Skip to content

Commit 269e475

Browse files
andy-stark-redisandy-stark-redis
authored
Merge pull request #845 from redis/DOC-4520-php-client-page
DOC-4520 added PHP client page
2 parents 2ea057b + 82123f8 commit 269e475

File tree

3 files changed

+323
-10
lines changed

3 files changed

+323
-10
lines changed

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

Lines changed: 14 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -16,13 +16,19 @@ 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:
21-
- [Python]({{< relref "/develop/connect/clients/python" >}})
22-
- [C#/.NET]({{< relref "/develop/connect/clients/dotnet" >}})
23-
- [Node.js]({{< relref "/develop/connect/clients/nodejs" >}})
24-
- [Java]({{< relref "/develop/connect/clients/java" >}})
25-
- [Go]({{< relref "/develop/connect/clients/go" >}})
19+
your own code. We document the following client libraries
20+
for six main languages:
21+
22+
| Language | Client name | Docs | Supported |
23+
| :-- | :-- | :-- | :-- |
24+
| [Python](https://www.python.org/) | [`redis-py`](https://github.com/redis/redis-py) |[Redis Python library guide]({{< relref "/develop/connect/clients/python/redis-py" >}}) | Yes |
25+
| [Python](https://www.python.org/) | [`RedisVL`](https://github.com/redis/redis-vl-python) |[RedisVL guide]({{< relref "/integrate/redisvl" >}}) | Yes
26+
| [C#/.NET](https://learn.microsoft.com/en-us/dotnet/csharp/) | [`NRedisStack`](https://github.com/redis/NRedisStack) |[C#/.NET guide]({{< relref "/develop/connect/clients/dotnet" >}}) | Yes |
27+
| [Node.js](https://nodejs.org/en) | [`node-redis`](https://github.com/redis/node-redis) | [Node.js guide]({{< relref "/develop/connect/clients/nodejs" >}}) | Yes |
28+
| [Java](https://www.java.com/en/) | [`Jedis`](https://github.com/redis/jedis) | [Jedis guide]({{< relref "/develop/connect/clients/java/jedis" >}}) | Yes |
29+
| [Java](https://www.java.com/en/) | [`Lettuce`](https://github.com/redis/lettuce) | [Lettuce guide]({{< relref "/develop/connect/clients/java/lettuce" >}}) | Yes |
30+
| [Go](https://go.dev/) | [`go-redis`](https://github.com/redis/go-redis) | [Go guide]({{< relref "/develop/connect/clients/go" >}}) | Yes |
31+
| [PHP](https://www.php.net/)| [`Predis`](https://github.com/predis/predis) | [PHP guide]({{< relref "/develop/connect/clients/php" >}}) | No |
2632

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

3642
The table below shows the recommended third-party client libraries for languages that
37-
Redis does not support directly:
43+
Redis does not document directly:
3844

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

0 commit comments

Comments
 (0)