Update CLI generator documentation

Author: paulbalandan

user_guide_src/source/cli/cli_generators.rst

@@ -33,7 +33,7 @@ Creates a new spark command.
 
 Usage:
 ======
-.. code-block:: none
+::
 
     make:command <name> [options]
 
@@ -46,7 +46,29 @@ Options:
 * ``--command``: The command name to run in spark. Defaults to ``command:name``.
 * ``--group``: The group/namespace of the command. Defaults to ``CodeIgniter`` for basic commands, and ``Generators`` for generator commands.
 * ``--type``: The type of command, whether a ``basic`` command or a ``generator`` command. Defaults to ``basic``.
-* ``-n``: Set the root namespace. Defaults to value of ``APP_NAMESPACE``.
+* ``--namespace``: Set the root namespace. Defaults to value of ``APP_NAMESPACE``.
+* ``--suffix``: Append the component suffix to the generated class name.
+* ``--force``: Set this flag to overwrite existing files on destination.
+
+make:config
+-----------
+
+Creates a new config file.
+
+Usage:
+======
+::
+
+    make:config <name> [options]
+
+Argument:
+=========
+* ``name``: The name of the config class. **[REQUIRED]**
+
+Options:
+========
+* ``--namespace``: Set the root namespace. Defaults to value of ``APP_NAMESPACE``.
+* ``--suffix``: Append the component suffix to the generated class name.
 * ``--force``: Set this flag to overwrite existing files on destination.
 
 make:controller
@@ -56,7 +78,7 @@ Creates a new controller file.
 
 Usage:
 ======
-.. code-block:: none
+::
 
     make:controller <name> [options]
 
@@ -68,7 +90,8 @@ Options:
 ========
 * ``--bare``: Extends from ``CodeIgniter\Controller`` instead of ``BaseController``.
 * ``--restful``: Extends from a RESTful resource. Choices are ``controller`` and ``presenter``. Defaults to ``controller``.
-* ``-n``: Set the root namespace. Defaults to value of ``APP_NAMESPACE``.
+* ``--namespace``: Set the root namespace. Defaults to value of ``APP_NAMESPACE``.
+* ``--suffix``: Append the component suffix to the generated class name.
 * ``--force``: Set this flag to overwrite existing files on destination.
 
 make:entity
@@ -78,7 +101,7 @@ Creates a new entity file.
 
 Usage:
 ======
-.. code-block:: none
+::
 
     make:entity <name> [options]
 
@@ -88,8 +111,9 @@ Argument:
 
 Options:
 ========
-* ``-n``: Set the root namespace. Defaults to value of ``APP_NAMESPACE``.
-* ``-force``: Set this flag to overwrite existing files on destination.
+* ``--namespace``: Set the root namespace. Defaults to value of ``APP_NAMESPACE``.
+* ``--suffix``: Append the component suffix to the generated class name.
+* ``--force``: Set this flag to overwrite existing files on destination.
 
 make:filter
 -----------
@@ -98,7 +122,7 @@ Creates a new filter file.
 
 Usage:
 ======
-.. code-block:: none
+::
 
     make:filter <name> [options]
 
@@ -108,7 +132,8 @@ Argument:
 
 Options:
 ========
-* ``-n``: Set the root namespace. Defaults to value of ``APP_NAMESPACE``.
+* ``--namespace``: Set the root namespace. Defaults to value of ``APP_NAMESPACE``.
+* ``--suffix``: Append the component suffix to the generated class name.
 * ``--force``: Set this flag to overwrite existing files on destination.
 
 make:model
@@ -118,7 +143,7 @@ Creates a new model file.
 
 Usage:
 ======
-.. code-block:: none
+::
 
     make:model <name> [options]
 
@@ -129,9 +154,10 @@ Argument:
 Options:
 ========
 * ``--dbgroup``: Database group to use. Defaults to ``default``.
-* ``--entity``: Set this flag to use an entity class as the return type.
+* ``--return``: Set the return type from ``array``, ``object``, or ``entity``. Defaults to ``array``.
 * ``--table``: Supply a different table name. Defaults to the pluralized class name.
