Debian Codegraph @

vendor/clue/redis-protocol/README.md

raw
1 # clue/redis-protocol
2
3 [![CI status](https://github.com/clue/redis-protocol/actions/workflows/ci.yml/badge.svg)](https://github.com/clue/redis-protocol/actions)
4 [![code coverage](https://img.shields.io/badge/code%20coverage-100%25-success)](#tests)
5 [![installs on Packagist](https://img.shields.io/packagist/dt/clue/redis-protocol?color=blue&label=installs%20on%20Packagist)](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.