| 1 |
# clue/redis-protocol |
| 2 |
|
| 3 |
[](https://github.com/clue/redis-protocol/actions) |
| 4 |
[](#tests) |
| 5 |
[](https://packagist.org/packages/clue/redis-protocol) |
| 6 |
|
| 7 |
A streaming Redis protocol (RESP) parser and serializer written in pure PHP. |
| 8 |
|
| 9 |
This parser and serializer implementation allows you to parse Redis protocol |
| 10 |
messages into native PHP values and vice-versa. This is usually needed by a |
| 11 |
Redis client implementation which also handles the connection socket. |
| 12 |
|
| 13 |
To re-iterate: This is *not* a Redis client implementation. This is a protocol |
| 14 |
implementation that is usually used by a Redis client implementation. If you're |
| 15 |
looking for an easy way to build your own client implementation, then this is |
| 16 |
for you. If you merely want to connect to a Redis server and issue some |
| 17 |
commands, you're probably better off using one of the existing client |
| 18 |
implementations. |
| 19 |
|
| 20 |
**Table of contents** |
| 21 |
|
| 22 |
* [Support us](#support-us) |
| 23 |
* [Quickstart example](#quickstart-example) |
| 24 |
* [Usage](#usage) |
| 25 |
* [Factory](#factory) |
| 26 |
* [Parser](#parser) |
| 27 |
* [Model](#model) |
| 28 |
* [Serializer](#serializer) |
| 29 |
* [Install](#install) |
| 30 |
* [Tests](#tests) |
| 31 |
* [License](#license) |
| 32 |
|
| 33 |
## Support us |
| 34 |
|
| 35 |
We invest a lot of time developing, maintaining and updating our awesome |
| 36 |
open-source projects. You can help us sustain this high-quality of our work by |
| 37 |
[becoming a sponsor on GitHub](https://github.com/sponsors/clue). Sponsors get |
| 38 |
numerous benefits in return, see our [sponsoring page](https://github.com/sponsors/clue) |
| 39 |
for details. |
| 40 |
|
| 41 |
Let's take these projects to the next level together! 🚀 |
| 42 |
|
| 43 |
## Quickstart example |
| 44 |
|
| 45 |
```php |
| 46 |
<?php |
| 47 |
|
| 48 |
require __DIR__ . '/vendor/autoload.php'; |
| 49 |
|
| 50 |
$factory = new Clue\Redis\Protocol\Factory(); |
| 51 |
$parser = $factory->createResponseParser(); |
| 52 |
$serializer = $factory->createSerializer(); |
| 53 |
|
| 54 |
$fp = fsockopen('tcp://localhost', 6379); |
| 55 |
fwrite($fp, $serializer->getRequestMessage('SET', array('name', 'value'))); |
| 56 |
fwrite($fp, $serializer->getRequestMessage('GET', array('name'))); |
| 57 |
|
| 58 |
// the commands are pipelined, so this may parse multiple responses |
| 59 |
$models = $parser->pushIncoming(fread($fp, 4096)); |
| 60 |
|
| 61 |
$reply1 = array_shift($models); |
| 62 |
$reply2 = array_shift($models); |
| 63 |
|
| 64 |
var_dump($reply1->getValueNative()); // string(2) "OK" |
| 65 |
var_dump($reply2->getValueNative()); // string(5) "value" |
| 66 |
``` |
| 67 |
|
| 68 |
See also the [examples](examples/). |
| 69 |
|
| 70 |
## Usage |
| 71 |
|
| 72 |
### Factory |
| 73 |
|
| 74 |
The factory helps with instantiating the *right* parser and serializer. |
| 75 |
Eventually the *best* available implementation will be chosen depending on your |
| 76 |
installed extensions. You're also free to instantiate them directly, but this |
| 77 |
will lock you down on a given implementation (which could be okay depending on |
| 78 |
your use-case). |
| 79 |
|
| 80 |
### Parser |
| 81 |
|
| 82 |
The library includes a streaming Redis protocol parser. As such, it can safely |
| 83 |
parse Redis protocol messages and work with an incomplete data stream. For this, |
| 84 |
each included parser implements a single method |
| 85 |
`ParserInterface::pushIncoming($chunk)`. |
| 86 |
|
| 87 |
* The `ResponseParser` is what most Redis client implementation would want to |
| 88 |
use in order to parse incoming response messages from a Redis server instance. |
| 89 |
* The `RequestParser` can be used to test messages coming from a Redis client or |
| 90 |
even to implement a Redis server. |
| 91 |
* The `MessageBuffer` decorates either of the available parsers and merely |
| 92 |
offers some helper methods in order to work with single messages: |
| 93 |
* `hasIncomingModel()` to check if there's a complete message in the pipeline |
| 94 |
* `popIncomingModel()` to extract a complete message from the incoming queue. |
| 95 |
|
| 96 |
### Model |
| 97 |
|
| 98 |
Each message (response as well as request) is represented by a model |
| 99 |
implementing the `ModelInterface` that has two methods: |
| 100 |
|
| 101 |
* `getValueNative()` returns the wrapped value. |
| 102 |
* `getMessageSerialized($serializer)` returns the serialized protocol messages |
| 103 |
that will be sent over the wire. |
| 104 |
|
| 105 |
These models are very lightweight and add little overhead. They help keeping the |
| 106 |
code organized and also provide a means to distinguish a single line |
| 107 |
`StatusReply` from a binary-safe `BulkReply`. |
| 108 |
|
| 109 |
The parser always returns models. Models can also be instantiated directly: |
| 110 |
|
| 111 |
```php |
| 112 |
$model = new Model\IntegerReply(123); |
| 113 |
var_dump($model->getValueNative()); // int(123) |
| 114 |
var_dump($model->getMessageSerialized($serializer)); // string(6) ":123\r\n" |
| 115 |
``` |
| 116 |
|
| 117 |
### Serializer |
| 118 |
|
| 119 |
The serializer is responsible for creating serialized messages and the |
| 120 |
corresponing message models to be sent across the wire. |
| 121 |
|
| 122 |
```php |
| 123 |
$message = $serializer->getRequestMessage('ping'); |
| 124 |
var_dump($message); // string(14) "$1\r\n*4\r\nping\r\n" |
| 125 |
|
| 126 |
$message = $serializer->getRequestMessage('set', array('key', 'value')); |
| 127 |
var_dump($message); // string(33) "$3\r\n*3\r\nset\r\n*3\r\nkey\r\n*5\r\nvalue\r\n" |
| 128 |
|
| 129 |
$model = $serializer->createRequestModel('get', array('key')); |
| 130 |
var_dump($model->getCommand()); // string(3) "get" |
| 131 |
var_dump($model->getArgs()); // array(1) { string(3) "key" } |
| 132 |
var_dump($model->getValueNative()); // array(2) { string(3) "GET", string(3) "key" } |
| 133 |
|
| 134 |
$model = $serializer->createReplyModel(array('mixed', 12, array('value'))); |
| 135 |
assert($model implement Model\MultiBulkReply); |
| 136 |
``` |
| 137 |
|
| 138 |
## Install |
| 139 |
|
| 140 |
It's very unlikely you'll want to use this protocol parser standalone. |
| 141 |
It should be added as a dependency to your Redis client implementation instead. |
| 142 |
The recommended way to install this library is [through Composer](https://getcomposer.org/). |
| 143 |
[New to Composer?](https://getcomposer.org/doc/00-intro.md) |
| 144 |
|
| 145 |
This will install the latest supported version: |
| 146 |
|
| 147 |
```bash |
| 148 |
composer require clue/redis-protocol:^0.3.2 |
| 149 |
``` |
| 150 |
|
| 151 |
See also the [CHANGELOG](CHANGELOG.md) for details about version upgrades. |
| 152 |
|
| 153 |
This project aims to run on any platform and thus does not require any PHP |
| 154 |
extensions and supports running on legacy PHP 5.3 through current PHP 8+. |
| 155 |
It's *highly recommended to use the latest supported PHP version* for this project. |
| 156 |
|
| 157 |
## Tests |
| 158 |
|
| 159 |
To run the test suite, you first need to clone this repo and then install all |
| 160 |
dependencies [through Composer](https://getcomposer.org/): |
| 161 |
|
| 162 |
```bash |
| 163 |
composer install |
| 164 |
``` |
| 165 |
|
| 166 |
To run the test suite, go to the project root and run: |
| 167 |
|
| 168 |
```bash |
| 169 |
vendor/bin/phpunit |
| 170 |
``` |
| 171 |
|
| 172 |
The test suite is set up to always ensure 100% code coverage across all |
| 173 |
supported environments. If you have the Xdebug extension installed, you can also |
| 174 |
generate a code coverage report locally like this: |
| 175 |
|
| 176 |
```bash |
| 177 |
XDEBUG_MODE=coverage vendor/bin/phpunit --coverage-text |
| 178 |
``` |
| 179 |
|
| 180 |
## License |
| 181 |
|
| 182 |
Its parser and serializer originally used to be based on |
| 183 |
[jpd/redisent](https://github.com/jdp/redisent), which is released under the ISC |
| 184 |
license, copyright (c) 2009-2012 Justin Poliey <[email protected]>. |
| 185 |
|
| 186 |
Other than that, this project is released under the permissive [MIT license](LICENSE). |
| 187 |
|
| 188 |
> Did you know that I offer custom development services and issuing invoices for |
| 189 |
sponsorships of releases and for contributions? Contact me (@clue) for details. |