-* ``-n``: Set the root namespace. Defaults to value of ``APP_NAMESPACE``.
+* ``--namespace``: Set the root namespace. Defaults to value of ``APP_NAMESPACE``.
+* ``--suffix``: Append the component suffix to the generated class name.
 * ``--force``: Set this flag to overwrite existing files on destination.
 
 make:seeder
@@ -141,7 +167,7 @@ Creates a new seeder file.
 
 Usage:
 ======
-.. code-block:: none
+::
 
     make:seeder <name> [options]
 
@@ -151,7 +177,8 @@ Argument:
 
 Options:
 ========
-* ``-n``: Set the root namespace. Defaults to value of ``APP_NAMESPACE``.
+* ``--namespace``: Set the root namespace. Defaults to value of ``APP_NAMESPACE``.
+* ``--suffix``: Append the component suffix to the generated class name.
 * ``--force``: Set this flag to overwrite existing files on destination.
 
 make:migration
@@ -161,7 +188,7 @@ Creates a new migration file.
 
 Usage:
 ======
-.. code-block:: none
+::
 
     make:migration <name> [options]
 
@@ -171,30 +198,13 @@ Argument:
 
 Options:
 ========
-* ``-n``: Set the root namespace. Defaults to value of ``APP_NAMESPACE``.
+* ``--session``: Generate a migration file for database sessions.
+* ``--table``: Set the table name to use for database sessions. Defaults to ``ci_sessions``.
+* ``--dbgroup``: Set the database group for database sessions. Defaults to ``default`` group.
+* ``--namespace``: Set the root namespace. Defaults to value of ``APP_NAMESPACE``.
+* ``--suffix``: Append the component suffix to the generated class name.
 * ``--force``: Set this flag to overwrite existing files on destination.
 
-session:migration
------------------
-
-Generates the migration file for database sessions.
-
-Usage:
-======
-.. code-block:: none
-
-    session:migration [options]
-
-Options:
-========
-* ``-g``: Set the database group.
-* ``-t``: Set the table name. Defaults to ``ci_sessions``.
-* ``-n``: Set the root namespace. Defaults to value of ``APP_NAMESPACE``.
-* ``--force``: Set this flag to overwrite existing files on destination.
-
-.. note:: When running ``php spark help session:migration``, you will see that it has the argument ``name`` listed.
-    This argument is not used as the class name is derived from the table name passed to the ``-t`` option.
-
 .. note:: Do you need to have the generated code in a subfolder? Let's say if you want to create a controller
     class to reside in the ``Admin`` subfolder of the main ``Controllers`` folder, you will just need
     to prepend the subfolder to the class name, like this: ``php spark make:controller admin/login``. This
@@ -203,14 +213,15 @@ Options:
 
 .. note:: Working on modules? Code generation will set the root namespace to a default of ``APP_NAMESPACE``.
     Should you need to have the generated code elsewhere in your module namespace, make sure to set
-    the ``-n`` option in your command, e.g., ``php spark make:model blog -n Acme\Blog``.
+    the ``--namespace`` option in your command, e.g., ``php spark make:model blog --namespace Acme\Blog``.
 
-.. warning:: Make sure when setting the ``-n`` option that the supplied namespace is a valid namespace
-    defined in your ``$psr4`` array in ``Config\Autoload`` or defined in your composer autoload file.
-    Otherwise, a ``RuntimeException`` will be thrown.
+.. warning:: Make sure when setting the ``--namespace`` option that the supplied namespace is a valid
+    namespace defined in your ``$psr4`` array in ``Config\Autoload`` or defined in your composer autoload
+    file. Otherwise, code generation will be interrupted.
 
 .. warning:: Use of ``migrate:create`` to create migration files is now deprecated. It will be removed in
-    future releases. Please use ``make:migration`` as replacement.
+    future releases. Please use ``make:migration`` as replacement. Also, please use ``make:migration --session``
+    to use instead of the deprecated ``session:migration``.
 
 ****************************************
 Scaffolding a Complete Set of Stock Code
@@ -234,122 +245,15 @@ will create the following classes:
 
 (1) ``App\Controllers\User``;
 (2) ``App\Models\User``;
