PHPackages                             aternos/lock - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. aternos/lock

ActiveLibrary[Utility & Helpers](/categories/utility)

aternos/lock
============

Distributed exclusive and shared resource locking based on etcd

v3.0.0(1y ago)54.9k↓38.2%3[1 PRs](https://github.com/aternosorg/php-lock/pulls)MITPHPPHP >=8.3CI failing

Since May 29Pushed 5mo ago3 watchersCompare

[ Source](https://github.com/aternosorg/php-lock)[ Packagist](https://packagist.org/packages/aternos/lock)[ RSS](/packages/aternos-lock/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (10)Dependencies (2)Versions (18)Used By (0)

PHP library for distributed locking
===================================

[](#php-library-for-distributed-locking)

Distributed exclusive and shared resource locking based on [etcd](https://github.com/etcd-io/etcd) (using [aternos/etcd](https://github.com/aternosorg/php-etcd)).

### About

[](#about)

This library was created to provide a highly available distributed locking solution for a file storage system, where a failed or incorrect lock could lead to potential data loss or corruption. Therefore it tries to achieve the best possible consistency while still providing simple usability, stability and scalability. There are lots of other locking libraries out there. Some of them don't allow shared locks, some of them implement complicated algorithms on the client-side which also didn't seem to fit our needs. Therefore we've decided to create our own solution and let etcd do most of the heavy lifting.

Etcd is a fast and reliable key-value store that allows transaction operations to ensure that no unexpected changes were made since the last read (see `putIf()` and `deleteIf()` in [`Aternos\Etcd\Client`](https://github.com/aternosorg/php-etcd/blob/master/src/Client.php)). This locking library uses those methods to ensure consistency. If two processes try to lock the same resource at the same time one of them will be denied by etcd and then retry its lock by either adding it to the other lock (shared) or waiting for the other lock to finish (exclusive). If more processes are fighting over the same lock, they will start to delay their retries in random intervals to find a consistent conclusion.

Timeouts (UnavailableExceptions) from etcd will also be detected and the operations retried after some delay to avoid problems because of short availability problems.

This library was extracted from a different project to be used in different places and not only for a file storage. Therefore we've already used this in production to create thousands of locks every minute in only a few milliseconds.

### Installation

[](#installation)

The gRPC PHP extension has to be installed to use this library. See [aternos/etcd](https://github.com/aternosorg/php-etcd#installation).

```
composer require aternos/lock
```

Usage
-----

[](#usage)

The most important class is the [`Lock`](src/Lock.php) class. Each instance of this class represents one lock on a resource that is identified by a key. There are also several static functions to set options for all locks, but all of them have default values, so you can just start by creating a lock:

```