[Console] Command as service

components/console/commands_as_services.rst

@@ -0,0 +1,117 @@
+.. index::
+    single: Console; Commands as Services
+
+How to Define Commands as Services
+==================================
+
+.. versionadded:: 2.4
+   Support for registering commands in the service container was introduced in
+   version 2.4.
+
+By default, Symfony will take a look in the ``Command`` directory of your
+bundles and automatically register your commands. For the ones implementing
+the ``ContainerAwareCommand`` interface, Symfony will even inject the container.
+While making life easier, this default implementation has some drawbacks in some
+situations:
+
+* Define the command elsewhere than in the ``Command`` directory;
+* Conditionally register your command, depending on the current environment or
+  on the availability of some dependencies;
+* Access dependencies before the ``setContainer()`` is called (for example in
+  the ``configure()`` method);
+* Reuse a command many times, but with different dependencies or parameters
+
+To solve those problems, you can register your command as a service by simply
+defining it with the ``console.command`` tag:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # app/config/config.yml
+        services:
+            acme_hello.command.my_command:
+                class: Acme\HelloBundle\Command\MyCommand
+                tags:
+                    -  { name: console.command }
+
+    .. code-block:: xml
+
+        <!-- app/config/config.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">
+
+            <services>
+                <service id="acme_hello.command.my_command"
+                    class="Acme\HelloBundle\Command\MyCommand">
+                    <tag name="console.command" />
+                </service>
+            </services>
+        </container>
+
+    .. code-block:: php
+
+        // app/config/config.php
+        $container
+            ->register('acme_hello.command.my_command', 'Acme\HelloBundle\Command\MyCommand')
+            ->addTag('console.command')
+        ;
+
+Using Dependencies and Parameters to Set Default Values for Options
+-------------------------------------------------------------------
+
+Imagine you want to provide a default value for the ``name``option. You could
+pass one of the following as the 5th argument of ``addOption()``:
+
+* an hardcoded string;
+* a value coming from the configuration (allows the user to change it easily);
+* a value computed by a service (e.g. a repository).
+
+With a ``ContainerAwareCommand`` you wouldn't be able to retrieve the
+configuration parameter, because the ``configure()`` method is called in the
+constructor. The only solution is to inject them::
+
+    // src/Acme/DemoBundle/Command/GreetCommand.php
+    namespace Acme\DemoBundle\Command;
+
+    use Acme\DemoBundle\Entity\NameRepository;
+    use Symfony\Component\Console\Command\Command;
+    use Symfony\Component\Console\Input\InputInterface;
+    use Symfony\Component\Console\Input\InputOption;
+    use Symfony\Component\Console\Output\OutputInterface;
+
+    class GreetCommand extends Command
+    {
+        protected $nameRepository;
+
+        public function __construct(NameRepository $nameRepository)
+        {
+            $this->nameRepository = $nameRepository;
+        }
+
+        protected function configure()
+        {
+            $defaultName = $this->nameRepository->findLastOne();
+
+            $this
+                ->setName('demo:greet')
+                ->setDescription('Greet someone')
+                ->addOption('name', '-n', InputOption::VALUE_REQUIRED, 'Who do you want to greet?', $defaultName)
+            ;
+        }
+
+        protected function execute(InputInterface $input, OutputInterface $output)
+        {
+            $name = $input->getOption('name');
+
+            $output->writeln($name);
+        }
+    }
+
+.. caution::
+
+    When running the console, every command is instantiated, which means every
+    ``configure()`` method is called. Be careful with database queries, as
+    they could impact performance.

components/console/index.rst

@@ -6,6 +6,7 @@ Console
 
     introduction
     usage
+    commands_as_services
     single_command_tool
     events
     helpers/index

components/console/introduction.rst

@@ -527,6 +527,7 @@ Learn More!
 * :doc:`/components/console/usage`
 * :doc:`/components/console/single_command_tool`
 * :doc:`/components/console/events`
+* :doc:`/components/console/commands_as_services`
 
 .. _Packagist: https://packagist.org/packages/symfony/console
 .. _ANSICON: https://github.com/adoxa/ansicon/releases

cookbook/console/console_command.rst

@@ -62,59 +62,6 @@ This command will now automatically be available to run:
 
     $ app/console demo:greet Fabien
 
-.. _cookbook-console-dic:
-
-Register Commands in the Service Container
-------------------------------------------
-
-.. versionadded:: 2.4
-   Support for registering commands in the service container was added in
-   version 2.4.
-
-Instead of putting your command in the ``Command`` directory and having Symfony
-auto-discover it for you, you can register commands in the service container
-using the ``console.command`` tag:
-
-.. configuration-block::
-
-    .. code-block:: yaml
-
-        # app/config/config.yml
-        services:
-            acme_hello.command.my_command:
-                class: Acme\HelloBundle\Command\MyCommand
-                tags:
-                    -  { name: console.command }
-
-    .. code-block:: xml
-
-        <!-- app/config/config.xml -->
-        <?xml version="1.0" encoding="UTF-8" ?>
-        <container xmlns="http://symfony.com/schema/dic/services"
-            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">
-
-            <service id="acme_hello.command.my_command"
-                class="Acme\HelloBundle\Command\MyCommand">
-                <tag name="console.command" />
-            </service>
-        </container>
-
-    .. code-block:: php
-
-        // app/config/config.php
-
-        $container
-            ->register('acme_hello.command.my_command', 'Acme\HelloBundle\Command\MyCommand')
-            ->addTag('console.command')
-        ;
-
-.. tip::
-
-    Registering your command as a service gives you more control over its
-    location and the services that are injected into it. But, there are no
-    functional advantages, so you don't need to register your command as a service.
-
 Getting Services from the Service Container
 -------------------------------------------