PCNTL Signals in CLI PHP

TL;DR

Explanation

pcntl_signal(SIGTERM, $handler) registers a callback for OS signals. Signals are checked at tick points (declare(ticks=1)) or via pcntl_signal_dispatch() in loops. Key signals: SIGTERM (graceful shutdown request), SIGINT (Ctrl+C), SIGUSR1/USR2 (custom), SIGHUP (reload config). Pattern for queue workers: set a flag on SIGTERM, check flag in loop, finish current task then exit cleanly. PHP-FPM manages its own signals separately. The pcntl extension is CLI-only — not available in FPM/web context. PHP 8.1: async signals via pcntl_async_signals(true) removes need for ticks.

Common Misconception

Why It Matters

Common Mistakes

• Not calling pcntl_signal_dispatch() in tight loops — signals accumulate but handler never fires.
• Using ticks=1 on every statement — performance overhead. Use pcntl_async_signals(true) instead.
• Handling SIGKILL — impossible to catch, always terminates immediately.

Code Examples

// Worker that can't shut down gracefully:
while (true) {
    $job = $queue->pop();
    processJob($job); // Killed mid-job on deploy
}

pcntl_async_signals(true); // PHP 8.1+ — no ticks needed
$running = true;
pcntl_signal(SIGTERM, function() use (&$running) {
    $running = false;
});
pcntl_signal(SIGINT, function() use (&$running) {
    $running = false;
});

while ($running) {
    $job = $queue->pop();
    if ($job) processJob($job); // Completes current job before exit
    else usleep(100000);
}

References

• ↗ https://www.php.net/manual/en/book.pcntl.php

Tags

Related Terms