Handling Signals in Laravel Console Commands

Earlier this month the Laravel documentation got an update with console signal handling feature inherited through a console signals feature added to the Symfony console component in v5.2:

Thanks to development by the upstream Symfony team, Artisan inherits a cool signal handling feature. Decided to document it today! ❤️ 🤝 pic.twitter.com/4IG3ZdWGTI

— Taylor Otwell 🪐 (@taylorotwell) April 1, 2021

From the Symfony blog post introducing console signals, it explains the background behind what a signal is as well as how you can respond to them in console commands:

Signals are an inter-process communication mechanism used by console commands. A signal is an asynchronous notification sent to a process (or to a specific thread within the same process) in order to notify it of an event that occurred. For example, when you press Ctrl + C in a command, the operating system sends the SIGINT signal to it.

Symfony 5.2 introduces support for responding to signals in your commands (e.g. to perform some cleanup tasks when quitting a command). If you want to handle some signals in a command, implement the new SignalableCommandInterface.

Handling signals could be helpful if you need to shut down or restart a service in response to a console command. Any cleanup required should be handled through signal when quitting a command.

Here's an example from the Laravel documentation, where all you need to do is implement the provided SignalableCommandInterface:

use Symfony\Component\Console\Command\SignalableCommandInterface;

class StartServer extends Command implements SignalableCommandInterface
{
    // ...

    /**
     * Get the list of signals handled by the command.
     *
     * @return array
     */
    public function getSubscribedSignals(): array
    {
        return [SIGINT, SIGTERM];
    }

    /**
     * Handle an incoming signal.
     *
     * @param  int  $signal
     * @return void
     */
    public function handleSignal(int $signal): void
    {
        if ($signal === SIGINT) {
            $this->stopServer();

            return;
        }
    }
}

The above interface is easy enough to introduce signal handling in your console commands; however, Freek Van der Herten wrote a laravel-signal-aware-command package designed to ease the work even further:

Using the Spatie signal-aware package, you can handle signals in a few ways (besides the above implementation, which directly implements the interface):

1. On an individual command
2. Via the Signal facade that ships with the signal-aware package
3. Via the SignalReceived event

Here's a quick example using the signal-aware package class to extend an individual console command:

use Spatie\SignalAwareCommand\SignalAwareCommand;

class YourCommand extends SignalAwareCommand
{
    protected $signature = 'your-command';

    public function handle()
    {
        $this->info('Command started...');

        sleep(100);
    }

    public function onSigint()
    {
        // will be executed when you stop the command
    
        $this->info('You stopped the command!');
    }
}

As you can see, extending the SignalAwareCommand, you can define the signal handlers you are interested in responding to.

#Learn More

You can learn more about signal handling in the Artisan console documentation.

The Console signals (Symfony Blog) is another resource to learn more about how these are implemented in the symfony/console package. Finally, check out Spatie's laravel-signal-aware-command package to quickly integrate signal handling in Laravel.

Freek also live-streamed Creating the Laravel Signal Aware Command package if you're interested in seeing him write the code for this package: