README

A flexible PHP locking library designed to prevent race conditions in CLI and web environments. It provides a simple Locker class that delegates the actual locking mechanism to a LockHandlerInterface implementation.

Features

Simple API: Easy to use lock() and unlock() methods.
Handler Abstraction: Easily swap between different locking backends (e.g., FlockHandler for file-based locking).
Automatic Cleanup: Locks are automatically released when the Locker instance is destroyed or (optionally) on script shutdown.
Blocking & Non-Blocking: Supports both blocking (wait for lock) and non-blocking (fail immediately) modes.

Installation

composer require michel/lock

Usage

Basic Usage (Non-Blocking)

By default or when passing false as the second argument, the lock attempt is non-blocking. It returns false immediately if the lock is already held by another process.

<?php

use Michel\Lock\Locker;
use Michel\Lock\Handler\FlockHandler;

// 1. Create a handler (e.g., file-based locking)
$handler = new FlockHandler('/tmp/locks');

// 2. Instantiate the Locker
$locker = new Locker($handler);

// 3. Acquire a lock
// 'my_process' is the key.
// false = non-blocking mode (return false immediately if locked)
if ($locker->lock('my_process', false)) {
    echo "Lock acquired!\n";

    // Do some critical work...
    sleep(5);

    // 4. Release the lock
    $locker->unlock('my_process');
} else {
    echo "Could not acquire lock. Another process is running.\n";
}

Blocking Mode (Wait for Lock)

If you want the script to pause and wait until the lock becomes available (e.g., waiting for another process to finish), set the second argument to true.

// Try to acquire lock, waiting indefinitely until it is available
// true = blocking mode
if ($locker->lock('heavy_task', true)) {
    echo "Lock acquired after waiting (if necessary).\n";
    
    // Perform task
    // ...
    
    $locker->unlock('heavy_task');
}

Automatic Unlock on Shutdown

You can ensure locks are released even if the script is killed or ends unexpectedly by using unlockIfKill().

$locker = new Locker($handler);
$locker->unlockIfKill(); // Registers a shutdown function

if ($locker->lock('critical_job')) {
    // ... work ...
}
// Lock will be released automatically when script ends

Key Validation

Keys must be non-empty and contain only alphanumeric characters, underscores, and dots (/^[a-zA-Z0-9_.]+$/).

License

MPL-2.0 License.

michel / lock

Maintainers

Details