Skip to content
Locking, the easy way
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


Build Status Latest Stable Version License Total Downloads Scrutinizer Code Quality

php-lock is a library that makes locking on resources easy. It can be used to avoid access to a file during write operations or to prevent crontabs to overlap. And it's designed to integrate well with Dependancy Injection (eg Symfony Container or Pimple).


With Composer :

composer require texthtml/php-lock


You can create an object that represent a lock on a file. You can then try to acquire that lock by calling $lock->acquire(). If the lock fail it will throw a \TH\Lock\Exception (useful for CLI tools built with Symfony Console Components documentation). If the lock is acquired the program can continue.

Locking a file exclusively

use TH\Lock\FileLock;

$lock = new FileLock('/path/to/file');


// other processes that try to acquire a lock on the file will fail

// edit /path/to/file


// other processes can now acquire a lock on the file

Sharing a lock on a file

use TH\Lock\FileLock;

$lock = new FileLock('/path/to/file', FileLock::SHARED);


// other processes that try to acquire an exclusive lock on the file will fail,
// processes that try to acquire an shared lock on the file will succeed

// read /path/to/file


// other processes can now acquire an exclusive lock on the file if no other shared lock remains.

Auto release

$lock->release() is called automatically when the lock is destroyed so you don't need to manually release it at the end of a script or if it got out of scope.

use TH\Lock\FileLock;

function batch() {
    $lock = new FileLock('/some/file');

    // lot of editing on file


// the lock will be released here even if $lock->release() is not called in batch()

Using lock for crontabs

When you don't want some crontabs to overlap you can make a lock on the same file in each crontab. The TH\Lock\LockFactory can ease the process and provide more helpful message in case of overlap.

$lock = $factory->create('protected resource', 'process 1');


// process 1 does stuff
$lock = $factory->create('protected resource', 'process 2');


// process 2 does stuff

When process 1 is running and we start process 2, an Exception will be thrown: "Could not acquire exclusive lock on protected resource" and if the factory was configured with a \Psr\Log\LoggerInterface, messages explaining what happend would be logged:

process 1: exclusive lock acquired on protected resource
process 2: could not acquire exclusive lock on protected resource
process 2: lock released on protected resource

The only LockFactory available at the moment is the TH\Lock\FileFactory. This factory autmatically create lock files for your resources in the specified folder.

use TH\Lock\FileFactory;

$factory = new FileFactory('/path/to/lock_dir/');
$lock = $factory->create('resource identifier');

Aggregating locks

If you want to simplify acquiring multiple locks at once, you can use the \TH\Lock\LockSet:

use TH\Lock\LockSet;

$superLock = new LockSet([$lock1, $lock2, $lock3]);
// You can make a set with any types of locks (eg: FileLock, RedisSimpleLock or another nested LockSet)


// all locks will be released when $superLock is destroyed or when `$superLock->release()` is called

It will try to acquire all locks, if it fails it will release the lock that have been acquired to avoid locking other processes.

note: Lock put inside a LockSet should not be used manually anymore


Distributed system

On a distributed system, file based locking does not work, You can use the php-lock redis extension to have a safe lock instead.

You can’t perform that action at this time.