From e0d1b355cf4e8d00231a91b16f4e2cc3bd82fa04 Mon Sep 17 00:00:00 2001
From: Jules Pietri <heahdude@yahoo.fr>
Date: Fri, 11 Aug 2023 17:26:11 +0200
Subject: [PATCH] [Console] Improve console events doc

---
 components/console/events.rst |  7 ++++---
 console.rst                   |  6 ++++++
 console/calling_commands.rst  | 34 +++++++++++++++++++++-------------
 3 files changed, 31 insertions(+), 16 deletions(-)

diff --git a/components/console/events.rst b/components/console/events.rst
index dc03a8a88d9..45f228e7399 100644
--- 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
index 28b560d1f9b..6f74c2e657e 100644
--- a/console.rst
+++ b/console.rst
@@ -574,6 +574,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
index 1a9cce4e6c3..35d388965ad 100644
--- 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::