README

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).

Installation

With Composer :

composer require texthtml/php-lock

Usage

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');

$lock->acquire();

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

// edit /path/to/file

$lock->release();

// 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);

$lock->acquire();

// 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

$lock->release();

// 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');
    $lock->acquire();

    // lot of editing on file
}

batch();

// 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');

$lock->acquire();

// process 1 does stuff

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

$lock->acquire();

// 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)

$superLock->acquire();

// 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

Notes

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.

texthtml / php-lock

Maintainers

Details