Created a new article

symfony · weaverryan · Mar 24, 2014 · Feb 28, 2014 · Mar 1, 2014 · Mar 1, 2014
commit e13795114c37b5085bf7c57fb79cce6a6cb57571
diff --git a/components/console/commands_as_services.rst b/components/console/commands_as_services.rst
@@ -0,0 +1,118 @@
+.. index::
+    single: Console; Commands as Services
+
+How to define Commands as Services
+==================================
+
+.. versionadded:: 2.4
+   Support for registering commands in the service container was added 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:
+
+* what if you want your command to be defined elsewhere than in the ``Command``
+  folder?
+* what if you want to register conditionally your command, depending on the
+  current environment or on the availability of some dependencies?
+* what if you need to access dependencies before the ``setContainer`` is called
+  (for example in the ``configure`` method)?
+* what if you want to 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">
+
+            <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')
+        ;
+
+Here are some use cases.
+
+Use dependencies and parameters in configure
+--------------------------------------------
+
+For example, imagine you want to provide a default value for the ``name``
+argument. You could:
+
+* hard code a string and pass it as the 4th argument of ``addArgument``;
+* allow the user to set the default value in the configuration;
+* retrieve the default value from a service (a repository for example).
+
+With a ``ContainerAwareCommand`` you wouldn't be able to retrieve the
+configuration parameter, because the ``configure`` method is called in the
+command's constructor. The only solution is to inject them through its
+constructor:
+
+    <?php
+    // 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\InputArgument;
+    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')
+                ->addArgument('name', InputArgument::OPTIONAL, 'Who do you want to greet?', $defaultName)
+            ;
+        }
+
+        protected function execute(InputInterface $input, OutputInterface $output)
+        {
+            $name = $input->getArgument('name');
+
+            $output->writeln($name);
+        }
+    }
diff --git a/components/console/index.rst b/components/console/index.rst
@@ -6,6 +6,7 @@ Console
 
     introduction
     usage
+    commands_as_services
     single_command_tool
     events
     helpers/index
diff --git a/cookbook/console/console_command.rst b/cookbook/console/console_command.rst
@@ -62,80 +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.
-
-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.
-
-If you want to, you can instead register them as services in the 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::
-
-    Commands as services can be useful in few situations:
-
-    * if you need your commands to be defined somewhere else than in the
-      ``Command`` folder;
-    * if you need to register the command conditionally (depending on the
-      environment or presence of some dependencies);
-    * ou want to reuse the command with a different service or different
-      configuration, without having to extend the command - you could just
-      define a second service with the same class;
-    * if you need to access services or configuration parameters in the
-      ``configure`` method.
-
-    For example, imagine you want to provide a default value for the ``name``
-    option. You could hard code a string and pass it as the 4th argument of
-    ``addArgument``, or you could allow the user to set the default value in the
-    configuration.
-
-    With a ``ContainerAwareCommand`` you wouldn't be able to retrieve the
-    configuration parameter, because the ``configure`` method is called in the
-    command's constructor. The only solution is to inject them through its
-    constructor.
-
 Getting Services from the Service Container
 -------------------------------------------