docs: refresh README

README.md

@@ -1,40 +1,63 @@
-<a href="https://roadrunner.dev" target="_blank">
-  <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://github.com/roadrunner-server/.github/assets/8040338/e6bde856-4ec6-4a52-bd5b-bfe78736c1ff">
-    <img align="center" src="https://github.com/roadrunner-server/.github/assets/8040338/040fb694-1dd3-4865-9d29-8e0748c2c8b8">
-  </picture>
-</a>
-
-# 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)
-<a href="https://discord.gg/spiralphp"><img src="https://img.shields.io/badge/discord-chat-magenta.svg"></a>
-
-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
+<p align="center">
+    <a href="https://roadrunner.dev"><picture>
+        <source media="(prefers-color-scheme: dark)" srcset="https://github.com/roadrunner-server/.github/assets/8040338/e6bde856-4ec6-4a52-bd5b-bfe78736c1ff">
+        <img alt="RoadRunner" src="https://github.com/roadrunner-server/.github/assets/8040338/040fb694-1dd3-4865-9d29-8e0748c2c8b8" style="width: 6in; display: block">
+    </picture></a>
+</p>
+
+<p align="center">Distributed locks for PHP applications powered by RoadRunner</p>
+
+<div align="center">
+
+[![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)
+
+</div>
+
+<br />
+
+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.