From 998c3872a9023a1a21d76571a1ddf8d63fe04e23 Mon Sep 17 00:00:00 2001 From: roxblnfk Date: Fri, 9 Oct 2026 21:32:15 +0400 Subject: [PATCH] docs: refresh README header, installation and usage Assisted-By: Claude Opus 5.5 --- README.md | 110 +++++++++++++++++++++++++++++++++++------------------- 1 file changed, 72 insertions(+), 38 deletions(-) diff --git a/README.md b/README.md index 0bb608d..1e078c5 100644 --- a/README.md +++ b/README.md @@ -1,40 +1,63 @@ - - - - - - - -# RoadRunner locks - -[![PHP Version Require](https://poser.pugx.org/roadrunner-php/lock/require/php)](https://packagist.org/packages/roadrunner-php/lock) -[![Latest Stable Version](https://poser.pugx.org/roadrunner-php/lock/v/stable)](https://packagist.org/packages/roadrunner-php/lock) -[![phpunit](https://github.com/roadrunner-php/lock/actions/workflows/phpunit.yml/badge.svg)](https://github.com/roadrunner-php/lock/actions) -[![psalm](https://github.com/roadrunner-php/lock/actions/workflows/psalm.yml/badge.svg)](https://github.com/roadrunner-php/lock/actions) -[![Codecov](https://codecov.io/gh/roadrunner-php/lock/branch/1.x/graph/badge.svg)](https://codecov.io/gh/roadrunner-php/lock/) -[![Total Downloads](https://poser.pugx.org/roadrunner-php/lock/downloads)](https://packagist.org/packages/roadrunner-php/lock) - - -This package provides a PHP integration package for the RoadRunner Lock plugin, which allows for easy management of -distributed locks in PHP applications. The plugin provides a fast, lightweight, and reliable way to acquire, release, -and manage locks in a distributed environment, making it ideal for use in high-traffic web applications and -microservices. - -## Requirements +

+ + + RoadRunner + +

+ +

Distributed locks for PHP applications powered by RoadRunner

+ +
+ +[![Documentation](https://img.shields.io/badge/Documentation-blue?style=for-the-badge&logo=gitbook&logoColor=white)](https://docs.roadrunner.dev/docs/plugins/locks) +[![Sponsor](https://img.shields.io/static/v1?style=for-the-badge&label=&message=Sponsor&logo=githubsponsors&logoColor=white&color=%23EA4AAA)](https://github.com/sponsors/roadrunner-server) + +[![Psalm Level](https://shepherd.dev/github/roadrunner-php/lock/level.svg)](https://shepherd.dev/github/roadrunner-php/lock) +[![Type Coverage](https://shepherd.dev/github/roadrunner-php/lock/coverage.svg)](https://shepherd.dev/github/roadrunner-php/lock) + +
+ +
+ +This package is a PHP client for the [RoadRunner Lock plugin](https://docs.roadrunner.dev/docs/plugins/locks). It lets +your workers acquire, release and manage exclusive and shared (read) locks on named resources, shared across all +processes connected to the RoadRunner server. + +## Get Started + +### Requirements Make sure that your server is configured with following PHP version and extensions: - PHP 8.1+ -## Installation - -You can install the package via composer: +### Installation ```bash composer require roadrunner-php/lock ``` -## Usage +[![PHP](https://img.shields.io/packagist/php-v/roadrunner-php/lock.svg?style=flat-square&logo=php)](https://packagist.org/packages/roadrunner-php/lock) +[![Latest Version on Packagist](https://img.shields.io/packagist/v/roadrunner-php/lock.svg?style=flat-square&logo=packagist)](https://packagist.org/packages/roadrunner-php/lock) +[![License](https://img.shields.io/packagist/l/roadrunner-php/lock.svg?style=flat-square)](LICENSE) +[![Total Downloads](https://img.shields.io/packagist/dt/roadrunner-php/lock.svg?style=flat-square)](https://packagist.org/packages/roadrunner-php/lock/stats) + +### Configuration + +The client talks to RoadRunner over RPC, so enable the `rpc` section in `.rr.yaml`. The Lock plugin uses the in-memory +backend by default; see the [plugin documentation](https://docs.roadrunner.dev/docs/plugins/locks) to share locks +between RoadRunner instances through Redis. + +```yaml +version: "3" + +rpc: + listen: tcp://127.0.0.1:6001 +``` + +### Your First Lock + +Create a `Lock` instance with an RPC connection to the RoadRunner server, then acquire and release a lock: ```php use RoadRunner\Lock\Lock; @@ -43,8 +66,22 @@ use Spiral\Goridge\RPC\RPC; require __DIR__ . '/vendor/autoload.php'; $lock = new Lock(RPC::create('tcp://127.0.0.1:6001')); + +$id = $lock->lock('pdf:create', ttl: 10); +if ($id === false) { + // The resource is locked by another process + return; +} + +try { + // Do the work +} finally { + $lock->release('pdf:create', $id); +} ``` +## Usage + ### Acquire lock Locks a resource so that it can be accessed by one process at a time. @@ -124,14 +161,15 @@ $lock->forceRelease('pdf:create'); ### Check lock -Checks if a resource is currently locked and returns information about the lock. +Checks if a resource is currently locked. Pass a lock id to check whether that particular lock is held. ```php -$status = $lock->exists('pdf:create'); -if($status) { - // Lock exists -} else { - // Lock not exists +if ($lock->exists('pdf:create')) { + // The resource is locked +} + +if ($lock->exists('pdf:create', $id)) { + // The lock with this id is held } ``` @@ -140,7 +178,7 @@ if($status) { Updates the time-to-live (TTL) for the locked resource. ```php -// Add 10 seconds to lock ttl +// Set the lock ttl to 10 seconds $lock->updateTTL('pdf:create', $id, 10); // or $lock->updateTTL('pdf:create', $id, new \DateInterval('PT10S')); @@ -155,7 +193,3 @@ composer test ## Credits - [butschster](https://github.com/butschster) - -## License - -The MIT License (MIT). Please see [License File](LICENSE) for more information.