feat: add new CLI command for make custom UserModel

Author: datamweb

docs/concepts.md

@@ -25,11 +25,19 @@ on the standard Config class if nothing is found in the database.
 ## User Providers
 
 You can use your own models to handle user persistence. Shield calls this the "User Provider" class. A default model
-is provided for you at `CodeIgniter\Shield\Models\UserModel`. You can change this in the `Config\Auth::$userProvider` setting.
+is provided for you at `CodeIgniter\Shield\Models\UserModel`. You can change this in the `Config\Auth->userProvider` setting.
 The only requirement is that your new class MUST extend the provided `UserModel`.
 
+Shield has a CLI command to quickly create a custom `MyUserModel` by running the following command in terminal:
+
+```console
+php spark shield:model MyUserModel
+```
+
+You should set `Config\Auth::$userProvider` as follows:
+
 ```php
-public string $userProvider = UserModel::class;
+public string $userProvider = \App\Models\MyUserModel::class;
 ```
 
 ## User Identities

src/Commands/Generators/UserModelGenerator.php

@@ -0,0 +1,77 @@
+<?php
+
+declare(strict_types=1);
+
+namespace CodeIgniter\Shield\Commands\Generators;
+
+use CodeIgniter\CLI\BaseCommand;
+use CodeIgniter\CLI\GeneratorTrait;
+
+/**
+ * Generates a skeleton command file.
+ */
+class UserModelGenerator extends BaseCommand
+{
+    use GeneratorTrait;
+
+    /**
+     * The Command's Group
+     *
+     * @var string
+     */
+    protected $group = 'Shield';
+
+    /**
+     * The Command's Name
+     *
+     * @var string
+     */
+    protected $name = 'shield:model';
+
+    /**
+     * The Command's Description
+     *
+     * @var string
+     */
+    protected $description = 'Generates a new UserModel file.';
+
+    /**
+     * The Command's Usage
+     *
+     * @var string
+     */
+    protected $usage = 'shield:model <name> [options]';
+
+    /**
+     * The Command's Arguments
+     *
+     * @var array<string, string>
+     */
+    protected $arguments = [
+        'name' => 'The model class name.',
+    ];
+
+    /**
+     * The Command's Options
+     *
+     * @var array<string, string>
+     */
+    protected $options = [
+        '--namespace' => 'Set root namespace. Default: "APP_NAMESPACE".',
+        '--suffix'    => 'Append the component title to the class name (e.g. User => UserModel).',
+        '--force'     => 'Force overwrite existing file.',
+    ];
+
+    /**
+     * Actually execute a command.
+     */
+    public function run(array $params): void
+    {
+        $this->component = 'Model';
+        $this->directory = 'Models';
+        $this->template  = 'usermodel.tpl.php';
+
+        $this->classNameLang = 'CLI.generator.className.model';
+        $this->execute($params);
+    }
+}

src/Commands/Generators/Views/usermodel.tpl.php

@@ -0,0 +1,20 @@
+<@php
+
+declare(strict_types=1);
+
+namespace {namespace};
+
+use CodeIgniter\Shield\Models\UserModel;
+
+class {class} extends UserModel
+{
+    protected function initialize(): void
+    {
+        $this->allowedFields = [
+            ...$this->allowedFields,
+            // Add here your custom fields
+            // 'first_name',
+        ];
+    }
+}
+

src/Config/Registrar.php

@@ -45,4 +45,13 @@ public static function Toolbar(): array
             ],
         ];
     }
+
+    public static function Generators(): array
+    {
+        return [
+            'views' => [
+                'shield:model' => 'CodeIgniter\Shield\Commands\Generators\Views\usermodel.tpl.php',
+            ],
+        ];
+    }
 }

tests/Commands/UserModelGeneratorTest.php

@@ -0,0 +1,100 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Commands;
+
+use CodeIgniter\Test\CIUnitTestCase;
+use CodeIgniter\Test\Filters\CITestStreamFilter;
+
+/**
+ * @internal
+ */
+final class UserModelGeneratorTest extends CIUnitTestCase
+{
+    protected $streamFilter;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+
+        CITestStreamFilter::$buffer = '';
+        $this->streamFilter         = stream_filter_append(STDOUT, 'CITestStreamFilter');
+        $this->streamFilter         = stream_filter_append(STDERR, 'CITestStreamFilter');
+    }
+
+    protected function tearDown(): void
+    {
+        parent::tearDown();
+
+        stream_filter_remove($this->streamFilter);
+        $result = str_replace(["\033[0;32m", "\033[0m", "\n"], '', CITestStreamFilter::$buffer);
+
+        $filepath = str_replace('APPPATH' . DIRECTORY_SEPARATOR, APPPATH, trim(substr($result, 14)));
+        if (is_file($filepath)) {
+            unlink($filepath);
+        }
+    }
+
+    protected function getFileContents(string $filepath): string
+    {
+        if (! file_exists($filepath)) {
+            return '';
+        }
+
+        return file_get_contents($filepath) ?: '';
+    }
+
+    public function testGenerateUserModel(): void
+    {
+        command('shield:model MyUserModel');
+        $filepath = APPPATH . 'Models/MyUserModel.php';
+
+        $this->assertStringContainsString('File created: ', CITestStreamFilter::$buffer);
+        $this->assertFileExists($filepath);
+
+        $this->assertStringContainsString('namespace App\Models;', $this->getFileContents($filepath));
+        $this->assertStringContainsString('class MyUserModel extends UserModel', $this->getFileContents($filepath));
+        $this->assertStringContainsString('use CodeIgniter\Shield\Models\UserModel;', $this->getFileContents($filepath));
+        $this->assertStringContainsString('protected function initialize(): void', $this->getFileContents($filepath));
+    }
+
+    public function testGenerateUserModelCustomNamespace(): void
+    {
+        command('shield:model MyUserModel --namespace CodeIgniter\\\\Shield');
+        $filepath = HOMEPATH . 'src/Models/MyUserModel.php';
+
+        $this->assertStringContainsString('File created: ', CITestStreamFilter::$buffer);
+        $this->assertFileExists($filepath);
+
+        $this->assertStringContainsString('namespace CodeIgniter\Shield\Models;', $this->getFileContents($filepath));
+        $this->assertStringContainsString('class MyUserModel extends UserModel', $this->getFileContents($filepath));
+        $this->assertStringContainsString('use CodeIgniter\Shield\Models\UserModel;', $this->getFileContents($filepath));
+        $this->assertStringContainsString('protected function initialize(): void', $this->getFileContents($filepath));
+
+        if (is_file($filepath)) {
+            unlink($filepath);
+        }
+    }
+
+    public function testGenerateUserModelWithForce(): void
+    {
+        command('shield:model MyUserModel');
+
+        command('shield:model MyUserModel --force');
+        $this->assertStringContainsString('File overwritten: ', CITestStreamFilter::$buffer);
+
+        $filepath = APPPATH . 'Models/MyUserModel.php';
+        $this->assertFileExists($filepath);
+    }
+
+    public function testGenerateUserModelWithSuffix(): void
+    {
+        command('shield:model MyUser --suffix');
+        $filepath = APPPATH . 'Models/MyUserModel.php';
+
+        $this->assertStringContainsString('File created: ', CITestStreamFilter::$buffer);
+        $this->assertFileExists($filepath);
+        $this->assertStringContainsString('class MyUserModel extends UserModel', $this->getFileContents($filepath));
+    }
+}