Repository files navigation

Mutex for Laravel console commands.

• Usage
• Strategies
• Advanced
  • Set custom timeout
  • Handle several commands
  • Custom mutex file storage
• Troubleshooting
  • Trait included, but nothing happens?
  • Several traits conflict?
• License

1. Install the package via Composer:

   composer require"illuminated/console-mutex:^6.0"

2. UseIlluminated\Console\WithoutOverlapping trait:

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

Overlapping can be prevented by various strategies:

• file (default)
• mysql
• redis
• memcached

Defaultfile 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 ExampleCommandextends Command{use WithoutOverlapping;protected$mutexStrategy ='mysql';// ...}

Or by usingsetMutexStrategy method:

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

By default, the mutex is checking for a running command, and if it finds such, it just exits. However, you can manuallyset 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 ExampleCommandextends Command{use WithoutOverlapping;protected$mutexTimeout =3000;// milliseconds// ...}

Or by usingsetMutexTimeout method:

class ExampleCommandextends Command{use WithoutOverlapping;publicfunction__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;

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, overridegetMutexName method in your command:

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

If you're usingfile strategy, mutex files will be stored in thestorage/app folder, by default.

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

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

Note, thatWithoutOverlapping trait is overridinginitialize method:

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

If your command is overridinginitialize method too, then you should callinitializeMutex method by yourself:

class ExampleCommandextends Command{use WithoutOverlapping;protectedfunctioninitialize(InputInterface$input,OutputInterface$output)    {$this->initializeMutex();$this->foo =$this->argument('foo');$this->bar =$this->argument('bar');$this->baz =$this->argument('baz');    }// ...}

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

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

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

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

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

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

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

The MIT License. Please seeLicense File for more information.