Merge branch '5.3' into 5.4

javiereguiluz · javiereguiluz · commit 2620b497de88 · 2021-09-23T16:48:06.000+02:00
* 5.3:
  [Console] Add docs for ConsoleSignalEvent
diff --git a/components/console/events.rst b/components/console/events.rst
@@ -154,4 +154,75 @@ Listeners receive a
     It is then dispatched just after the ``ConsoleEvents::ERROR`` event.
     The exit code received in this case is the exception code.
 
+The ``ConsoleEvents::SIGNAL`` Event
+-----------------------------------
+
+**Typical Purposes**: To perform some actions after the command execution was interrupted.
+
+`Signals`_ are asynchronous notifications sent to a process in order to notify
+it of an event that occurred. For example, when you press ``Ctrl + C`` in a
+command, the operating system sends the ``SIGINT`` signal to it.
+
+When a command is interrupted, Symfony dispatches the ``ConsoleEvents::SIGNAL``
+event. Listen to this event so you can perform some actions (e.g. logging some
+results, cleaning some temporary files, etc.) before finishing the command execution.
+
+Listeners receive a
+:class:`Symfony\\Component\\Console\\Event\\ConsoleSignalEvent` event::
+
+    use Symfony\Component\Console\ConsoleEvents;
+    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!";
+        }
+    });
+
+.. tip::
+
+    All the available signals (``SIGINT``, ``SIGQUIT``, etc.) are defined as
+    `constants of the PCNTL PHP extension`_.
+
+If you use the Console component inside a Symfony application, commands can
+handle signals themselves. To do so, implement the
+``SignalableCommandInterface`` and subscribe to one or more signals::
+
+    // src/Command/SomeCommand.php
+    namespace App\Command;
+
+    use Symfony\Component\Console\Command\Command;
+    use Symfony\Component\Console\Command\SignalableCommandInterface;
+
+    class SomeCommand extends Command implements SignalableCommandInterface
+    {
+        // ...
+
+        public function getSubscribedSignals(): array
+        {
+            // return here any of the constants defined by PCNTL extension
+            return [\SIGINT, \SIGTERM];
+        }
+
+        public function handleSignal(int $signal)
+        {
+            if (\SIGINT === $signal) {
+                // ...
+            }
+
+            // ...
+        }
+    }
+
+.. versionadded:: 5.2
+
+    The ``ConsoleSignalEvent`` and ``SignalableCommandInterface`` classes were
+    introduced in Symfony 5.2.
+
 .. _`reserved exit codes`: https://www.tldp.org/LDP/abs/html/exitcodes.html
+.. _`Signals`: https://en.wikipedia.org/wiki/Signal_(IPC)
+.. _`constants of the PCNTL PHP extension`: https://www.php.net/manual/en/pcntl.constants.php
