Laravel Signal Aware Command Laravel Package

Getting Started

1. Install via Composer: composer require spatie/laravel-signal-aware-command
2. Extend Spatie\SignalAwareCommand\BaseSignalAwareCommand in your artisan command instead of Command
3. Register your signal listeners in the handle() method using $this->onSignal()
4. First use case: Implement a long-running worker loop that exits cleanly on SIGTERM — no orphaned processes or unflushed state.

protected function handle()
{
    $this->onSignal(SIGTERM, fn () => $this->info('Shutting down gracefully...'));

    while ($this->shouldRun) {
        // Process jobs...
        usleep(100_000);
    }
}

Implementation Patterns

• Centralized shutdown logic: Define reusable cleanup handlers (e.g., closing DB connections, saving state) in a trait or base command, then override only signal-specific behavior.
• Progress-aware shutdown: Combine signal handling with checkpoints — e.g., save progress to DB before terminating:

  $this->onSignal(SIGTERM, fn () => $this->saveCheckpointAndExit());
  

• Graceful worker shutdown: For queue-consumer-style tasks, set a flag (e.g., $this->shouldRun = false) inside the signal callback to break the main loop.
• Signal fallbacks: Wrap critical sections with $this->protectFromSignal() to prevent interruption during atomic operations (e.g., file writes).
• Testing: Use $command->simulateSignal(SIGTERM) in tests to validate shutdown behavior without spawning actual processes.

Gotchas and Tips

• Windows compatibility: Only limited signal support (e.g., no SIGTERM/SIGINT on Windows CLI); test on target environment or use env-based fallbacks.
• Synchronous signal delivery: Signals are processed only when PHP execution is interruptible (e.g., during sleep, usleep, or I/O). Long CPU-bound loops may ignore signals — use pcntl_signal_dispatch() manually if needed.
• Signal handler order matters: Later handlers override earlier ones for the same signal unless you use the prepend option in onSignal().
• Avoid closures with references: Closure-based handlers captured in loops may leak memory — prefer class methods or injected services.
• Check PHP extensions: Requires pcntl and posix extensions — ensure php artisan -V runs without warnings.
• Extend with middleware: Use custom middleware to wrap signal-aware commands (e.g., for metrics or logging around shutdown).