Skip to content

Commit 72c021c

Browse files
andy-stark-redisandy-stark-redis
committed
DOC-4520 added PHP client page
1 parent be24725 commit 72c021c

File tree

3 files changed

+319
-5
lines changed

3 files changed

+319
-5
lines changed

‎content/develop/connect/clients/_index.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -16,13 +16,14 @@ weight: 45
1616
---
1717

1818
Use the Redis client libraries to connect to Redis servers from
19-
your own code. We support client libraries
20-
for five main languages:
19+
your own code. We document client libraries
20+
for six main languages:
2121
- [Python]({{< relref "/develop/connect/clients/python" >}})
2222
- [C#/.NET]({{< relref "/develop/connect/clients/dotnet" >}})
2323
- [Node.js]({{< relref "/develop/connect/clients/nodejs" >}})
2424
- [Java]({{< relref "/develop/connect/clients/java" >}})
2525
- [Go]({{< relref "/develop/connect/clients/go" >}})
26+
- [PHP]({{< relref "/develop/connect/clients/php" >}})
2627

2728
We also provide several higher-level
2829
[object mapping (OM)]({{< relref "/develop/connect/clients/om-clients" >}})
@@ -34,13 +35,12 @@ libraries for [Python]({{< relref "/integrate/redisom-for-python" >}}),
3435
## Community-supported clients
3536

3637
The table below shows the recommended third-party client libraries for languages that
37-
Redis does not support directly:
38+
Redis does not document directly:
3839

3940
| Language | Client name | Github | Docs |
4041
| :-- | :-- | :-- | :-- |
4142
| C | hiredis | https://github.com/redis/hiredis | https://github.com/redis/hiredis |
4243
| [PHP](https://www.php.net/) | PhpRedis extension | https://github.com/phpredis/phpredis | https://github.com/phpredis/phpredis/blob/develop/README.md |
43-
| [PHP](https://www.php.net/) | Predis library | https://github.com/predis/predis | https://github.com/predis/predis/wiki |
4444
| [Ruby](https://www.ruby-lang.org/en/) | redis-rb | https://github.com/redis/redis-rb | https://rubydoc.info/gems/redis |
4545
| [Rust](https://www.rust-lang.org/) | redis-rs | https://github.com/redis-rs/redis-rs | https://docs.rs/redis/latest/redis/ |
4646
| [C++](https://en.wikipedia.org/wiki/C%2B%2B) | Boost.Redis | https://github.com/boostorg/redis | https://www.boost.org/doc/libs/develop/libs/redis/doc/html/index.html |

‎content/develop/connect/clients/om-clients/_index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ description: Object-Mapper libraries for Redis Stack
1313
linkTitle: Object mapping
1414
stack: true
1515
title: Object-Mapper libraries
16-
weight: 6
16+
weight: 7
1717
---
1818

1919
Redis OM (pronounced *REDiss OHM*) is a library that provides object mapping for Redis. With the help of Redis OM, you can map Redis data types, specifically Hashes and JSON documents, to objects of your preferred programming language or framework. Redis OM relies on Redis Stack's JSON, query, and search features, allowing you to query and search for objects.

‎content/develop/connect/clients/php.md‎

Lines changed: 314 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,314 @@
1+
---
2+
categories:
3+
- docs
4+
- develop
5+
- stack
6+
- oss
7+
- rs
8+
- rc
9+
- oss
10+
- kubernetes
11+
- clients
12+
description: Connect your PHP application to a Redis database
13+
linkTitle: PHP
14+
title: PHP guide
15+
weight: 6
16+
---
17+
18+
[`Predis`](https://github.com/predis/predis) is the recommended [PHP](https://php.net/)
19+
client for Redis.
20+
The sections below explain how to install `predis` and connect your application to a Redis database.
21+
22+
{{< note >}}Although we provide basic documentation for `Predis`, it is a third-party
23+
client library and is not developed or supported directly by Redis.
24+
{{< /note >}}
25+
26+
`Predis` requires a running Redis or
27+
[Redis Stack]({{< relref "/operate/oss_and_stack/install/install-stack/" >}}) server.
28+
See [Getting started]({{< relref "/operate/oss_and_stack/install/" >}}) for Redis installation
29+
instructions.
30+
31+
## Install
32+
33+
Use [Composer](https://getcomposer.org/) to install the `predis` library
34+
with the following command line:
35+
36+
```bash
37+
composer require predis/predis
38+
```
39+
40+
## Connect
41+
42+
Connect to a locally-running server on the standard port (6379)
43+
with the following code:
44+
45+
```php
46+
<?php
47+
48+
require 'vendor/autoload.php';
49+
50+
use Predis\Client as PredisClient;
51+
52+
$r = new PredisClient([
53+
'scheme' => 'tcp',
54+
'host' => '127.0.0.1',
55+
'port' => 6379,
56+
'password' => '',
57+
'database' => 0,
58+
]);
59+
```
60+
61+
Store and retrieve a simple string to test the connection:
62+
63+
```php
64+
echo $r->set('foo', 'bar'), PHP_EOL;
65+
// OK
66+
67+
echo $r->get('foo'), PHP_EOL;
68+
// bar
69+
```
70+
71+
Store and retrieve a [hash]({{< relref "/develop/data-types/hashes" >}})
72+
object:
73+
74+
```php
75+
$r->hset('user-session:123', 'name', 'John');
76+
$r->hset('user-session:123', 'surname', 'Smith');
77+
$r->hset('user-session:123', 'company', 'Redis');
78+
$r->hset('user-session:123', 'age', 29);
79+
80+
echo var_export($r->hgetall('user-session:123')), PHP_EOL;
81+
/*
82+
array (
83+
'name' => 'John',
84+
'surname' => 'Smith',
85+
'company' => 'Redis',
86+
'age' => '29',
87+
)
88+
*/
89+
```
90+
91+
## Connect to a Redis cluster
92+
93+
To connect to a Redis cluster, specify one or more of the nodes in
94+
the `clusterNodes` parameter and set `'cluster'=>'redis'` in
95+
`options`:
96+
97+
```php
98+
$clusterNodes = [
99+
'tcp://127.0.0.1:30001', // Node 1
100+
'tcp://127.0.0.1:30002', // Node 2
101+
'tcp://127.0.0.1:30003', // Node 3
102+
];
103+
$options = ['cluster' => 'redis'];
104+
105+
// Create a Predis client for the cluster
106+
$rc = new PredisClient($clusterNodes, $options);
107+
108+
echo $rc->cluster('nodes'), PHP_EOL;
109+
/*
110+
d8773e888e92d015b7c52fc66798fd6815afefec 127.0.0.1:30004@40004 slave cde97d1f7dce13e9253ace5cafd3fb0aa67cda63 0 1730713764217 1 connected
111+
58fe1346de4c425d60db24e9b153926fbde0d174 127.0.0.1:30002@40002 master - 0 1730713763361 2 connected 5461-10922
112+
015ecc8148a05377dda22f19921d16efcdd6d678 127.0.0.1:30006@40006 slave c019b75d8b52e83e7e52724eccc716ac553f71d6 0 1730713764218 3 connected
113+
aca365963a72642e6ae0c9503aabf3be5c260806 127.0.0.1:30005@40005 slave 58fe1346de4c425d60db24e9b153926fbde0d174 0 1730713763363 2 connected
114+
c019b75d8b52e83e7e52724eccc716ac553f71d6 127.0.0.1:30003@40003 myself,master - 0 1730713764000 3 connected 10923-16383
115+
cde97d1f7dce13e9253ace5cafd3fb0aa67cda63 127.0.0.1:30001@40001 master - 0 1730713764113 1 connected 0-5460
116+
*/
117+
118+
echo $rc->set('foo', 'bar'), PHP_EOL;
119+
// OK
120+
echo $rc->get('foo'), PHP_EOL;
121+
// bar
122+
```
123+
124+
## Connect to your production Redis with TLS
125+
126+
When you deploy your application, use TLS and follow the
127+
[Redis security]({{< relref "/operate/oss_and_stack/management/security/" >}})
128+
guidelines.
129+
130+
Use the following commands to generate the client certificate and private key:
131+
132+
```bash
133+
openssl genrsa -out redis_user_private.key 2048
134+
openssl req -new -key redis_user_private.key -out redis_user.csr
135+
openssl x509 -req -days 365 -in redis_user.csr -signkey redis_user_private.key -out redis_user.crt
136+
```
137+
138+
If you have the [Redis source folder](https://github.com/redis/redis) available,
139+
you can also use generate the certificate and private key with these commands:
140+
141+
```bash
142+
./utils/gen-test-certs.sh
143+
./src/redis-server --tls-port 6380 --port 0 --tls-cert-file ./tests/tls/redis.crt --tls-key-file ./tests/tls/redis.key --tls-ca-cert-file ./tests/tls/ca.crt
144+
```
145+
146+
Pass this information during connection using the `ssl` section of `options`:
147+
148+
```php
149+
$options = [
150+
'scheme' => 'tls', // Use 'tls' for SSL connections
151+
'host' => '127.0.0.1', // Redis server hostname
152+
'port' => 6379, // Redis server port
153+
'username' => 'default', // Redis username
154+
'password' => '', // Redis password
155+
'options' => [
156+
'ssl' => [
157+
'verify_peer' => true, // Verify the server's SSL certificate
158+
'cafile' => './redis_ca.pem', // Path to CA certificate
159+
'local_cert' => './redis_user.crt', // Path to client certificate
160+
'local_pk' => './redis_user_private.key', // Path to client private key
161+
],
162+
],
163+
];
164+
165+
$tlsConnection = new PredisClient($options);
166+
167+
echo $tlsConnection->set('foo', 'bar'), PHP_EOL;
168+
// OK
169+
echo $tlsConnection->get('foo'), PHP_EOL;
170+
// bar
171+
```
172+
173+
## Example: Indexing and querying JSON documents
174+
175+
This example shows how to index and query Redis JSON data using `predis`.
176+
177+
Make sure that you have Redis Stack and `predis` installed, as described
178+
in the [Install](#install) section above.
179+
180+
Start by importing dependencies:
181+
182+
```php
183+
<?php
184+
185+
require 'vendor/autoload.php';
186+
187+
use Predis\Client as PredisClient;
188+
189+
use Predis\Command\Argument\Search\AggregateArguments;
190+
use Predis\Command\Argument\Search\CreateArguments;
191+
use Predis\Command\Argument\Search\SearchArguments;
192+
use Predis\Command\Argument\Search\SchemaFields\NumericField;
193+
use Predis\Command\Argument\Search\SchemaFields\TextField;
194+
use Predis\Command\Argument\Search\SchemaFields\TagField;
195+
use Predis\Command\Argument\Search\SchemaFields\VectorField;
196+
```
197+
198+
Connect to the Redis server:
199+
200+
```php
201+
$r = new PredisClient([
202+
'scheme' => 'tcp',
203+
'host' => '127.0.0.1',
204+
'port' => 6379,
205+
'password' => '',
206+
'database' => 0,
207+
]);
208+
```
209+
210+
Create some test data to add to the database:
211+
212+
```php
213+
$user1 = json_encode([
214+
'name' => 'Paul John',
215+
'email' => '[email protected]',
216+
'age' => 42,
217+
'city' => 'London',
218+
], JSON_THROW_ON_ERROR);
219+
220+
$user2 = json_encode([
221+
'name' => 'Eden Zamir',
222+
'email' => '[email protected]',
223+
'age' => 29,
224+
'city' => 'Tel Aviv',
225+
], JSON_THROW_ON_ERROR);
226+
227+
$user3 = json_encode([
228+
'name' => 'Paul Zamir',
229+
'email' => '[email protected]',
230+
'age' => 35,
231+
'city' => 'Tel Aviv',
232+
], JSON_THROW_ON_ERROR);
233+
```
234+
235+
Create an
236+
[index]({{< relref "/develop/interact/search-and-query/indexing" >}}).
237+
In this example, only JSON documents with the key prefix `user:` are indexed.
238+
For more information, see
239+
[Query syntax]({{< relref "/develop/interact/search-and-query/query/" >}}).
240+
241+
```php
242+
$schema = [
243+
new TextField('$.name', 'name'),
244+
new TagField('$.city', 'city'),
245+
new NumericField('$.age', "age"),
246+
];
247+
248+
try {
249+
$r->ftCreate("idx:users", $schema,
250+
(new CreateArguments())
251+
->on('JSON')
252+
->prefix(["user:"]));
253+
}
254+
catch (Exception $e) {
255+
echo $e->getMessage(), PHP_EOL;
256+
}
257+
```
258+
259+
Add the three sets of user data to the database as
260+
[JSON]({{< relref "/develop/data-types/json" >}}) objects.
261+
If you use keys with the `user:` prefix then Redis will index the
262+
objects automatically as you add them:
263+
264+
```php
265+
$r->jsonset('user:1', '$', $user1);
266+
$r->jsonset('user:2', '$', $user2);
267+
$r->jsonset('user:3', '$', $user3);
268+
```
269+
270+
You can now use the index to search the JSON objects. The
271+
[query]({{< relref "/develop/interact/search-and-query/query" >}})
272+
below searches for objects that have the text "Paul" in any field
273+
and have an `age` value in the range 30 to 40:
274+
275+
```php
276+
$res = $r->ftSearch("idx:users", "Paul @age:[30 40]");
277+
echo json_encode($res), PHP_EOL;
278+
// [1,"user:3",["$","{\"name\":\"Paul Zamir\",\"email\":\"[email protected]\",\"age\":35,\"city\":\"London\"}"]]
279+
```
280+
281+
Specify query options to return only the `city` field:
282+
283+
```php
284+
$arguments = new SearchArguments();
285+
$arguments->addReturn(3, '$.city', true, 'thecity');
286+
$arguments->dialect(2);
287+
$arguments->limit(0, 5);
288+
289+
$res = $r->ftSearch("idx:users", "Paul", $arguments);
290+
291+
echo json_encode($res), PHP_EOL;
292+
// [2,"user:1",["thecity","London"],"user:3",["thecity","Tel Aviv"]]
293+
```
294+
295+
Use an
296+
[aggregation query]({{< relref "/develop/interact/search-and-query/query/aggregation" >}})
297+
to count all users in each city.
298+
299+
```php
300+
$ftAggregateArguments = (new AggregateArguments())
301+
->groupBy('@city')
302+
->reduce('COUNT', true, 'count');
303+
304+
$res = $r->ftAggregate('idx:users', '*', $ftAggregateArguments);
305+
echo json_encode($res), PHP_EOL;
306+
// [2,["city","London","count","1"],["city","Tel Aviv","count","2"]]
307+
```
308+
309+
See the [Redis query engine]({{< relref "/develop/interact/search-and-query" >}}) docs
310+
for a full description of all query features with examples.
311+
312+
## Learn more
313+
314+
- [Predis wiki on Github](https://github.com/predis/predis/wiki)

0 commit comments

Comments
 (0)