-(3) ``App\Entities\User``;
-(4) ``App\Database\Migrations\<some date here>_User``; and
-(5) ``App\Database\Seeds\User``.
-
-****************
-GeneratorCommand
-****************
-
-All generator commands must extend ``GeneratorCommand`` to fully utilize its methods that are used in code
-generation. While some of the methods are already functional, you may have the need to customize or upgrade
-what each method does. You can do so as all methods have protected visibility, except for the ``run()`` method
-which is public and need not be overridden as it is essentially complete.
-
-.. php:class:: CodeIgniter\\CLI\\GeneratorCommand
-
-    .. php:method:: getClassName()
-
-        :rtype: string
-
-        Gets the class name from input. This can be overridden if name is really
-        required by providing a prompt.
-
-    .. php:method:: sanitizeClassName(string $class)
-
-        :param string $class: Class name.
-        :rtype: string
-
-        Trims input, normalize separators, and ensures all paths are in Pascal case.
-
-    .. php:method:: qualifyClassName(string $class)
-
-        :param string $class: Class name.
-        :rtype: string
-
-        Parses the class name and checks if it is already fully qualified.
-
-    .. php:method:: getRootNamespace()
-
-        :rtype: string
-
-        Gets the root namespace from input. Defaults to value of ``APP_NAMESPACE``.
-
-    .. php:method:: getNamespacedClass(string $rootNamespace, string $class)
-
-        :param string $rootNamespace: The root namespace of the class.
-        :param string $class: Class name
-        :returns: The fully qualified class name
-        :rtype: string
-
-        Gets the qualified class name. This should be implemented.
-
-    .. php:method:: buildPath(string $class)
-
-        :param string $class: The fully qualified class name
-        :returns: The absolute path to where the class will be saved.
-        :rtype: string
-        :throws: RuntimeException
-
-        Builds the file path from the class name.
-
-    .. php:method:: modifyBasename(string $filename)
-
-        :param string $filename: The basename of the file path.
-        :returns: A modified basename for the file.
-        :rtype: string
-
-        Provides last chance for child generators to change the file's basename before saving.
-        This is useful for migration files where the basename has a date component.
-
-    .. php:method:: buildClassContents(string $class)
-
-        :param string $class: The fully qualified class name.
-        :rtype: string
-
-        Builds the contents for class being generated, doing all the replacements necessary in the template.
-
-    .. php:method:: getTemplate()
-
-        :rtype: string
-
-        Gets the template for the class being generated. This must be implemented.
-
-    .. php:method:: getNamespace(string $class)
-
-        :param string $class: The fully qualified class name.
-        :rtype: string
-
-        Retrieves the namespace part from the fully qualified class name.
-
-    .. php:method:: setReplacements(string $template, string $class)
-
-        :param string $template: The template string to use.
-        :param string $class: The fully qualified class name.
-        :returns: The template string with all annotations replaced.
-        :rtype: string
-
-        Performs all the necessary replacements.
-
-    .. php:method:: sortImports(string $template)
-
-        :param string $template: The template file.
-        :returns: The template file with all imports already sorted.
-        :rtype: string
-
-        Alphabetically sorts the imports for a given template.
-
-.. warning:: Child generators should make sure to implement ``GeneratorCommand``'s two abstract methods:
-    ``getNamespacedClass`` and ``getTemplate``, or else you will get a PHP fatal error.
+(3) ``App\Database\Migrations\<some date here>_User``; and
+(4) ``App\Database\Seeds\User``.
 
-.. note:: ``GeneratorCommand`` has the default argument of ``['name' => 'Class name']``. You can
-    override the description by supplying the name in your ``$arguments`` property, e.g., ``['name' => 'Module class name']``.
+To include an ``Entity`` class in the scaffolded files, just include the ``--return entity`` to the command
+and it will be passed to the model generator.
 
-.. note:: ``GeneratorCommand`` has the default options of ``-n`` and ``--force``. Child classes cannot override
-    these two properties as they are crucial in the implementation of the code generation.
+**************
+GeneratorTrait
+**************
 
-.. note:: Generators are default listed under the ``Generators`` namespace because it is the default group
-    name in ``GeneratorCommand``. If you want to have your own generator listed elsewhere under a different
-    namespace, you will just need to provide the ``$group`` property in your child generator,
-    e.g., ``protected $group = 'CodeIgniter';``.
+All generator commands must use the ``GeneratorTrait`` to fully utilize its methods that are used in code
+generation.