Skip to content

dmitry-ivanov/laravel-console-mutex

Folders and files

NameName
Last commit message
Last commit date

Latest commit

2f81517 · Jul 14, 2018
Sep 1, 2017
Dec 25, 2017
Jan 24, 2018
Nov 4, 2016
May 24, 2016
Dec 15, 2016
Feb 18, 2018
May 24, 2016
Jul 14, 2018
Jul 14, 2018
Jul 14, 2018
Sep 8, 2017

Repository files navigation

Laravel Console Mutex

StyleCI Build Status Coverage Status

Latest Stable Version Latest Unstable Version Total Downloads License

The mutex for Laravel console commands.

Laravel Console Mutex
5.1.* 5.1.*
5.2.* 5.2.*
5.3.* 5.3.*
5.4.* 5.4.*
5.5.* 5.5.*
5.6.* 5.6.*

Example

Table of contents

Usage

  1. Install package through composer:

    composer require illuminated/console-mutex
  2. Use Illuminated\Console\WithoutOverlapping trait:

    use Illuminated\Console\WithoutOverlapping;
    
    class ExampleCommand extends Command
    {
        use WithoutOverlapping;
    
        // ...
    }

Strategies

Overlapping can be prevented by various strategies:

  • file (default)
  • mysql
  • redis
  • memcached

Default file strategy is fine for small applications, which are deployed on a single server. If your application is more complex and deployed on several nodes, then you probably would like to use another mutex strategy.

You can change the mutex strategy by specifying $mutexStrategy field:

class ExampleCommand extends Command
{
    use WithoutOverlapping;

    protected $mutexStrategy = 'mysql';

    // ...
}

Or by using setMutexStrategy method:

class ExampleCommand extends Command
{
    use WithoutOverlapping;

    public function __construct()
    {
        parent::__construct();

        $this->setMutexStrategy('mysql');
    }

    // ...
}

Advanced

Set custom timeout

By default, the mutex is checking for a running command, and if it finds such, it just exits. However, you can manually set the timeout for a mutex, so it can wait for another command to finish its execution, instead of just quitting immediately.

You can change the mutex timeout by specifying $mutexTimeout field:

class ExampleCommand extends Command
{
    use WithoutOverlapping;

    protected $mutexTimeout = 3000; // milliseconds

    // ...
}

Or by using setMutexTimeout method:

class ExampleCommand extends Command
{
    use WithoutOverlapping;

    public function __construct()
    {
        parent::__construct();

        $this->setMutexTimeout(3000); // milliseconds
    }

    // ...
}

There are three possible options for $mutexTimeout field:

  • 0 - check without waiting (default);
  • {milliseconds} - check, and wait for a maximum of milliseconds specified;
  • null - wait, till running command finish its execution;

Handle several commands

Sometimes it is useful to set common mutex for several commands. You can easily achieve this by setting them the same mutex name. By default, mutex name is generated based on a command's name and arguments.

To change this, override getMutexName method in your command:

class ExampleCommand extends Command
{
    use WithoutOverlapping;

    public function getMutexName()
    {
        return "icmutex-for-command1-and-command2";
    }

    // ...
}

Custom mutex file storage

If you're using file strategy, mutex files will be stored in the storage/app folder, by default.

You can change the storage folder by overriding getMutexFileStorage method in your command:

class ExampleCommand extends Command
{
    use WithoutOverlapping;

    public function getMutexFileStorage()
    {
        return storage_path('my/custom/path');
    }

    // ...
}

Troubleshooting

Trait included, but nothing happens?

Note, that WithoutOverlapping trait is overriding initialize method:

trait WithoutOverlapping
{
    protected function initialize(InputInterface $input, OutputInterface $output)
    {
        $this->initializeMutex();
    }

    // ...
}

If your command is overriding initialize method too, then you should call initializeMutex method by yourself:

class ExampleCommand extends Command
{
    use WithoutOverlapping;

    protected function initialize(InputInterface $input, OutputInterface $output)
    {
        $this->initializeMutex();

        $this->foo = $this->argument('foo');
        $this->bar = $this->argument('bar');
        $this->baz = $this->argument('baz');
    }

    // ...
}

Several traits conflict?

If you're using another illuminated/console-% package, then you can find yourself getting into the "traits conflict".

For example, if you're trying to build loggable command, which is protected against overlapping:

class ExampleCommand extends Command
{
    use Loggable;
    use WithoutOverlapping;

    // ...
}

You'll get the fatal error - the traits conflict, because of both of these traits are overriding initialize method:

If two traits insert a method with the same name, a fatal error is produced, if the conflict is not explicitly resolved.

Override initialize method by yourself, and initialize traits in required order:

class ExampleCommand extends Command
{
    use Loggable;
    use WithoutOverlapping;

    protected function initialize(InputInterface $input, OutputInterface $output)
    {
        $this->initializeMutex();
        $this->initializeLogging();
    }

    // ...
}