[9.x] Introducing Signal Traps 🚦

src/Illuminate/Console/Command.php

@@ -13,6 +13,7 @@ class Command extends SymfonyCommand
     use Concerns\CallsCommands,
         Concerns\HasParameters,
         Concerns\InteractsWithIO,
+        Concerns\InteractsWithSignals,
         Macroable;
 
     /**
@@ -120,9 +121,13 @@ public function run(InputInterface $input, OutputInterface $output): int
 
         $this->components = $this->laravel->make(Factory::class, ['output' => $this->output]);
 
-        return parent::run(
-            $this->input = $input, $this->output
-        );
+        try {
+            return parent::run(
+                $this->input = $input, $this->output
+            );
+        } finally {
+            $this->untrap();
+        }
     }
 
     /**

src/Illuminate/Console/Concerns/InteractsWithSignals.php

@@ -0,0 +1,49 @@
+<?php
+
+namespace Illuminate\Console\Concerns;
+
+use Illuminate\Console\Signals;
+use Illuminate\Support\Arr;
+
+trait InteractsWithSignals
+{
+    /**
+     * The signals instance, if any.
+     *
+     * @var \Illuminate\Console\Signals|null
+     */
+    protected $signals;
+
+    /**
+     * Sets a trap to be run when the given signal(s) occurs.
+     *
+     * @param  iterable<array-key, int>|int  $signals
+     * @param  callable  $callback
+     * @return void
+     */
+    public function trap($signals, $callback)
+    {
+        Signals::whenAvailable(function () use ($signals, $callback) {
+            $this->signals ??= new Signals(
+                $this->getApplication()->getSignalRegistry(),
+            );
+
+            collect(Arr::wrap($signals))
+                ->each(fn ($signal) => $this->signals->register($signal, $callback));
+        });
+    }
+
+    /**
+     * Untraps traps set by the command class.
+     *
+     * @return void
+     */
+    public function untrap()
+    {
+        if (! is_null($this->signals)) {
+            $this->signals->unregister();
+
+            $this->signals = null;
+        }
+    }
+}

src/Illuminate/Console/Signals.php

@@ -0,0 +1,132 @@
+<?php
+
+namespace Illuminate\Console;
+
+use Symfony\Component\Console\SignalRegistry\SignalRegistry;
+
+class Signals
+{
+    /**
+     * The signal registry instance.
+     *
+     * @var \Symfony\Component\Console\SignalRegistry\SignalRegistry
+     */
+    protected $registry;
+
+    /**
+     * The signal registry's previous list of handlers.
+     *
+     * @param array<int, array<int, callable>>|null
+     */
+    protected $previousHandlers;
+
+    /**
+     * Create a new Signals instance.
+     *
+     * @param  \Symfony\Component\Console\SignalRegistry\SignalRegistry  $registry
+     * @return void
+     */
+    public function __construct($registry)
+    {
+        $this->registry = $registry;
+
+        $this->previousHandlers = $this->getHandlers();
+    }
+
+    /**
+     * Registers a new signal handler.
+     *
+     * @param  int  $signal
+     * @param  callable  $callback
+     * @return void
+     */
+    public function register($signal, $callback)
+    {
+        $this->previousHandlers[$signal] ??= $this->initializeSignal($signal);
+
+        with($this->getHandlers(), function ($handlers) use ($signal) {
+            $handlers[$signal] ??= $this->initializeSignal($signal);
+
+            $this->setHandlers($handlers);
+        });
+
+        $this->registry->register($signal, $callback);
+
+        with($this->getHandlers(), function ($handlers) use ($signal) {
+            $lastHandlerInserted = array_pop($handlers[$signal]);
+            array_unshift($handlers[$signal], $lastHandlerInserted);
+
+            $this->setHandlers($handlers);
+        });
+    }
+
+    /**
+     * Unregister the current signals instance, and reverts
+     * the signal's registry handlers state.
+     *
+     * @return array<int, array<int, callable>>
+     */
+    public function unregister()
+    {
+        $this->setHandlers($this->previousHandlers);
+    }
+
+    /**
+     * Executes the given callback if "signals" are supported.
+     *
+     * @param  callable  $callback
+     * @return void
+     */
+    public static function whenAvailable($callback)
+    {
+        if (
+            app()->runningInConsole()
+            && ! app()->runningUnitTests()
+            && extension_loaded('pcntl')
+            && defined('SIGINT')
+            && SignalRegistry::isSupported()) {
+            $callback();
+        }
+    }
+
+    /**
+     * Set the registry's handlers.
+     *
+     * @param  array<int, array<int, callable>>  $handlers
+     * @return void
+     */
+    protected function setHandlers($handlers)
+    {
+        (fn () => $this->signalHandlers = $handlers)
+            ->call($this->registry);
+    }
+
+    /**
+     * Get the registry's handlers.
+     *
+     * @return array<int, array<int, callable>>
+     */
+    protected function getHandlers()
+    {
+        return (fn () => $this->signalHandlers)
+            ->call($this->registry);
+    }
+
+    /**
+     * Gets the signal's default callback on the array format.
+     *
+     * @return [callable]
+     */
+    protected function initializeSignal($signal)
+    {
+        $existingHandler = pcntl_signal_get_handler($signal);
+
+        return [is_callable($existingHandler)
+            ? $existingHandler
+            : function ($signal) {
+                if (! in_array($signal, [SIGUSR1, SIGUSR2])) {
+                    exit(0);
+                }
+            }, ];
+    }
+}