initial commit

vendor/symfony/maker-bundle/docs/index.rst

@@ -0,0 +1,166 @@
+The Symfony MakerBundle
+=======================
+
+Symfony Maker helps you create empty commands, controllers, form classes,
+tests and more so you can forget about writing boilerplate code. This bundle
+assumes you're using a standard Symfony directory structure, but many
+commands can generate code into any application.
+
+Installation
+------------
+
+Run this command to install and enable this bundle in your application:
+
+.. code-block:: terminal
+
+    $ composer require --dev symfony/maker-bundle
+
+Usage
+-----
+
+This bundle provides several commands under the ``make:`` namespace. List them
+all executing this command:
+
+.. code-block:: terminal
+
+    $ php bin/console list make
+
+     make:command            Creates a new console command class
+     make:controller         Creates a new controller class
+     make:entity             Creates a new Doctrine entity class
+
+     [...]
+
+     make:validator          Creates a new validator and constraint class
+     make:voter              Creates a new security voter class
+
+The names of the commands are self-explanatory, but some of them include
+optional arguments and options. Check them out with the ``--help`` option:
+
+.. code-block:: terminal
+
+    $ php bin/console make:controller --help
+
+.. caution::
+
+    ``make:entity`` requires ``doctrine/orm`` to be installed and configured. This maker support only ORM, not ODM.
+
+Linting Generated Code
+______________________
+
+MakerBundle uses php-cs-fixer to enforce coding standards when generating ``.php``
+files. When running a ``make`` command, MakerBundle will use a ``php-cs-fixer``
+version and configuration that is packaged with this bundle.
+
+You can explicitly set a custom path to a php-cs-fixer binary and/or configuration
+file by their respective environment variables:
+
+- ``MAKER_PHP_CS_FIXER_BINARY_PATH`` e.g. tools/vendor/bin/php-cs-fixer
+- ``MAKER_PHP_CS_FIXER_CONFIG_PATH`` e.g. .php-cs-fixer.config.php
+
+
+.. tip::
+
+    Is PHP-CS-Fixer installed globally? To avoid needing to set these in every
+    project, you can instead set these on your operating system.
+
+
+Configuration
+-------------
+
+This bundle doesn't require any configuration. But, you *can* override the default
+configuration:
+
+.. code-block:: yaml
+
+    # config/packages/maker.yaml
+    when@dev:
+        maker:
+            root_namespace: 'App'
+            generate_final_classes: true
+            generate_final_entities: false
+
+root_namespace
+~~~~~~~~~~~~~~
+
+**type**: ``string`` **default**: ``App``
+
+The root namespace used when generating all of your classes
+(e.g. ``App\Entity\Article``, ``App\Command\MyCommand``, etc). Changing
+this to ``Acme`` would cause MakerBundle to create new classes like
+(e.g. ``Acme\Entity\Article``, ``Acme\Command\MyCommand``, etc).
+
+generate_final_classes
+~~~~~~~~~~~~~~~~~~~~~~
+
+**type**: ``boolean`` **default**: ``true``
+
+By default, MakerBundle will generate all of your classes with the
+``final`` PHP keyword except for doctrine entities. Set this to ``false``
+to override this behavior for all maker commands.
+
+See https://www.php.net/manual/en/language.oop5.final.php
+
+.. code-block:: php
+
+    final class MyVoter
+    {
+        ...
+    }
+
+.. versionadded:: 1.61
+
+    ``generate_final_classes`` was introduced in MakerBundle 1.61
+
+
+generate_final_entities
+~~~~~~~~~~~~~~~~~~~~~~~
+
+**type**: ``boolean`` **default**: ``false``
+
+By default, MakerBundle will not generate any of your doctrine entity
+classes with the ``final`` PHP keyword. Set this to ``true``
+to override this behavior for all maker commands that create
+entities.
+
+See https://www.php.net/manual/en/language.oop5.final.php
+
+.. code-block:: php
+
+    #[ORM\Entity(repositoryClass: TaskRepository::class)]
+    final class Task extends AbstractEntity
+    {
+        ...
+    }
+
+.. versionadded:: 1.61
+
+    ``generate_final_entities`` was introduced in MakerBundle 1.61.
+
+Creating your Own Makers
+------------------------
+
+In case your applications need to generate custom boilerplate code, you can
+create your own ``make:...`` command reusing the tools provided by this bundle.
+To do that, you should create a class that extends
+`AbstractMaker`_ in your ``src/Maker/``
+directory. And this is really it!
+
+For examples of how to complete your new maker command, see the `core maker commands`_.
+Make sure your class is registered as a service and tagged with ``maker.command``.
+If you're using the standard Symfony ``services.yaml`` configuration, this
+will be done automatically.
+
+Overriding the Generated Code
+-----------------------------
+
+Generated code can never be perfect for everyone. The MakerBundle tries to balance
+adding "extension points" with keeping the library simple so that existing commands
+can be improved and new commands can be added.
+
+For that reason, in general, the generated code cannot be modified. In many cases,
+adding your *own* maker command is so easy, that we recommend that. However, if there
+is some extension point that you'd like, please open an issue so we can discuss!
+
+.. _`AbstractMaker`: https://github.com/symfony/maker-bundle/blob/main/src/Maker/AbstractMaker.php
+.. _`core maker commands`: https://github.com/symfony/maker-bundle/tree/main/src/Maker