feat: improvements for redis related documentation (#1560)

* feat: improvements for redis relate documentation

* Apply suggestions from code review

---------

Co-authored-by: Bojan Rajh <[email protected]>

guides/hosting/infrastructure/redis.md

@@ -18,6 +18,8 @@ The data stored in Redis can be roughly classified into those three categories:
 2. Durable, but "aging" data: This data is important and cannot easily be recreated, but the relevance of the data decreases over time, e.g. sessions.
 3. Durable and critical data: This data is important and cannot easily be recreated, e.g. carts, number ranges.
 
+Please note, that in current Redis versions, it is not possible to use different eviction policies for different databases in the same Redis instance. Therefore, it is recommended to use separate Redis instances for different types of data. 
+
 ## Ephemeral data
 
 As ephemeral data can easily be restored and is most often used in cases where high performance matters, this data can be stored with no durable persistence. 
@@ -59,11 +61,37 @@ shopware:
             ephemeral:
                 dsn: 'redis://host1:port/dbindex'
             persistent:
-                dsn: 'redis://host2:port/dbindex?persistent=1'
+                dsn: 'redis://host2:port/dbindex'
 ```
 
 Connection names should reflect the actual connection purpose/type and be unique. Also, the names are used as part of the service names in the container, so they should follow the service naming conventions. After defining connections, you can reference them by name in the configuration of different subsystems.
 
+It's possible to use environment variables in the DSN string, e.g. if `REDIS_EPHEMERAL` is set to `redis://host1:port`, the configuration could look like this:
+
+```yaml
+shopware:
+    # ...
+    redis:
+        connections:
+            ephemeral_1:
+                dsn: '%env(REDIS_EPHEMERAL)%/1' # using database 1
+            ephemeral_2:
+                dsn: '%env(REDIS_EPHEMERAL)%/2' # using database 2
+```
+
+### Connection pooling
+
+In high-load scenarios, it is recommended to use persistent connections to avoid the overhead of establishing a new connection for each request. This can be achieved by setting the `persistent` flag in DSN to `1`:
+```yaml
+shopware:
+    redis:
+        connections:
+            ephemeral:
+                dsn: 'redis://host:port/dbindex?persistent=1'
+```
+Please note that the persistent flag influences connection pooling, not persistent storage of data.
+
+
 <PageRef page="../performance/cart-storage" />
 
 <PageRef page="../performance/number-ranges" />

guides/hosting/performance/cart-storage.md

@@ -42,8 +42,7 @@ shopware:
 ```
 </Tab>
 </Tabs>
-
-It is recommended to use a persistent Redis connection to avoid connection issues in high-load scenarios.
+Note that the `?persistent=1` parameter here refers to the connection pooling, not the persistent storage of data. Please refer to the [Redis configuration guide](../infrastructure/redis) for more information.*
 
 ## Migrating between storages
 

guides/hosting/performance/increment.md

@@ -45,7 +45,7 @@ shopware:
     redis:
         connections:
             persistent:
-                dsn: 'redis://host:port/dbindex?persistent=1'
+                dsn: 'redis://host:port/dbindex'
 
     increment:
         user_activity:

guides/hosting/performance/number-ranges.md

@@ -36,7 +36,7 @@ shopware:
     redis:
         connections:
             persistent:
-                dsn: 'redis://host:port/dbindex?persistent=1'
+                dsn: 'redis://host:port/dbindex'
     number_range:
         increment_storage: 'redis'
         config:

guides/plugins/plugins/redis.md

@@ -9,6 +9,8 @@ nav:
 
 Starting with Shopware v6.6.8.0, Redis support has been improved, giving you more flexibility in how you use it in your projects and plugins.
 
+## Accessing Redis connections
+
 Once you've set up your Redis connections as explained in the  [Redis configuration](../../hosting/infrastructure/redis) guide, you can access them in your code using the following methods:
 
 1. Inject `Shopware\Core\Framework\Adapter\Redis\RedisConnectionProvider` and retrieve connections by name:
@@ -55,7 +57,7 @@ Once you've set up your Redis connections as explained in the  [Redis configurat
     class MyCustomService
     { 
         public function __construct (
-            private Redis $redisConnection,
+            private object $redisConnection,
         ) { }
 
         public function doSomething()
@@ -74,4 +76,22 @@ Once you've set up your Redis connections as explained in the  [Redis configurat
     ```
    Be cautious with this approach! If you change the Redis connection names in your configuration, it will cause container build errors.
 
-Keep in mind that Redis is an optional dependency in Shopware and might not be available in all installations.
+## Redis usage tips
+
+### Connection types
+Under the hood, connection service objects are created using the `\Symfony\Component\Cache\Adapter\RedisAdapter::createConnection` method.
+Depending on the installed extensions/libraries and the provided DSN, this method may return instance of one of the following classes:
+`\Redis|Relay|\RedisArray|\RedisCluster|\Predis\ClientInterface`
+
+### Reusing connections
+Connections are cached in a static variable and reused based on the provided DSN. If you use the same DSN for multiple connections, they will share the same connection object.
+This means you need to be cautious when closing or modifying connection options, as it will affect all services using the same connection.
+
+### Connection initialization
+The moment actual connection is established depends on the usage model:
+* When `RedisConnectionProvider::getConnection` is called.
+* When the Redis connection service is requested from the container.
+* When a service that depends on Redis connection is instantiated.
+
+### Redis is optional
+When developing a plugin, please keep in mind that Redis is an optional dependency in Shopware and might not be available in all installations.