Weave Code
Lock Laravel Package
roadrunner-php/lock
PHP integration for the RoadRunner Lock plugin, enabling fast, lightweight distributed lock management in high-traffic apps and microservices. Acquire, release, and manage locks with optional blocking waits via a simple RPC-based API. Requires PHP 8.1+.
Distributed locks for PHP applications backed by the RoadRunner lock plugin: acquire, release, extend and inspect read and write locks over RPC
Frequently asked questions about Lock
- How do I integrate RoadRunner Lock with Laravel’s queue system to prevent race conditions in job execution?
- First, ensure RoadRunner is running with the `lock` plugin enabled. Bind the `Lock` service in Laravel’s `config/app.php` or a service provider. Then, use the `Lock` facade or service to acquire locks before executing critical sections in your jobs. For example, wrap job logic in a `try-finally` block to release locks automatically, even if the job fails.
- What Laravel versions and PHP versions does this package support?
- This package supports Laravel 8.x–10.x and PHP 8.1+. It’s fully backward-compatible with existing Laravel applications, assuming RoadRunner is already deployed. No breaking changes were introduced in recent updates, so upgrades are safe if you’re within these version ranges.
- Do I need to manually configure RoadRunner to use this lock package?
- Yes, RoadRunner must be configured with the `lock` plugin enabled in your `rr.yaml` or `rr.json` config file. The package itself doesn’t handle this—it assumes RoadRunner is already set up with the plugin. Check the [RoadRunner docs](https://roadrunner.dev) for plugin configuration details.
- Can I use this package for non-RoadRunner Laravel applications, or is it strictly tied to RoadRunner?
- This package is **strictly tied to RoadRunner**. It won’t work without RoadRunner running as a dependency. If you’re not using RoadRunner, consider alternatives like `predis/predis` (for Redis-based locks) or Laravel’s built-in `Cache::lock()` for simpler use cases.
- How do I handle lock timeouts or deadlocks in production?
- Set a `ttl` (time-to-live) when acquiring locks to avoid deadlocks, e.g., `$lock->lock('resource', ttl: 10)`. Always release locks in a `finally` block or use Laravel’s `try-catch-finally` to ensure locks are freed. Monitor long-running jobs to detect potential deadlocks early.
- Are there any performance implications of using RoadRunner Lock compared to other solutions like Redis locks?
- RoadRunner Lock is optimized for RoadRunner’s worker model and avoids external dependencies like Redis, making it lightweight. Performance depends on your backend (e.g., filesystem or Redis via RoadRunner). Benchmark against your specific use case, but expect low overhead for typical Laravel job coordination.
- How do I test lock functionality in a Laravel test environment?
- Mock the `Lock` service in your tests using Laravel’s `Mockery` or `PHPUnit`. Simulate concurrent requests by running tests in parallel (e.g., with `pest` or `phpunit --parallel`). Verify locks are acquired/released correctly by checking job execution order and resource state.
- What happens if RoadRunner crashes while a lock is held?
- Locks may become orphaned if RoadRunner crashes before releasing them. To mitigate this, use short `ttl` values and ensure your application logic handles lock expiration gracefully. RoadRunner’s stability (e.g., proper shutdown signals) also reduces this risk.
- Can I use this package with Laravel’s Horizon queue worker?
- No, this package is designed for RoadRunner workers only. Horizon uses Supervisor and a different architecture, so it’s incompatible. If you’re using Horizon, consider Redis-based locks (e.g., `predis/predis`) or Laravel’s `Cache::lock()` instead.
- How do I migrate from manual locking (e.g., `flock`) to RoadRunner Lock in an existing Laravel app?
- Replace all `flock` or `sem_acquire` calls with `Lock` service calls. Start with non-critical sections, then gradually migrate to RoadRunner Lock. Use a feature flag or config setting to toggle between old and new locking mechanisms during the transition.
Weaver
How can I help you explore Laravel packages today?