- What is yriveiro/php-fslock used for?
- yriveiro/php-fslock is a lightweight PHP library for filesystem-based locking that wraps PHP's native flock() function behind a simple acquire, release, and status-check API. It is designed for mutual exclusion between processes on the same host, such as CLI scripts, cron jobs, scheduled maintenance tasks, and single-node queue workers. It supports shared and exclusive locks plus timeout support so you can avoid indefinite blocking.
- How do I install yriveiro/php-fslock with Composer?
- Install it with composer require yriveiro/php-fslock. The package has no extension or external service requirements beyond PHP itself, so no additional infrastructure is needed. Because there is no Laravel service provider, facade, or config file, the recommended pattern is to wrap the library behind your own small LockService class and bind it in the container.
- Does yriveiro/php-fslock work with Laravel?
- It is framework-agnostic and not Laravel-native: there is no service provider, facade, config file, or published assets. You can use it inside Artisan commands, scheduled jobs, and local scripts, but you should wrap it in an internal service interface rather than calling it directly throughout your app. That wrapper also makes it easier to swap in Laravel cache or database locks later.
- Which versions of PHP and Laravel does php-fslock support?
- The 3.0.0 release declares a minimum PHP version of 7.x, but PHP 8.x support is not explicitly confirmed in the release notes, which matters if your Laravel estate runs 8.1 or later. Check the composer.json constraint and run the package's tests on your target runtime before adopting it. The library itself has no Laravel version dependency, so Laravel compatibility depends on your PHP version.
- How do I configure where php-fslock stores its lock files?
- Version 3.0.0 added a constructor parameter that lets you set the directory where lock files are stored, instead of accepting an implicit default path. Set this explicitly to an app-owned local directory or tmpfs with reliable flock semantics, and make sure every process on the host resolves exactly the same value. If two processes resolve different lock directories they will silently fail to exclude each other, and nothing will raise an error.
- Does php-fslock support timeouts and non-blocking lock acquisition?
- Yes. The library supports both blocking and non-blocking modes and includes timeout support to avoid indefinite blocking when acquiring a lock. For production use, always call blocking acquisition with a proven bounded timeout so a stuck process cannot hang a worker indefinitely. Combine that with a clear failure path when the lock cannot be acquired.
- Can I use php-fslock across multiple servers or Kubernetes replicas?
- No. flock is host-local and only coordinates processes that share the same filesystem view, so it cannot provide mutual exclusion across multiple nodes, autoscaled queue workers, or Kubernetes replicas. For distributed coordination, use Laravel cache locks backed by Redis or database atomic locks instead. Keep php-fslock for same-host tasks such as scheduled commands and local exports.
- Why did upgrading php-fslock to 3.0.0 break my code?
- Version 3.0.0 removed the destroy() method as a hard breaking change, and the release notes do not describe a deprecation path, so audit your usages before upgrading. The release also adds explicit return type declarations, meaning any application or vendor subclass overriding these methods must match the declared signatures or PHP will throw a fatal error. Re-run your test suite and check any mocking strategy after the upgrade.
- Are php-fslock filesystem locks reliable on NFS or container storage?
- flock is advisory and filesystem-dependent, and it is known to behave unreliably on NFS and on some overlay or container storage drivers. Prefer an app-controlled local directory or tmpfs for the lock path, especially in containerized deployments with read-only or ephemeral filesystems. Also confirm the default lock path is writable if you omit the new constructor parameter.
- What are the alternatives to php-fslock for locking in Laravel?
- Laravel's native cache locks backed by Redis or its database atomic locks cover most distributed use cases without adding a dependency. For host-local locking you can also consider symfony/lock or a small in-house flock wrapper. Because php-fslock is a low-visibility package with an unclear maintenance cadence, vendoring its small implementation is a reasonable fallback if PHP compatibility later breaks.