Handling console signals in Laravel

Original – Apr 5th 2021 by Freek Van der Herten – 7 minute read

When you cancel a long-running artisan command with Ctrl+C, a SIGINT signal is sent by the operating system to the PHP process. You can use this signal to perform some cleanup quickly.

Symfony 5.2 introduced support for handling signals in commands.

We've released a package called spatie/laravel-signal-aware-commands that provides a substantial improvement to how you can use these signals in a Laravel app. In this blog post, I'd like to tell you all about it.

Handling signals in Laravel

As Laravel's artisan commands are based on Symfony, signals can be handled in Laravel as well. You should simply add the SignableCommandInterface and implement the getSubscribedSignals and handleSignal methods.

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

That's basically all you need to do to make commands signal aware, but it doesn't feel very "Laravel-y" to me.

Ideally, I just want to add a function like onSigint to the command and put the signal handling code there. That feels much lighter.

// in an artisan command class

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!');
}

Something that I found lacking in the code that Symfony provides is that only the command itself is aware of signals. Wouldn't it be nice if we could handle signals anywhere in the app, like this?

Signal::handle(SIGINT, function() {
   // handle the signal
});

This seemed like a nice thing for me to work on, so I decided to create a package that would add these niceties.

In this stream, you can see me build the foundations of spatie/laravel-signal-aware-command

Using Signal aware commands

Making commands signal aware is easy. When the package is installed, there are three ways to handle signals:

on the command itself
via the Signal facade
using the SignalReceived event

Let's start with making a command signal aware. You need to let your command extend SignalAwareCommand. Next, define a method that starts with on followed by the name of the signal. Here's an example where the SIGINT signal is handled.

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!');
    }
}

The above code will make the command signal aware. But what if you want to handle signals in other parts of your code? In that case, you can use the Signal facade. First, you need to define the signals you want to handle in your command in the handlesSignals property.

use Spatie\SignalAwareCommand\SignalAwareCommand;

class YourCommand extends SignalAwareCommand
{
    protected $signature = 'your-command';
    
    protected $handlesSignals = [SIGINT];

    public function handle()
    {
        (new SomeOtherClass())->performSomeWork();

        sleep(100);
    }
}

In any class you'd like, you can use the Signal facade to register code that should be executed when a signal is received.

use Illuminate\Console\Command;
use Spatie\SignalAwareCommand\Facades\Signal;

class SomeOtherClass
{
    public function performSomeWork()
    {
        Signal::handle(SIGINT, function(Command $commandThatReceivedSignal) {
            $commandThatReceivedSignal->info('Received the SIGINT signal!');
        })
    }
}

You can call clearHandlers if you want to remove a handler that was previously registered.

use Spatie\SignalAwareCommand\Facades\Signal;

public function performSomeWork()
{
    Signal::handle(SIGNINT, function() {
        // perform cleanup
    });
    
    $this->doSomeWork();
    
    // at this point doSomeWork was executed without any problems
    // running a cleanup isn't necessary anymore
    Signal::clearHandlers(SIGINT);
}

To clear all handlers for all signals use Signal::clearHandlers().

A third way of handling signal is by listening for the SignalReceived event.

use Spatie\SignalAwareCommand\Events\SignalReceived;
use Spatie\SignalAwareCommand\Signals;

class SomeOtherClass
{
    public function performSomeWork()
    {
        Event::listen(function(SignalReceived $event) {
            $signalNumber = $event->signal;
            
            $signalName = Signals::getSignalName($signalNumber);
        
            $event->command->info("Received the {$signalName} signal");
        });
    }
}

I hope you agree that these three ways of handling signals feels much better than adding the SignableCommandInterface and implement the getSubscribedSignals and handleSignal yourself.

A practical example

To see a practical example of this package, can take a look at this commit in the laravel-backup package.

The laravel-backup package creates a backup in the form of a zip file that contains DB dumps and a selection of files. This zip is created inside of a temporary directory. Should the user cancel a running backup command, we'll not use the SIGINT signal to delete that temporary directory.

Pretty nice, right?

Question: why haven't you PR'ed this to Laravel?

After creating the package, some people have asked why I didn't immediately PR this to Laravel. The answer is that creating a package is much faster for me to do. When creating a package, I basically have a blank canvas. I can implement functionality in whichever fashion I want. I can also make use of PHP 8 features. When the package is finished, I can immediately tag a release and start using it.

If I would PR this to Laravel, I would keep Laravel's coding practices in mind, use an older version of PHP. The PR would probably be in review for a couple of days without the guarantee of actually being merged.

The above paragraph isn't a criticism on Laravel. It's just the way it is. It's good that things are getting review and that there is a discussion on features that are added.

I hope that by creating a package, somebody from the community or the Laravel team takes the time to PR some of the functionality to Laravel, making my package obsolete.

Until that happens, you can use my package.

Question: why are you letting users extend a class

Right now, the package requires you to extend the SignalAwareCommand command instead of the regularCommand. Some people frown upon this, and rightly so. Putting functionality in base classes is some cases not flexible, and in the Laravel world, it seems that use traits is preferred. Generally speaking, I prefer this too, as a class can only be extended from one other class, but you can have as many traits as you want.

In this case, I opted for the package offering an abstract SignalAwareCommand that should be extended instead of a trait because this way, other parts of the code could be hidden.

Let's imagine the package would offer a trait instead of a base class. This is would people would have to use it.

class TestCommand extends Command
{
    use HandlesSignals;
    
    public function __construct()
    {
        parent::construct();
        
        // signals must be known when the command is constructed
        $this->registerSignalsToBeHandled();
    }
    
    public function handle()
    {
        $this->registerSignalHandlers();
        
        // your code
    }
}

In my mind, this would undermine the better DX that the package tries to achieve.

I bet that if the ideas of this package make it into Laravel, that the necessary changes could be added directly into Illuminate\Console\Command, making DX even better.

In closing

To know more about spatie/laravel-signal-aware-command, head over the the readme on GitHub.

This isn't the first package our team has created. Here's a list of packages we released previously. I'm pretty sure there's something there for your next project.

If you want to support our team creating open-source, consider becoming a sponsor, or picking up one of our paid products.

Freek.dev