Skip to content

Commit cc0f4ac

Browse files
clueclue
committed
Improve documentation structure
1 parent af0cce3 commit cc0f4ac

1 file changed

Lines changed: 167 additions & 164 deletions

File tree

‎README.md‎

Lines changed: 167 additions & 164 deletions
Original file line numberDiff line numberDiff line change
@@ -29,17 +29,18 @@ It enables you to set and query its data or use its PubSub topics to react to in
2929
* [Support us](#support-us)
3030
* [Quickstart example](#quickstart-example)
3131
* [Usage](#usage)
32-
* [Factory](#factory)
33-
* [createClient()](#createclient)
34-
* [createLazyClient()](#createlazyclient)
35-
* [Client](#client)
3632
* [Commands](#commands)
3733
* [Promises](#promises)
3834
* [PubSub](#pubsub)
39-
* [close()](#close)
40-
* [end()](#end)
41-
* [error event](#error-event)
42-
* [close event](#close-event)
35+
* [API](#api)
36+
* [Factory](#factory)
37+
* [createClient()](#createclient)
38+
* [createLazyClient()](#createlazyclient)
39+
* [Client](#client)
40+
* [end()](#end)
41+
* [close()](#close)
42+
* [error event](#error-event)
43+
* [close event](#close-event)
4344
* [Install](#install)
4445
* [Tests](#tests)
4546
* [License](#license)
@@ -83,6 +84,161 @@ See also the [examples](examples).
8384

8485
## Usage
8586

87+
### Commands
88+
89+
All [Redis commands](https://redis.io/commands) are automatically available as public methods like this:
90+
91+
```php
92+
$client->get($key);
93+
$client->set($key, $value);
94+
$client->exists($key);
95+
$client->expire($key, $seconds);
96+
$client->mget($key1, $key2, $key3);
97+
98+
$client->multi();
99+
$client->exec();
100+
101+
$client->publish($channel, $payload);
102+
$client->subscribe($channel);
103+
104+
$client->ping();
105+
$client->select($database);
106+
107+
// many more…
108+
```
109+
110+
Listing all available commands is out of scope here, please refer to the [Redis command reference](https://redis.io/commands).
111+
All [Redis commands](https://redis.io/commands) are automatically available as public methods via the magic `__call()` method.
112+
113+
Each of these commands supports async operation and either *resolves* with
114+
its *results* or *rejects* with an `Exception`.
115+
Please see the following section about [promises](#promises) for more details.
116+
117+
### Promises
118+
119+
Sending commands is async (non-blocking), so you can actually send multiple commands in parallel.
120+
Redis will respond to each command request with a response message, pending commands will be pipelined automatically.
121+
122+
Sending commands uses a [Promise](https://github.com/reactphp/promise)-based interface that makes it easy to react to when a command is *fulfilled*
123+
(i.e. either successfully resolved or rejected with an error):
124+
125+
```php
126+
$client->set('hello', 'world');
127+
$client->get('hello')->then(function ($response) {
128+
// response received for GET command
129+
echo 'hello ' . $response;
130+
});
131+
```
132+
133+
### PubSub
134+
135+
This library is commonly used to efficiently transport messages using Redis'
136+
[Pub/Sub](https://redis.io/topics/pubsub) (Publish/Subscribe) channels. For
137+
instance, this can be used to distribute single messages to a larger number
138+
of subscribers (think horizontal scaling for chat-like applications) or as an
139+
efficient message transport in distributed systems (microservice architecture).
140+
141+
The [`PUBLISH` command](https://redis.io/commands/publish) can be used to
142+
send a message to all clients currently subscribed to a given channel:
143+
144+
```php
145+
$channel = 'user';
146+
$message = json_encode(array('id' => 10));
147+
$client->publish($channel, $message);
148+
```
149+
150+
The [`SUBSCRIBE` command](https://redis.io/commands/subscribe) can be used to
151+
subscribe to a channel and then receive incoming PubSub `message` events:
152+
153+
```php
154+
$channel = 'user';
155+
$client->subscribe($channel);
156+
157+
$client->on('message', function ($channel, $payload) {
158+
// pubsub message received on given $channel
159+
var_dump($channel, json_decode($payload));
160+
});
161+
```
162+
163+
Likewise, you can use the same client connection to subscribe to multiple
164+
channels by simply executing this command multiple times:
165+
166+
```php
167+
$client->subscribe('user.register');
168+
$client->subscribe('user.join');
169+
$client->subscribe('user.leave');
170+
```
171+
172+
Similarly, the [`PSUBSCRIBE` command](https://redis.io/commands/psubscribe) can
173+
be used to subscribe to all channels matching a given pattern and then receive
174+
all incoming PubSub messages with the `pmessage` event:
175+
176+
177+
```php
178+
$pattern = 'user.*';
179+
$client->psubscribe($pattern);
180+
181+
$client->on('pmessage', function ($pattern, $channel, $payload) {
182+
// pubsub message received matching given $pattern
183+
var_dump($channel, json_decode($payload));
184+
});
185+
```
186+
187+
Once you're in a subscribed state, Redis no longer allows executing any other
188+
commands on the same client connection. This is commonly worked around by simply
189+
creating a second client connection and dedicating one client connection solely
190+
for PubSub subscriptions and the other for all other commands.
191+
192+
The [`UNSUBSCRIBE` command](https://redis.io/commands/unsubscribe) and
193+
[`PUNSUBSCRIBE` command](https://redis.io/commands/punsubscribe) can be used to
194+
unsubscribe from active subscriptions if you're no longer interested in
195+
receiving any further events for the given channel and pattern subscriptions
196+
respectively:
197+
198+
```php
199+
$client->subscribe('user');
200+
201+
Loop::addTimer(60.0, function () use ($client) {
202+
$client->unsubscribe('user');
203+
});
204+
```
205+
206+
Likewise, once you've unsubscribed the last channel and pattern, the client
207+
connection is no longer in a subscribed state and you can issue any other
208+
command over this client connection again.
209+
210+
Each of the above methods follows normal request-response semantics and return
211+
a [`Promise`](#promises) to await successful subscriptions. Note that while
212+
Redis allows a variable number of arguments for each of these commands, this
213+
library is currently limited to single arguments for each of these methods in
214+
order to match exactly one response to each command request. As an alternative,
215+
the methods can simply be invoked multiple times with one argument each.
216+
217+
Additionally, can listen for the following PubSub events to get notifications
218+
about subscribed/unsubscribed channels and patterns:
219+
220+
```php
221+
$client->on('subscribe', function ($channel, $total) {
222+
// subscribed to given $channel
223+
});
224+
$client->on('psubscribe', function ($pattern, $total) {
225+
// subscribed to matching given $pattern
226+
});
227+
$client->on('unsubscribe', function ($channel, $total) {
228+
// unsubscribed from given $channel
229+
});
230+
$client->on('punsubscribe', function ($pattern, $total) {
231+
// unsubscribed from matching given $pattern
232+
});
233+
```
234+
235+
When using the [`createLazyClient()`](#createlazyclient) method, the `unsubscribe`
236+
and `punsubscribe` events will be invoked automatically when the underlying
237+
connection is lost. This gives you control over re-subscribing to the channels
238+
and patterns as appropriate.
239+
240+
## API
241+
86242
### Factory
87243

88244
The `Factory` is responsible for creating your [`Client`](#client) instance.
@@ -354,169 +510,16 @@ and keeps track of pending commands.
354510
Besides defining a few methods, this interface also implements the
355511
`EventEmitterInterface` which allows you to react to certain events as documented below.
356512

357-
#### Commands
358-
359-
All [Redis commands](https://redis.io/commands) are automatically available as public methods like this:
360-
361-
```php
362-
$client->get($key);
363-
$client->set($key, $value);
364-
$client->exists($key);
365-
$client->expire($key, $seconds);
366-
$client->mget($key1, $key2, $key3);
367-
368-
$client->multi();
369-
$client->exec();
370-
371-
$client->publish($channel, $payload);
372-
$client->subscribe($channel);
373-
374-
$client->ping();
375-
$client->select($database);
376-
377-
// many more…
378-
```
379-
380-
Listing all available commands is out of scope here, please refer to the [Redis command reference](https://redis.io/commands).
381-
All [Redis commands](https://redis.io/commands) are automatically available as public methods via the magic `__call()` method.
382-
383-
Each of these commands supports async operation and either *resolves* with
384-
its *results* or *rejects* with an `Exception`.
385-
Please see the following section about [promises](#promises) for more details.
386-
387-
#### Promises
388-
389-
Sending commands is async (non-blocking), so you can actually send multiple commands in parallel.
390-
Redis will respond to each command request with a response message, pending commands will be pipelined automatically.
391-
392-
Sending commands uses a [Promise](https://github.com/reactphp/promise)-based interface that makes it easy to react to when a command is *fulfilled*
393-
(i.e. either successfully resolved or rejected with an error):
394-
395-
```php
396-
$client->set('hello', 'world');
397-
$client->get('hello')->then(function ($response) {
398-
// response received for GET command
399-
echo 'hello ' . $response;
400-
});
401-
```
402-
403-
#### PubSub
404-
405-
This library is commonly used to efficiently transport messages using Redis'
406-
[Pub/Sub](https://redis.io/topics/pubsub) (Publish/Subscribe) channels. For
407-
instance, this can be used to distribute single messages to a larger number
408-
of subscribers (think horizontal scaling for chat-like applications) or as an
409-
efficient message transport in distributed systems (microservice architecture).
410-
411-
The [`PUBLISH` command](https://redis.io/commands/publish) can be used to
412-
send a message to all clients currently subscribed to a given channel:
413-
414-
```php
415-
$channel = 'user';
416-
$message = json_encode(array('id' => 10));
417-
$client->publish($channel, $message);
418-
```
419-
420-
The [`SUBSCRIBE` command](https://redis.io/commands/subscribe) can be used to
421-
subscribe to a channel and then receive incoming PubSub `message` events:
422-
423-
```php
424-
$channel = 'user';
425-
$client->subscribe($channel);
426-
427-
$client->on('message', function ($channel, $payload) {
428-
// pubsub message received on given $channel
429-
var_dump($channel, json_decode($payload));
430-
});
431-
```
432-
433-
Likewise, you can use the same client connection to subscribe to multiple
434-
channels by simply executing this command multiple times:
435-
436-
```php
437-
$client->subscribe('user.register');
438-
$client->subscribe('user.join');
439-
$client->subscribe('user.leave');
440-
```
441-
442-
Similarly, the [`PSUBSCRIBE` command](https://redis.io/commands/psubscribe) can
443-
be used to subscribe to all channels matching a given pattern and then receive
444-
all incoming PubSub messages with the `pmessage` event:
445-
446-
447-
```php
448-
$pattern = 'user.*';
449-
$client->psubscribe($pattern);
450-
451-
$client->on('pmessage', function ($pattern, $channel, $payload) {
452-
// pubsub message received matching given $pattern
453-
var_dump($channel, json_decode($payload));
454-
});
455-
```
456-
457-
Once you're in a subscribed state, Redis no longer allows executing any other
458-
commands on the same client connection. This is commonly worked around by simply
459-
creating a second client connection and dedicating one client connection solely
460-
for PubSub subscriptions and the other for all other commands.
461-
462-
The [`UNSUBSCRIBE` command](https://redis.io/commands/unsubscribe) and
463-
[`PUNSUBSCRIBE` command](https://redis.io/commands/punsubscribe) can be used to
464-
unsubscribe from active subscriptions if you're no longer interested in
465-
receiving any further events for the given channel and pattern subscriptions
466-
respectively:
467-
468-
```php
469-
$client->subscribe('user');
470-
471-
Loop::addTimer(60.0, function () use ($client) {
472-
$client->unsubscribe('user');
473-
});
474-
```
475-
476-
Likewise, once you've unsubscribed the last channel and pattern, the client
477-
connection is no longer in a subscribed state and you can issue any other
478-
command over this client connection again.
479-
480-
Each of the above methods follows normal request-response semantics and return
481-
a [`Promise`](#promises) to await successful subscriptions. Note that while
482-
Redis allows a variable number of arguments for each of these commands, this
483-
library is currently limited to single arguments for each of these methods in
484-
order to match exactly one response to each command request. As an alternative,
485-
the methods can simply be invoked multiple times with one argument each.
486-
487-
Additionally, can listen for the following PubSub events to get notifications
488-
about subscribed/unsubscribed channels and patterns:
489-
490-
```php
491-
$client->on('subscribe', function ($channel, $total) {
492-
// subscribed to given $channel
493-
});
494-
$client->on('psubscribe', function ($pattern, $total) {
495-
// subscribed to matching given $pattern
496-
});
497-
$client->on('unsubscribe', function ($channel, $total) {
498-
// unsubscribed from given $channel
499-
});
500-
$client->on('punsubscribe', function ($pattern, $total) {
501-
// unsubscribed from matching given $pattern
502-
});
503-
```
513+
#### end()
504514

505-
When using the [`createLazyClient()`](#createlazyclient) method, the `unsubscribe`
506-
and `punsubscribe` events will be invoked automatically when the underlying
507-
connection is lost. This gives you control over re-subscribing to the channels
508-
and patterns as appropriate.
515+
The `end():void` method can be used to
516+
soft-close the Redis connection once all pending commands are completed.
509517

510518
#### close()
511519

512520
The `close():void` method can be used to
513521
force-close the Redis connection and reject all pending commands.
514522

515-
#### end()
516-
517-
The `end():void` method can be used to
518-
soft-close the Redis connection once all pending commands are completed.
519-
520523
#### error event
521524

522525
The `error` event will be emitted once a fatal error occurs, such as

0 commit comments

Comments
 (0)