- What does illuminated/console-mutex do for Laravel console commands?
- illuminated/console-mutex adds an atomic, cache-backed lock around a Laravel Artisan command so two copies of the same command cannot run at the same time. It is a thin decorator over Laravel's console lifecycle and the Cache::lock() contract, so it adds no queue, daemon, schema, or new infrastructure. It is aimed at preventing duplicate jobs and race conditions in scheduled or manually triggered commands.
- How do I install illuminated/console-mutex?
- Install it with Composer by requiring illuminated/console-mutex in your Laravel project. There is essentially no configuration surface, so after installation you add the package's trait to the command you want to protect. Check the composer.json version constraints against your pinned Laravel and PHP versions before committing.
- How do I apply the mutex to an existing Artisan command?
- Add the provided trait to the Artisan command class you want to guard; it composes into the existing command without forcing a base-class change. The trait wires the command lifecycle to a cache lock, so the lock is acquired before the work starts and released afterward. Adoption can be done one command at a time and backed out per command.
- Which cache driver should I use for the lock in production?
- Use a cache store that provides a genuinely shared lock across every host that can run the command: Redis, Memcached, DynamoDB, or the database store are appropriate. The file cache store only locks locally, so on a multi-node deployment it silently provides no mutual exclusion. This is the single largest failure mode and it is a configuration mistake rather than a code defect.
- Does console-mutex work across multiple servers or container replicas?
- Yes, if the cache store is shared across all hosts. On a single-server setup the local file store technically works, but it provides no protection once you scale to multiple nodes or container replicas. Always verify that the production cache driver backs the lock with a shared store.
- Is illuminated/console-mutex redundant with Laravel's withoutOverlapping()?
- Not entirely. Laravel's scheduler has shipped withoutOverlapping() for years, and Cache::lock() is a first-class primitive, so if your only overlap risk is scheduler-driven commands the native answer is sufficient. The package's genuine differentiator is protecting commands invoked outside the scheduler, such as manual artisan runs, commands dispatched from jobs, deploy hooks, and ad-hoc operator invocations.
- What happens when a second copy of the command hits the lock?
- Contention must map to some exit status, and that policy should be chosen deliberately rather than left to chance. If contention maps to success, monitoring cannot distinguish a real run from a skipped one; if it maps to failure, you generate false alerts. The package supports common policies such as fail-fast, bounded wait, or skip-and-log, so align the choice with your observability stack.
- How should I choose the lock TTL for long-running commands?
- Choose a lock TTL that comfortably exceeds the command's worst-case runtime. If the expiry is shorter than a run, the lock evaporates mid-run and the exact overlap you were preventing can happen silently. Measure realistic worst-case durations, set the expiry with margin, and revisit it whenever the command's workload grows.
- What Laravel and PHP versions does illuminated/console-mutex support?
- The package targets supported Laravel applications on supported PHP versions, but you should verify the composer.json constraints against your pinned framework version before committing. With a low-star package, the version constraint is worth checking explicitly. There are no PHP extensions, PECL modules, Node tooling, or sidecars required.
- Is illuminated/console-mutex actively maintained and safe to depend on?
- It has roughly 147 GitHub stars and zero dependents, which means effectively no third-party production validation and no downstream pressure on the maintainer. The codebase is small enough to audit in an afternoon and can be adopted one command at a time, so the risk is manageable if you price it in. Keep in mind that a fallback trait of roughly 200 lines is a weekend project if the package goes stale.