Rewords and tweaks

Author: javiereguiluz

components/console/events.rst

@@ -153,16 +153,19 @@ Listeners receive a
     This event is also dispatched when an exception is thrown by the command.
     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.
 
-After the command has been interrupted, the ``ConsoleEvents::SIGNAL`` event is
-dispatched. It can be used to do any actions
-(to log or profile commands / to perform some cleanup tasks when quitting a command).
+`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::
@@ -180,9 +183,46 @@ Listeners receive a
         }
     });
 
-.. versionadded:: 5.2
+.. 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;
 
-    The ``ConsoleSignalEvent`` class was introduced in Symfony 5.2.
+    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