minor #18741 [Console] Improve console events doc (HeahDude)

javiereguiluz · javiereguiluz · commit c82934fd9d33 · 2023-08-28T10:15:29.000+02:00
This PR was squashed before being merged into the 5.4 branch. Discussion ---------- [Console] Improve console events doc The docs currently state that running a command from another command does not dispatch events. This side effect can be avoided by using `$this->getApplication()->doRun()` and the command name as first argument of the input, instead of `$this->getApplication()->find(...)->run()`. Also, the events page is linked by the component doc, for better discoverability I added a short section to link it in the main page of `Console`. Commits ------- e0d1b35 [Console] Improve console events doc
diff --git a/components/console/events.rst b/components/console/events.rst
@@ -17,7 +17,8 @@ the wheel, it uses the Symfony EventDispatcher component to do the work::
 .. caution::
 
     Console events are only triggered by the main command being executed.
-    Commands called by the main command will not trigger any event.
+    Commands called by the main command will not trigger any event, unless
+    run by the application itself, see :doc:`/console/calling_commands`.
 
 The ``ConsoleEvents::COMMAND`` Event
 ------------------------------------
@@ -171,10 +172,10 @@ Listeners receive a
     use Symfony\Component\Console\Event\ConsoleSignalEvent;
 
     $dispatcher->addListener(ConsoleEvents::SIGNAL, function (ConsoleSignalEvent $event) {
-       
+
         // gets the signal number
         $signal = $event->getHandlingSignal();
-        
+
         if (\SIGINT === $signal) {
             echo "bye bye!";
         }
diff --git a/console.rst b/console.rst
@@ -585,6 +585,12 @@ registers an :doc:`event subscriber </event_dispatcher>` to listen to the
 :ref:`ConsoleEvents::TERMINATE event <console-events-terminate>` and adds a log
 message whenever a command doesn't finish with the ``0`` `exit status`_.
 
+Using Events And Handling Signals
+---------------------------------
+
+When a command is running, many events are dispatched, one of them allows to
+react to signals, read more in :doc:`this section </components/console/events>`.
+
 Learn More
 ----------
 
diff --git a/console/calling_commands.rst b/console/calling_commands.rst
@@ -8,13 +8,13 @@ or if you want to create a "meta" command that runs a bunch of other commands
 changed on the production servers: clearing the cache, generating Doctrine
 proxies, dumping web assets, ...).
 
-Use the :method:`Symfony\\Component\\Console\\Application::find` method to
-find the command you want to run by passing the command name. Then, create a
-new :class:`Symfony\\Component\\Console\\Input\\ArrayInput` with the
-arguments and options you want to pass to the command.
+Use the :method:`Symfony\\Component\\Console\\Application::doRun`. Then, create
+a new :class:`Symfony\\Component\\Console\\Input\\ArrayInput` with the
+arguments and options you want to pass to the command. The command name must be
+the first argument.
 
-Eventually, calling the ``run()`` method actually runs the command and returns
-the returned code from the command (return value from command's ``execute()``
+Eventually, calling the ``doRun()`` method actually runs the command and returns
+the returned code from the command (return value from command ``execute()``
 method)::
 
     // ...
@@ -29,15 +29,14 @@ method)::
 
         protected function execute(InputInterface $input, OutputInterface $output): int
         {
-            $command = $this->getApplication()->find('demo:greet');
-
-            $arguments = [
+            $greetInput = new ArrayInput([
+                // the command name is passed as first argument
+                'command' => 'demo:greet',
                 'name'    => 'Fabien',
                 '--yell'  => true,
-            ];
+            ]);
 
-            $greetInput = new ArrayInput($arguments);
-            $returnCode = $command->run($greetInput, $output);
+            $returnCode = $this->getApplication()->doRun($greetInput, $output);
 
             // ...
         }
@@ -47,7 +46,16 @@ method)::
 
     If you want to suppress the output of the executed command, pass a
     :class:`Symfony\\Component\\Console\\Output\\NullOutput` as the second
-    argument to ``$command->run()``.
+    argument to ``$application->doRun()``.
+
+.. note::
+
+    Using ``doRun()`` instead of ``run()`` prevents autoexiting and allows to
+    return the exit code instead.
+
+    Also, using ``$this->getApplication()->doRun()`` instead of
+    ``$this->getApplication()->find('demo:greet')->run()`` will allow proper
+    events to be dispatched for that inner command as well.
 
 .. caution::
 
