minor #8269 [Console] Commands auto-registration is deprecated (GuilhemN)

xabbuh · xabbuh · commit a50892c7a190 · 2017-09-03T10:17:45.000+02:00
This PR was squashed before being merged into the 3.4 branch (closes #8269). Discussion ---------- [Console] Commands auto-registration is deprecated Document symfony/symfony#23805. I wonder, should I update https://github.com/symfony/symfony-docs/blob/17d1c39298e9415886e2c712748d3021ed7865a4/bundles/best_practices.rst L122 (`Command/ Yes`) ? As it is not really mandatory to use the `Command/` directory anymore. Commits ------- 493ae89 [Console] Commands auto-registration is deprecated
diff --git a/console.rst b/console.rst
@@ -12,11 +12,11 @@ use it to create your own commands.
 Creating a Command
 ------------------
 
-Commands are defined in classes which must be created in the ``Command`` namespace
-of your bundle (e.g. ``AppBundle\Command``) and their names must end with the
+Commands are defined in classes which should be created in the ``Command`` namespace
+of your bundle (e.g. ``AppBundle\Command``) and their names should end with the
 ``Command`` suffix.
 
-For example, a command called ``CreateUser`` must follow this structure::
+For example, you may want a command to create a user::
 
     // src/AppBundle/Command/CreateUserCommand.php
     namespace AppBundle\Command;
@@ -64,12 +64,28 @@ method. Then you can optionally define a help message and the
 Executing the Command
 ---------------------
 
-After configuring the command, you can execute it in the terminal:
+Symfony registers any PHP class extending :class:`Symfony\\Component\\Console\\Command\\Command`
+as a console command automatically. So you can now execute this command in the
+terminal:
 
 .. code-block:: terminal
 
     $ php bin/console app:create-user
 
+.. note::
+
+    If you're using the :ref:`default services.yml configuration <service-container-services-load-example>`,
+    your command classes are automatically registered as services.
+
+    You can also manually register your command as a service by configuring the service
+    and :doc:`tagging it </service_container/tags>` with ``console.command``.
+
+.. caution::
+
+    Symfony also looks in the ``Command/`` directory of bundles for commands
+    non registered as a service but this is deprecated since Symfony 3.4 and
+    won't be supported in Symfony 4.0.
+
 As you might expect, this command will do nothing as you didn't write any logic
 yet. Add your own logic inside the ``execute()`` method, which has access to the
 input stream (e.g. options and arguments) and the output stream (to write
diff --git a/console/commands_as_services.rst b/console/commands_as_services.rst
@@ -5,9 +5,13 @@ How to Define Commands as Services
 ==================================
 
 If you're using the :ref:`default services.yml configuration <service-container-services-load-example>`,
-your command classes are already registered as services. Great! This is the recommended
-setup, but it's not required. Symfony also looks in the ``Command/`` directory of
-each bundle and automatically registers those classes as commands.
+your command classes are already registered as services. Great! This is the
+recommended setup.
+
+Symfony also looks in the ``Command/`` directory of each bundle for commands
+non registered as a service and automatically registers those classes as
+commands. However this auto-registration was deprecated in Symfony 3.4. In
+Symfony 4.0, commands won't be auto-registered anymore.
 
 .. note::
 
