Signal Handler Laravel Package

Getting Started

Start by installing the package via Composer:

composer require seld/signal-handler

The core use case is handling OS signals (e.g., SIGINT, SIGTERM) in CLI scripts to enable graceful shutdown — especially useful for long-running workers, daemons, or console commands. Create a handler with SignalHandler::create(), register callbacks for signals, and keep the returned instance alive (critical on PHP 8.0+). For example:

use Seld\Signal\SignalHandler;

$handler = SignalHandler::create();
$handler->register(SIGINT, fn() => $this->shutdown());
$handler->register(SIGTERM, fn() => $this->shutdown());

while ($job = $this->fetchJob()) {
    $this->process($job);
}

Note: Signal handling silently fails on Windows (except SIGINT/SIGTERM on PHP 7.4+), making it safe for cross-platform code.

Implementation Patterns

• Worker/Process Lifecycles: Ideal for long-running processes (e.g., queue consumers, WebSocket servers) where you need to clean up resources (DB connections, locks, caches) before exiting.
• Integration with Symfony Console: Register handlers inside Command::execute() to handle Ctrl+C during extended runs, preventing orphaned processes or corrupted state.
• Stacking Handlers: Multiple handlers can coexist (e.g., app-level + library-level handlers). The library manages nesting and cleanup safely — no need to manually unregister previous handlers.
• Exit Integration: Use exitWithLastSignal() after signal handling to ensure the process exits with the signal number (e.g., exit(SignalHandler::SIGNAL_SIGTERM) → exit code 143), which is picked up by process supervisors.
• Dependency Injection: Pass SignalHandler as a service in Laravel console commands or workers, instantiated once per process. Avoid creating/disposing repeatedly during request lifecycle.

Gotchas and Tips

• Critical: PHP 8.0+ Garbage Collection — You must store the SignalHandler instance in a persistent variable (e.g., class property or top-level variable). If it falls out of scope, the weak reference is GC’d and handlers never fire. Common pitfall: creating it inside a method without assigning to $this->signalHandler.
• Ticks Not Needed (PHP 7.1+) — This package uses async signal handling internally. You can safely remove declare(ticks=1); from your code (it was required in older versions).
• Windows Limitations — Only SIGINT and SIGTERM work on Windows (PHP 7.4+), and only in CLI. GUI mode or older PHP versions cause silent no-ops — ideal for "best-effort" signal handling across platforms.
• unregister() is destructive — Calling it clears all signals for that handler instance (no arguments needed since v2.0). If you need selective unregistration, store separate handler instances.
• Type Safety — Since v2.0.1, type annotations are correct (fixed in phpstan), so IDE autocompletion and static analysis work reliably for SignalHandler::create().
• No Signal on Windows非CLI — If testing signal handling on Windows, always use php -S or php artisan serve + separate terminal (not web requests) to verify SIGINT/SIGTERM.