From 72c021c49b07607e4a3f59162d9d10193270bf10 Mon Sep 17 00:00:00 2001 From: Andy Stark Date: Tue, 5 Nov 2024 16:43:12 +0000 Subject: [PATCH 1/7] DOC-4520 added PHP client page --- content/develop/connect/clients/_index.md | 8 +- .../connect/clients/om-clients/_index.md | 2 +- content/develop/connect/clients/php.md | 314 ++++++++++++++++++ 3 files changed, 319 insertions(+), 5 deletions(-) create mode 100644 content/develop/connect/clients/php.md diff --git a/content/develop/connect/clients/_index.md b/content/develop/connect/clients/_index.md index 959a436fe2..14741cf7a2 100644 --- a/content/develop/connect/clients/_index.md +++ b/content/develop/connect/clients/_index.md @@ -16,13 +16,14 @@ weight: 45 --- Use the Redis client libraries to connect to Redis servers from -your own code. We support client libraries -for five main languages: +your own code. We document client libraries +for six main languages: - [Python]({{< relref "/develop/connect/clients/python" >}}) - [C#/.NET]({{< relref "/develop/connect/clients/dotnet" >}}) - [Node.js]({{< relref "/develop/connect/clients/nodejs" >}}) - [Java]({{< relref "/develop/connect/clients/java" >}}) - [Go]({{< relref "/develop/connect/clients/go" >}}) +- [PHP]({{< relref "/develop/connect/clients/php" >}}) We also provide several higher-level [object mapping (OM)]({{< relref "/develop/connect/clients/om-clients" >}}) @@ -34,13 +35,12 @@ libraries for [Python]({{< relref "/integrate/redisom-for-python" >}}), ## Community-supported clients The table below shows the recommended third-party client libraries for languages that -Redis does not support directly: +Redis does not document directly: | Language | Client name | Github | Docs | | :-- | :-- | :-- | :-- | | C | hiredis | https://github.com/redis/hiredis | https://github.com/redis/hiredis | | [PHP](https://www.php.net/) | PhpRedis extension | https://github.com/phpredis/phpredis | https://github.com/phpredis/phpredis/blob/develop/README.md | -| [PHP](https://www.php.net/) | Predis library | https://github.com/predis/predis | https://github.com/predis/predis/wiki | | [Ruby](https://www.ruby-lang.org/en/) | redis-rb | https://github.com/redis/redis-rb | https://rubydoc.info/gems/redis | | [Rust](https://www.rust-lang.org/) | redis-rs | https://github.com/redis-rs/redis-rs | https://docs.rs/redis/latest/redis/ | | [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 | diff --git a/content/develop/connect/clients/om-clients/_index.md b/content/develop/connect/clients/om-clients/_index.md index 8a762ed4df..4954932d7d 100644 --- a/content/develop/connect/clients/om-clients/_index.md +++ b/content/develop/connect/clients/om-clients/_index.md @@ -13,7 +13,7 @@ description: Object-Mapper libraries for Redis Stack linkTitle: Object mapping stack: true title: Object-Mapper libraries -weight: 6 +weight: 7 --- 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. diff --git a/content/develop/connect/clients/php.md b/content/develop/connect/clients/php.md new file mode 100644 index 0000000000..b7c59ee160 --- /dev/null +++ b/content/develop/connect/clients/php.md @@ -0,0 +1,314 @@ +--- +categories: +- docs +- develop +- stack +- oss +- rs +- rc +- oss +- kubernetes +- clients +description: Connect your PHP application to a Redis database +linkTitle: PHP +title: PHP guide +weight: 6 +--- + +[`Predis`](https://github.com/predis/predis) is the recommended [PHP](https://php.net/) +client for Redis. +The sections below explain how to install `predis` and connect your application to a Redis database. + +{{< note >}}Although we provide basic documentation for `Predis`, it is a third-party +client library and is not developed or supported directly by Redis. +{{< /note >}} + +`Predis` requires a running Redis or +[Redis Stack]({{< relref "/operate/oss_and_stack/install/install-stack/" >}}) server. +See [Getting started]({{< relref "/operate/oss_and_stack/install/" >}}) for Redis installation +instructions. + +## Install + +Use [Composer](https://getcomposer.org/) to install the `predis` library +with the following command line: + +```bash +composer require predis/predis +``` + +## Connect + +Connect to a locally-running server on the standard port (6379) +with the following code: + +```php + 'tcp', + 'host' => '127.0.0.1', + 'port' => 6379, + 'password' => '', + 'database' => 0, + ]); +``` + +Store and retrieve a simple string to test the connection: + +```php +echo $r->set('foo', 'bar'), PHP_EOL; +// OK + +echo $r->get('foo'), PHP_EOL; +// bar +``` + +Store and retrieve a [hash]({{< relref "/develop/data-types/hashes" >}}) +object: + +```php +$r->hset('user-session:123', 'name', 'John'); +$r->hset('user-session:123', 'surname', 'Smith'); +$r->hset('user-session:123', 'company', 'Redis'); +$r->hset('user-session:123', 'age', 29); + +echo var_export($r->hgetall('user-session:123')), PHP_EOL; +/* +array ( + 'name' => 'John', + 'surname' => 'Smith', + 'company' => 'Redis', + 'age' => '29', +) +*/ +``` + +## Connect to a Redis cluster + +To connect to a Redis cluster, specify one or more of the nodes in +the `clusterNodes` parameter and set `'cluster'=>'redis'` in +`options`: + +```php +$clusterNodes = [ + 'tcp://127.0.0.1:30001', // Node 1 + 'tcp://127.0.0.1:30002', // Node 2 + 'tcp://127.0.0.1:30003', // Node 3 +]; +$options = ['cluster' => 'redis']; + +// Create a Predis client for the cluster +$rc = new PredisClient($clusterNodes, $options); + +echo $rc->cluster('nodes'), PHP_EOL; +/* +d8773e888e92d015b7c52fc66798fd6815afefec 127.0.0.1:30004@40004 slave cde97d1f7dce13e9253ace5cafd3fb0aa67cda63 0 1730713764217 1 connected +58fe1346de4c425d60db24e9b153926fbde0d174 127.0.0.1:30002@40002 master - 0 1730713763361 2 connected 5461-10922 +015ecc8148a05377dda22f19921d16efcdd6d678 127.0.0.1:30006@40006 slave c019b75d8b52e83e7e52724eccc716ac553f71d6 0 1730713764218 3 connected +aca365963a72642e6ae0c9503aabf3be5c260806 127.0.0.1:30005@40005 slave 58fe1346de4c425d60db24e9b153926fbde0d174 0 1730713763363 2 connected +c019b75d8b52e83e7e52724eccc716ac553f71d6 127.0.0.1:30003@40003 myself,master - 0 1730713764000 3 connected 10923-16383 +cde97d1f7dce13e9253ace5cafd3fb0aa67cda63 127.0.0.1:30001@40001 master - 0 1730713764113 1 connected 0-5460 +*/ + +echo $rc->set('foo', 'bar'), PHP_EOL; +// OK +echo $rc->get('foo'), PHP_EOL; +// bar +``` + +## Connect to your production Redis with TLS + +When you deploy your application, use TLS and follow the +[Redis security]({{< relref "/operate/oss_and_stack/management/security/" >}}) +guidelines. + +Use the following commands to generate the client certificate and private key: + +```bash +openssl genrsa -out redis_user_private.key 2048 +openssl req -new -key redis_user_private.key -out redis_user.csr +openssl x509 -req -days 365 -in redis_user.csr -signkey redis_user_private.key -out redis_user.crt +``` + +If you have the [Redis source folder](https://github.com/redis/redis) available, +you can also use generate the certificate and private key with these commands: + +```bash +./utils/gen-test-certs.sh +./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 +``` + +Pass this information during connection using the `ssl` section of `options`: + +```php +$options = [ + 'scheme' => 'tls', // Use 'tls' for SSL connections + 'host' => '127.0.0.1', // Redis server hostname + 'port' => 6379, // Redis server port + 'username' => 'default', // Redis username + 'password' => '', // Redis password + 'options' => [ + 'ssl' => [ + 'verify_peer' => true, // Verify the server's SSL certificate + 'cafile' => './redis_ca.pem', // Path to CA certificate + 'local_cert' => './redis_user.crt', // Path to client certificate + 'local_pk' => './redis_user_private.key', // Path to client private key + ], + ], +]; + +$tlsConnection = new PredisClient($options); + +echo $tlsConnection->set('foo', 'bar'), PHP_EOL; +// OK +echo $tlsConnection->get('foo'), PHP_EOL; +// bar +``` + +## Example: Indexing and querying JSON documents + +This example shows how to index and query Redis JSON data using `predis`. + +Make sure that you have Redis Stack and `predis` installed, as described +in the [Install](#install) section above. + +Start by importing dependencies: + +```php + 'tcp', + 'host' => '127.0.0.1', + 'port' => 6379, + 'password' => '', + 'database' => 0, + ]); +``` + +Create some test data to add to the database: + +```php +$user1 = json_encode([ + 'name' => 'Paul John', + 'email' => 'paul.john@example.com', + 'age' => 42, + 'city' => 'London', +], JSON_THROW_ON_ERROR); + +$user2 = json_encode([ + 'name' => 'Eden Zamir', + 'email' => 'eden.zamir@example.com', + 'age' => 29, + 'city' => 'Tel Aviv', +], JSON_THROW_ON_ERROR); + +$user3 = json_encode([ + 'name' => 'Paul Zamir', + 'email' => 'paul.zamir@example.com', + 'age' => 35, + 'city' => 'Tel Aviv', +], JSON_THROW_ON_ERROR); +``` + +Create an +[index]({{< relref "/develop/interact/search-and-query/indexing" >}}). +In this example, only JSON documents with the key prefix `user:` are indexed. +For more information, see +[Query syntax]({{< relref "/develop/interact/search-and-query/query/" >}}). + +```php +$schema = [ + new TextField('$.name', 'name'), + new TagField('$.city', 'city'), + new NumericField('$.age', "age"), +]; + +try { +$r->ftCreate("idx:users", $schema, + (new CreateArguments()) + ->on('JSON') + ->prefix(["user:"])); +} +catch (Exception $e) { + echo $e->getMessage(), PHP_EOL; +} +``` + +Add the three sets of user data to the database as +[JSON]({{< relref "/develop/data-types/json" >}}) objects. +If you use keys with the `user:` prefix then Redis will index the +objects automatically as you add them: + +```php +$r->jsonset('user:1', '$', $user1); +$r->jsonset('user:2', '$', $user2); +$r->jsonset('user:3', '$', $user3); +``` + +You can now use the index to search the JSON objects. The +[query]({{< relref "/develop/interact/search-and-query/query" >}}) +below searches for objects that have the text "Paul" in any field +and have an `age` value in the range 30 to 40: + +```php +$res = $r->ftSearch("idx:users", "Paul @age:[30 40]"); +echo json_encode($res), PHP_EOL; +// [1,"user:3",["$","{\"name\":\"Paul Zamir\",\"email\":\"paul.zamir@example.com\",\"age\":35,\"city\":\"London\"}"]] +``` + +Specify query options to return only the `city` field: + +```php +$arguments = new SearchArguments(); +$arguments->addReturn(3, '$.city', true, 'thecity'); +$arguments->dialect(2); +$arguments->limit(0, 5); + +$res = $r->ftSearch("idx:users", "Paul", $arguments); + +echo json_encode($res), PHP_EOL; +// [2,"user:1",["thecity","London"],"user:3",["thecity","Tel Aviv"]] +``` + +Use an +[aggregation query]({{< relref "/develop/interact/search-and-query/query/aggregation" >}}) +to count all users in each city. + +```php +$ftAggregateArguments = (new AggregateArguments()) +->groupBy('@city') +->reduce('COUNT', true, 'count'); + +$res = $r->ftAggregate('idx:users', '*', $ftAggregateArguments); +echo json_encode($res), PHP_EOL; +// [2,["city","London","count","1"],["city","Tel Aviv","count","2"]] +``` + +See the [Redis query engine]({{< relref "/develop/interact/search-and-query" >}}) docs +for a full description of all query features with examples. + +## Learn more + +- [Predis wiki on Github](https://github.com/predis/predis/wiki) From 27600d09b64ce7c805f26b7cce087ec7f9f22505 Mon Sep 17 00:00:00 2001 From: andy-stark-redis <164213578+andy-stark-redis@users.noreply.github.com> Date: Tue, 5 Nov 2024 17:05:31 +0000 Subject: [PATCH 2/7] Update content/develop/connect/clients/php.md Co-authored-by: David Dougherty --- content/develop/connect/clients/php.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/develop/connect/clients/php.md b/content/develop/connect/clients/php.md index b7c59ee160..48295f2911 100644 --- a/content/develop/connect/clients/php.md +++ b/content/develop/connect/clients/php.md @@ -17,7 +17,7 @@ weight: 6 [`Predis`](https://github.com/predis/predis) is the recommended [PHP](https://php.net/) client for Redis. -The sections below explain how to install `predis` and connect your application to a Redis database. +The sections below explain how to install `Predis` and connect your application to a Redis database. {{< note >}}Although we provide basic documentation for `Predis`, it is a third-party client library and is not developed or supported directly by Redis. From 799b171c131edee2d768286b3137ac12757f2ea0 Mon Sep 17 00:00:00 2001 From: andy-stark-redis <164213578+andy-stark-redis@users.noreply.github.com> Date: Tue, 5 Nov 2024 17:05:38 +0000 Subject: [PATCH 3/7] Update content/develop/connect/clients/php.md Co-authored-by: David Dougherty --- content/develop/connect/clients/php.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/develop/connect/clients/php.md b/content/develop/connect/clients/php.md index 48295f2911..6cc723de0e 100644 --- a/content/develop/connect/clients/php.md +++ b/content/develop/connect/clients/php.md @@ -30,7 +30,7 @@ instructions. ## Install -Use [Composer](https://getcomposer.org/) to install the `predis` library +Use [Composer](https://getcomposer.org/) to install the `Predis` library with the following command line: ```bash From 3b82c132239edce8930a67b6f4fd9a3f1e539ab4 Mon Sep 17 00:00:00 2001 From: andy-stark-redis <164213578+andy-stark-redis@users.noreply.github.com> Date: Tue, 5 Nov 2024 17:05:45 +0000 Subject: [PATCH 4/7] Update content/develop/connect/clients/php.md Co-authored-by: David Dougherty --- content/develop/connect/clients/php.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/develop/connect/clients/php.md b/content/develop/connect/clients/php.md index 6cc723de0e..af2b59598f 100644 --- a/content/develop/connect/clients/php.md +++ b/content/develop/connect/clients/php.md @@ -136,7 +136,7 @@ openssl x509 -req -days 365 -in redis_user.csr -signkey redis_user_private.key - ``` If you have the [Redis source folder](https://github.com/redis/redis) available, -you can also use generate the certificate and private key with these commands: +you can also generate the certificate and private key with these commands: ```bash ./utils/gen-test-certs.sh From 4713f692940c0ecadea27061bbafb64a3c77c616 Mon Sep 17 00:00:00 2001 From: Andy Stark Date: Wed, 6 Nov 2024 09:39:50 +0000 Subject: [PATCH 5/7] DOC-4520 remove defaults from basic connection example --- content/develop/connect/clients/php.md | 10 ++-------- 1 file changed, 2 insertions(+), 8 deletions(-) diff --git a/content/develop/connect/clients/php.md b/content/develop/connect/clients/php.md index af2b59598f..e2f0bd4fdf 100644 --- a/content/develop/connect/clients/php.md +++ b/content/develop/connect/clients/php.md @@ -49,13 +49,7 @@ require 'vendor/autoload.php'; use Predis\Client as PredisClient; -$r = new PredisClient([ - 'scheme' => 'tcp', - 'host' => '127.0.0.1', - 'port' => 6379, - 'password' => '', - 'database' => 0, - ]); +$r = new PredisClient(); ``` Store and retrieve a simple string to test the connection: @@ -78,7 +72,7 @@ $r->hset('user-session:123', 'company', 'Redis'); $r->hset('user-session:123', 'age', 29); echo var_export($r->hgetall('user-session:123')), PHP_EOL; -/* +/* >>> array ( 'name' => 'John', 'surname' => 'Smith', From c664ed2f1df6ed229fad3357b968510b0e5f9d66 Mon Sep 17 00:00:00 2001 From: Andy Stark Date: Wed, 6 Nov 2024 09:43:12 +0000 Subject: [PATCH 6/7] DOC-4520 added >>> before output comments --- content/develop/connect/clients/php.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/content/develop/connect/clients/php.md b/content/develop/connect/clients/php.md index e2f0bd4fdf..1c81beb955 100644 --- a/content/develop/connect/clients/php.md +++ b/content/develop/connect/clients/php.md @@ -56,10 +56,10 @@ Store and retrieve a simple string to test the connection: ```php echo $r->set('foo', 'bar'), PHP_EOL; -// OK +// >>> OK echo $r->get('foo'), PHP_EOL; -// bar +// >>> bar ``` Store and retrieve a [hash]({{< relref "/develop/data-types/hashes" >}}) @@ -100,7 +100,7 @@ $options = ['cluster' => 'redis']; $rc = new PredisClient($clusterNodes, $options); echo $rc->cluster('nodes'), PHP_EOL; -/* +/* >>> d8773e888e92d015b7c52fc66798fd6815afefec 127.0.0.1:30004@40004 slave cde97d1f7dce13e9253ace5cafd3fb0aa67cda63 0 1730713764217 1 connected 58fe1346de4c425d60db24e9b153926fbde0d174 127.0.0.1:30002@40002 master - 0 1730713763361 2 connected 5461-10922 015ecc8148a05377dda22f19921d16efcdd6d678 127.0.0.1:30006@40006 slave c019b75d8b52e83e7e52724eccc716ac553f71d6 0 1730713764218 3 connected @@ -110,9 +110,9 @@ cde97d1f7dce13e9253ace5cafd3fb0aa67cda63 127.0.0.1:30001@40001 master - 0 173071 */ echo $rc->set('foo', 'bar'), PHP_EOL; -// OK +// >>> OK echo $rc->get('foo'), PHP_EOL; -// bar +// >>> bar ``` ## Connect to your production Redis with TLS @@ -159,9 +159,9 @@ $options = [ $tlsConnection = new PredisClient($options); echo $tlsConnection->set('foo', 'bar'), PHP_EOL; -// OK +// >>> OK echo $tlsConnection->get('foo'), PHP_EOL; -// bar +// >>> bar ``` ## Example: Indexing and querying JSON documents @@ -269,7 +269,7 @@ and have an `age` value in the range 30 to 40: ```php $res = $r->ftSearch("idx:users", "Paul @age:[30 40]"); echo json_encode($res), PHP_EOL; -// [1,"user:3",["$","{\"name\":\"Paul Zamir\",\"email\":\"paul.zamir@example.com\",\"age\":35,\"city\":\"London\"}"]] +// >>> [1,"user:3",["$","{\"name\":\"Paul Zamir\",\"email\":\"paul.zamir@example.com\",\"age\":35,\"city\":\"London\"}"]] ``` Specify query options to return only the `city` field: @@ -283,7 +283,7 @@ $arguments->limit(0, 5); $res = $r->ftSearch("idx:users", "Paul", $arguments); echo json_encode($res), PHP_EOL; -// [2,"user:1",["thecity","London"],"user:3",["thecity","Tel Aviv"]] +// >>> [2,"user:1",["thecity","London"],"user:3",["thecity","Tel Aviv"]] ``` Use an @@ -297,7 +297,7 @@ $ftAggregateArguments = (new AggregateArguments()) $res = $r->ftAggregate('idx:users', '*', $ftAggregateArguments); echo json_encode($res), PHP_EOL; -// [2,["city","London","count","1"],["city","Tel Aviv","count","2"]] +// >>> [2,["city","London","count","1"],["city","Tel Aviv","count","2"]] ``` See the [Redis query engine]({{< relref "/develop/interact/search-and-query" >}}) docs From 82123f8b3509d07d7e4197e45ee811d6e99d8e64 Mon Sep 17 00:00:00 2001 From: Andy Stark Date: Wed, 6 Nov 2024 10:30:39 +0000 Subject: [PATCH 7/7] DOC-4520 add table of client support/doc status' --- content/develop/connect/clients/_index.md | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/content/develop/connect/clients/_index.md b/content/develop/connect/clients/_index.md index 14741cf7a2..33b61ec26a 100644 --- a/content/develop/connect/clients/_index.md +++ b/content/develop/connect/clients/_index.md @@ -16,14 +16,19 @@ weight: 45 --- Use the Redis client libraries to connect to Redis servers from -your own code. We document client libraries +your own code. We document the following client libraries for six main languages: -- [Python]({{< relref "/develop/connect/clients/python" >}}) -- [C#/.NET]({{< relref "/develop/connect/clients/dotnet" >}}) -- [Node.js]({{< relref "/develop/connect/clients/nodejs" >}}) -- [Java]({{< relref "/develop/connect/clients/java" >}}) -- [Go]({{< relref "/develop/connect/clients/go" >}}) -- [PHP]({{< relref "/develop/connect/clients/php" >}}) + +| Language | Client name | Docs | Supported | +| :-- | :-- | :-- | :-- | +| [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 | +| [Python](https://www.python.org/) | [`RedisVL`](https://github.com/redis/redis-vl-python) |[RedisVL guide]({{< relref "/integrate/redisvl" >}}) | Yes +| [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 | +| [Node.js](https://nodejs.org/en) | [`node-redis`](https://github.com/redis/node-redis) | [Node.js guide]({{< relref "/develop/connect/clients/nodejs" >}}) | Yes | +| [Java](https://www.java.com/en/) | [`Jedis`](https://github.com/redis/jedis) | [Jedis guide]({{< relref "/develop/connect/clients/java/jedis" >}}) | Yes | +| [Java](https://www.java.com/en/) | [`Lettuce`](https://github.com/redis/lettuce) | [Lettuce guide]({{< relref "/develop/connect/clients/java/lettuce" >}}) | Yes | +| [Go](https://go.dev/) | [`go-redis`](https://github.com/redis/go-redis) | [Go guide]({{< relref "/develop/connect/clients/go" >}}) | Yes | +| [PHP](https://www.php.net/)| [`Predis`](https://github.com/predis/predis) | [PHP guide]({{< relref "/develop/connect/clients/php" >}}) | No | We also provide several higher-level [object mapping (OM)]({{< relref "/develop/connect/clients/om-clients" >}})