README

English | 中文

🔒 A framework-agnostic mutex library designed to facilitate serialized execution of PHP code in high-concurrency scenarios.

Requirements

• PHP >= 7.1 or above
• Redis >= 2.6.12 or above (required for distributed locks or Redlock)
• Swoole >= 4.5 or above (required for coroutine-level mutex locks)

Installation

composer require pudongping/wise-locksmith

Quickstart

<?php

require 'vendor/autoload.php';

use Pudongping\WiseLocksmith\Locker;

$redisHosts = [
    [
        'host' => '127.0.0.1',
        'port' => 6379
    ],
    [
        'host' => '127.0.0.1',
        'port' => 6380
    ],
    [
        'host' => '127.0.0.1',
        'port' => 6381
    ],
    [
        'host' => '127.0.0.1',
        'port' => 6382
    ],
    [
        'host' => '127.0.0.1',
        'port' => 6383
    ],
];

// Initialize Redis instances if distributed locks or Redlock are needed; otherwise, you can skip this step
$redisInstances = array_map(function ($v) {
    $redis = new \Redis();
    $redis->connect($v['host'], $v['port']);
    return $redis;
}, $redisHosts);

// Create an instance of locker
$locker = new Locker();

Usage

An example of potential data inconsistency in high-concurrency scenarios is provided in the current project, see here.

flock - File Lock

File locking has no dependencies. You can set the lock's timeout using the optional third parameter, in seconds (supports floating-point numbers, e.g., 1.5 means 1500ms, which means it will wait for a maximum of 1500ms; if it fails to acquire the lock, it will actively release the attempt and throw a Pudongping\WiseLocksmith\Exception\TimeoutException exception). Setting it to Pudongping\WiseLocksmith\Lock\File\Flock::INFINITE_TIMEOUT means it never expires, and it will continuously block attempting to acquire the lock until successful. The default value is Pudongping\WiseLocksmith\Lock\File\Flock::INFINITE_TIMEOUT.

$path = tempnam(sys_get_temp_dir(), 'wise-locksmith-flock-');
$fileHandler = fopen($path, 'r');

$res = $locker->flock($fileHandler, function () {
    // Write the code you want to protect here
});

unlink($path);

return $res;

redisLock - Distributed Lock

Requires the redis extension. You can set the lock's timeout using the optional third parameter, in seconds (supports floating-point numbers, e.g., 1.5 means 1500ms, which means it will wait for a maximum of 1500ms; if it fails to acquire the lock, it will actively release the attempt and throw a Pudongping\WiseLocksmith\Exception\TimeoutException exception). The default value is 5. The fourth parameter is a unique value for the current lock, which is generally not needed to be set unless there are special circumstances.

$res = $locker->redisLock($redisInstances[0], 'redisLock', function () {
    // Write the code you want to protect here
});

return $res;

redLock - RedLock (Implementation of distributed locks in a Redis cluster environment)

The parameters required for setting up the redLock lock are identical to the redisLock lock, except for the first parameter. All other parameters are exactly the same. The redLock lock is a cluster implementation of the redisLock lock.

$res = $locker->redLock($redisInstances, 'redLock', function () {
    // Write the code you want to protect here
});

return $res;

channelLock - Coroutine-Level Mutex Lock

When using this lock, you need to have the swoole extension installed, and the version must be greater than or equal to 4.5. You can set the lock's timeout using the optional third parameter, in seconds (supports floating-point numbers, e.g., 1.5 means 1500ms, which means it will wait for a maximum of 1500ms; if it fails to acquire the lock, it will actively give up the attempt and return false to indicate the lock was not acquired). Setting it to -1 means it never expires, and it will continuously block attempting to acquire the lock until successful. The default value is -1.

$res = $locker->channelLock('channelLock', function () {
    // Write the code you want to protect here
});

return $res;

For all the mentioned locks, the business closure function is executed only after successfully acquiring the lock. It then returns the result of the business closure function's execution. Otherwise, if the lock is not acquired, the business closure function is not executed, and the return value is null.

Running tests

To run the test suite, clone this repository and then install dependencies via Composer.

composer install

Then, go to the project root and run:

php -d memory_limit=-1 ./vendor/bin/phpunit -c ./phpunit.xml.dist

or 

composer run test

Exception Handling

You can catch Pudongping\WiseLocksmith\Exception\WiseLocksmithException exceptions to capture all exceptions thrown by this library.

use Pudongping\WiseLocksmith\Exception\WiseLocksmithException;
use Pudongping\WiseLocksmith\Locker;

try {
    $locker = new Locker();
    // ...
} catch (WiseLocksmithException $exception) {
    var_dump($exception->getPrevious());
    var_dump($exception->getCode(), $exception->getMessage());
}

Acknowledgments

• laravel/framework
• hyperf/context
• easy-swoole/component
• swoole/library
• redisson/redisson
• php-lock/lock
• How to do distributed locking
• Is Redlock safe?
• Distributed Locks with Redis ， 一种基于 Redis 的分布式锁模式 （中文译文）

Contributing

Bug reports (and small patches) can be submitted via the issue tracker. Forking the repository and submitting a Pull Request is preferred for substantial patches.

License

MIT, see LICENSE file.