Repository files navigation

Mutex for Laravel Console Commands.

• Usage
• Strategies
• Advanced
  • Set custom timeout
  • Handle multiple commands
  • Set custom storage folder
• Troubleshooting
  • Trait included, but nothing happens?
  • Several traits conflict?
• Sponsors
• License

1. Install the package via Composer:

   composer require illuminated/console-mutex

2. UseIlluminated\Console\WithoutOverlapping trait:

   useIlluminated\Console\WithoutOverlapping;class ExampleCommandextends Command{use WithoutOverlapping;// ...}

Mutex can prevent overlapping by using various strategies:

• file (default)
• mysql
• redis
• memcached

The defaultfile strategy is acceptable for small applications, which are deployed on a single server.If your application is more complex and deployed on several nodes, you should consider using another mutex strategy.

You can change strategy by using the$mutexStrategy field:

class ExampleCommandextends Command{use WithoutOverlapping;protectedstring$mutexStrategy ='mysql';// ...}

Or by using thesetMutexStrategy() method:

class ExampleCommandextends Command{use WithoutOverlapping;publicfunction__construct()    {parent::__construct();$this->setMutexStrategy('mysql');    }// ...}

By default, if mutex sees that the command is already running, it will immediately quit.You can change that behavior by setting a timeout in which mutex can wait for another running command to finish its execution.

You can set the timeout by specifying the$mutexTimeout field:

class ExampleCommandextends Command{use WithoutOverlapping;// In millisecondsprotected ?int$mutexTimeout =3000;// ...}

Or by using thesetMutexTimeout() method:

class ExampleCommandextends Command{use WithoutOverlapping;publicfunction__construct()    {parent::__construct();// In milliseconds$this->setMutexTimeout(3000);    }// ...}

Here's how the$mutexTimeout field is treated:

• 0 - no waiting (default);
• {int} - wait for the given number of milliseconds;
• null - wait for the running command to finish its execution;

Sometimes it might be useful to have a shared mutex for multiple commands.You can easily achieve that by setting the same mutex name for all of those commands.

You should use thegetMutexName() method for that:

class ExampleCommandextends Command{use WithoutOverlapping;publicfunctiongetMutexName()    {return'shared-for-command1-and-command2';    }// ...}

If you're using thefile strategy, mutex files would be stored in thestorage/app folder.

You can change that by overriding thegetMutexFileStorage() method:

class ExampleCommandextends Command{use WithoutOverlapping;publicfunctiongetMutexFileStorage()    {returnstorage_path('my/custom/path');    }// ...}

WithoutOverlapping trait overrides theinitialize() method:

trait WithoutOverlapping{protectedfunctioninitialize(InputInterface$input,OutputInterface$output)    {$this->initializeMutex();parent::initialize($input,$output);    }// ...}

If your command overrides theinitialize() method too, you have to call theinitializeMutex() method by yourself:

class ExampleCommandextends Command{use WithoutOverlapping;protectedfunctioninitialize(InputInterface$input,OutputInterface$output)    {// You have to call it first$this->initializeMutex();// Then goes your custom code$this->foo =$this->argument('foo');$this->bar =$this->argument('bar');$this->baz =$this->argument('baz');    }// ...}

If you're using anotherilluminated/console-% package, you'll get the "traits conflict" error.

For example, if you're building aloggable command, which doesn't allow overlapping:

class ExampleCommandextends Command{use Loggable;use WithoutOverlapping;// ...}

You'll get the traits conflict, because both of those traits are overriding theinitialize() method:

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

To fix that - override theinitialize() method and resolve the conflict:

class ExampleCommandextends Command{use Loggable;use WithoutOverlapping;protectedfunctioninitialize(InputInterface$input,OutputInterface$output)    {// Initialize conflicting traits$this->initializeMutex();$this->initializeLogging();    }// ...}

Laravel Console Mutex is open-sourced software licensed under theMIT license.