A simple cross-platform¹ signal handler.

¹ Windows support is only possible on PHP 7.4+ and only supports catching SIGINT/SIGBREAK (ctrl+c / ctrl+break respectively). On older PHP versions it will simply silently fail to work on Windows so you can use it but signals will just interrupt PHP as if the library was not in use.

Note: To maximize cross-platform support all signals are available as constants on the SignalHandler class and it is recommended to use those instead of the PHP constants as the constants are not available on all platforms.

use Seld\Signal\SignalHandler;

$signal = SignalHandler::create();

while (true) {
    // do some work here ...

    // exit gracefully at the end of an iteration if the process interruption was called for
    if ($signal->isTriggered()) {
        $signal->exitWithLastSignal();
    }
}

If you create multiple SignalHandler instances they will be kept on a stack and only the top-most / last created one will be triggered when a signal comes in.

When you unregister the top one the previous one becomes active again, etc.

For this to work well however you need to make sure you properly unregister the signal handler when you are done with it. On PHP 8.0+ this is done automatically whenever the signal handler is garbage collected as the stack uses WeakReference instances to keep track of the handlers. On PHP 7 however you need to call $signal->unregister(); explicitly to remove it from the global handler stack.

Typically it would look something like this if you need PHP 7 support:

use Seld\Signal\SignalHandler;

$signal = SignalHandler::create();

try {
    // do things
} finally {
    $signal->unregister();
}

use Seld\Signal\SignalHandler;

// using strings for the constant names makes sure the code will run on Windows and
// OSX even if the signal is missing on those platforms
$signal = SignalHandler::create([SignalHandler::SIGHUP, SignalHandler::SIGUSR1]);

while (true) {
    // do some work here ...

    // reload the config when the signal was triggered
    if ($signal->isTriggered()) {
        $this->reloadConfiguration();

        // reset the handler so next time you check isTriggered() it
        // will be false, until SIGHUP/SIGUSR1 is signaled again
        $signal->reset();
    }
}

use Seld\Signal\SignalHandler;

$signal = SignalHandler::create(null, new PSR3Logger());

use Seld\Signal\SignalHandler;

$signal = SignalHandler::create([SignalHandler::SIGINT], function (string $signalName, SignalHandler $self) {
    echo 'Received ' . $signalName . PHP_EOL;

    // you can optionally receive the SignalHandler instance as second arg to do things on it like
    // resetting its state or exiting to handle the signal
    $self->reset();
    $self->exitWithLastSignal();
});

Warning: As described above on PHP 8.0+ this library uses weak references to keep track of the handlers, so if you do not store the result of ::create() into a variable that you keep around as long as you need the handler, it will not work and your callback function will never be called.

For a quick install with Composer use:

$ composer require seld/signal-handler

• PHP 7.2+ (or PHP 5.4+ for v1 which is EOL now)

Bugs and feature request are tracked on GitHub

Jordi Boggiano - j.boggiano@seld.be - http://twitter.com/seldaek

signal-handler is licensed under the MIT License - see the LICENSE file for details