README

A lightweight PHP library for file-based exclusive locking using flock().

Requirements

PHP 8.1 or higher

Installation

composer require danil-kashin/file-lock

Usage

Basic acquire and release

use DanilKashin\FileLock\FileLock;

$lock = new FileLock('/tmp/my-process.lock');

$lock->acquire(); // blocks until the lock is obtained
// ... critical section ...
$lock->release();

Clean up the lock file after use

$lock = new FileLock('/tmp/my-process.lock');

$lock->acquire();
// ... critical section ...
$lock->release();
$lock->deleteFile();

Error handling

use DanilKashin\FileLock\Exceptions\FileLockException;

$lock = new FileLock('/tmp/my-process.lock');

try {
    $lock->acquire();
    // ... critical section ...
} catch (FileLockException $e) {
    // lock file could not be opened or the lock could not be acquired
    echo $e->getMessage();
} finally {
    $lock->release();
}

API

`FileLock::__construct(string $lockFile)`

Creates a new FileLock instance. The $lockFile path is the file used as the lock. The file is created automatically on the first call to acquire() if it does not exist.

`acquire(): void`

Acquires an exclusive lock (LOCK_EX). Blocks until the lock becomes available. Calling acquire() multiple times on the same instance is safe — the file handle is reused and flock is re-entrant on the same process.

Throws FileLockException if the lock file cannot be opened.

`release(): void`

Releases the exclusive lock (LOCK_UN). The lock file itself is kept on disk.

`deleteFile(): void`

Deletes the lock file from disk. Call this after release() when the file is no longer needed.

How it works

FileLock opens the target file in cb mode (create if missing, binary) and delegates all locking to the operating system via PHP's flock(). This makes it safe to use across multiple processes on the same machine.

Running tests

composer install
vendor/bin/phpunit

danil-kashin / file-lock

Maintainers

Package info

Statistics

Security