From 59f368dc72a94125d5466dd79104189b53805da3 Mon Sep 17 00:00:00 2001 From: Roel van Hintum Date: Mon, 29 Dec 2025 10:51:20 +0100 Subject: [PATCH 1/3] fix: yii/redis 2.1.x requires an explicit connection --- docs/4.x/config/app.md | 2 ++ docs/5.x/reference/config/app.md | 2 ++ 2 files changed, 4 insertions(+) diff --git a/docs/4.x/config/app.md b/docs/4.x/config/app.md index 147c698e1..47d3826e5 100644 --- a/docs/4.x/config/app.md +++ b/docs/4.x/config/app.md @@ -209,6 +209,7 @@ return [ // Full Redis connection details: 'redis' => [ + 'class' => yii\redis\Connection::class, 'hostname' => App::env('REDIS_HOSTNAME') ?: 'localhost', 'port' => 6379, 'password' => App::env('REDIS_PASSWORD') ?: null, @@ -433,6 +434,7 @@ return [ 'proxyQueue' => [ 'class' => yii\queue\redis\Queue::class, 'redis' => [ + 'class' => yii\redis\Connection::class, 'hostname' => App::env('REDIS_HOSTNAME') ?: 'localhost', 'port' => 6379, 'password' => App::env('REDIS_PASSWORD') ?: null, diff --git a/docs/5.x/reference/config/app.md b/docs/5.x/reference/config/app.md index e561a6f9b..2a4ed4be1 100644 --- a/docs/5.x/reference/config/app.md +++ b/docs/5.x/reference/config/app.md @@ -220,6 +220,7 @@ return [ // Full Redis connection details: 'redis' => [ + 'class' => yii\redis\Connection::class, 'hostname' => App::env('REDIS_HOSTNAME') ?: 'localhost', 'port' => 6379, 'password' => App::env('REDIS_PASSWORD') ?: null, @@ -444,6 +445,7 @@ return [ 'proxyQueue' => [ 'class' => yii\queue\redis\Queue::class, 'redis' => [ + 'class' => yii\redis\Connection::class, 'hostname' => App::env('REDIS_HOSTNAME') ?: 'localhost', 'port' => 6379, 'password' => App::env('REDIS_PASSWORD') ?: null, From f51aecb8337f6566bdbe0339289de41ff67caf76 Mon Sep 17 00:00:00 2001 From: August Miller Date: Wed, 14 Jan 2026 10:36:37 -0800 Subject: [PATCH 2/3] Add redis connection config to mutex and session We don't currently supply queue config examples, so only the warnings have been adjusted. --- docs/4.x/config/app.md | 50 ++++++++++++++++++++++++++--- docs/5.x/reference/config/app.md | 55 +++++++++++++++++++++++++++++--- 2 files changed, 97 insertions(+), 8 deletions(-) diff --git a/docs/4.x/config/app.md b/docs/4.x/config/app.md index 47d3826e5..9755f7f5f 100644 --- a/docs/4.x/config/app.md +++ b/docs/4.x/config/app.md @@ -74,6 +74,7 @@ return [ $config = [ 'class' => yii\redis\Cache::class, 'redis' => [ + 'class' => yii\redis\Connection::class, // ... Redis connection configuration ], ]; @@ -223,7 +224,7 @@ return [ ``` ::: warning -If you are also using Redis for [session](#session-redis) storage or the [queue](#queue), you should [set a unique `database`](https://www.yiiframework.com/extension/yiisoft/yii2-redis/doc/api/2.0/yii-redis-connection#$database-detail) for each component’s connection to prevent inadvertently flushing important data! +If you are also using Redis for [session](#session-redis) storage, [mutex](#mutex-redis), or the [queue](#queue), you should [set a unique `database`](https://www.yiiframework.com/extension/yiisoft/yii2-redis/doc/api/2.0/yii-redis-connection#$database-detail) for each component’s connection to prevent inadvertently flushing important data! ::: ### Database @@ -339,6 +340,7 @@ return [ // Define additional properties: $config['redis'] = [ + 'class' => yii\redis\Connection::class, 'hostname' => App::env('REDIS_HOSTNAME') ?: 'localhost', 'port' => 6379, 'password' => App::env('REDIS_PASSWORD') ?: null, @@ -352,7 +354,7 @@ return [ ``` ::: warning -If you are sharing a Redis server between multiple components, you should [set a unique `database`](https://www.yiiframework.com/extension/yiisoft/yii2-redis/doc/api/2.0/yii-redis-connection#$database-detail) for each one. +If you are also using Redis for the [cache](#cache-redis), [mutex](#mutex-redis) or the [queue](#queue), you should [set a unique `database`](https://www.yiiframework.com/extension/yiisoft/yii2-redis/doc/api/2.0/yii-redis-connection#$database-detail) for each component’s connection to prevent inadvertently flushing important data! ::: #### Database Example @@ -473,7 +475,7 @@ return [ $generalConfig = Craft::$app->getConfig()->getGeneral(); $config = [ - 'class' => craft\mutex\File::class, + 'class' => craft\mutex\Mutex::class, // Alter just this nested property of the main mutex component: 'mutex' => [ 'class' => yii\mutex\FileMutex::class, @@ -493,7 +495,47 @@ return [ The specific properties that you can (or must) use in the configuration object will differ based on the specified mutex class—check the driver’s documentation for instructions. ::: warning -The primary mutex _component_ should always be an instance of . We’re only modifying the existing `mutex` component’s nested _driver_ property and leaving the rest of its config as-is! +The primary mutex _component_ should always be an instance of . +We only need to replace the driver, using the component’s nested `mutex` property. +::: + + + +#### Redis Example + +Like the [session](#session), [cache](#cache), and [queue](#queue), the mutex component can take advantage of a Redis connection: + +```php + [ + 'mutex' => function() { + // Build a new configuration object: + $config = [ + 'class' => craft\mutex\Mutex::class, + 'mutex' => [ + 'class' => yii\redis\Mutex::class, + 'redis' => [ + 'class' => yii\redis\Connection::class, + 'hostname' => App::env('REDIS_HOSTNAME') ?: 'localhost', + 'port' => 6379, + 'password' => App::env('REDIS_PASSWORD') ?: null, + ], + ], + ]; + + // Return the initialized component: + return Craft::createObject($config); + } + ], +]; +``` + +::: warning +If you are also using Redis for the [cache](#cache-redis), [session](#session-redis) storage, or the [queue](#queue), you should [set a unique `database`](https://www.yiiframework.com/extension/yiisoft/yii2-redis/doc/api/2.0/yii-redis-connection#$database-detail) for each component’s connection to prevent inadvertently flushing important data! ::: ## Modules diff --git a/docs/5.x/reference/config/app.md b/docs/5.x/reference/config/app.md index 2a4ed4be1..94e47f587 100644 --- a/docs/5.x/reference/config/app.md +++ b/docs/5.x/reference/config/app.md @@ -85,6 +85,7 @@ return [ $config = [ 'class' => yii\redis\Cache::class, 'redis' => [ + 'class' => yii\redis\Connection::class, // ... Redis connection configuration ], ]; @@ -234,7 +235,7 @@ return [ ``` ::: warning -If you are also using Redis for [session](#session-redis) storage or the [queue](#queue), you should [set a unique `database`](https://www.yiiframework.com/extension/yiisoft/yii2-redis/doc/api/2.0/yii-redis-connection#$database-detail) for each component’s connection to prevent inadvertently flushing important data! +If you are also using Redis for [session](#session-redis) storage, [mutex](#mutex-redis), or the [queue](#queue), you should [set a unique `database`](https://www.yiiframework.com/extension/yiisoft/yii2-redis/doc/api/2.0/yii-redis-connection#$database-detail) for each component’s connection to prevent inadvertently flushing important data! ::: ### Database @@ -350,6 +351,7 @@ return [ // Define additional properties: $config['redis'] = [ + 'class' => yii\redis\Connection::class, 'hostname' => App::env('REDIS_HOSTNAME') ?: 'localhost', 'port' => 6379, 'password' => App::env('REDIS_PASSWORD') ?: null, @@ -363,7 +365,7 @@ return [ ``` ::: warning -If you are sharing a Redis server between multiple components, you should [set a unique `database`](https://www.yiiframework.com/extension/yiisoft/yii2-redis/doc/api/2.0/yii-redis-connection#$database-detail) for each one. +If you are also using Redis for the [cache](#cache-redis), [mutex](#mutex-redis), or the [queue](#queue), you should [set a unique `database`](https://www.yiiframework.com/extension/yiisoft/yii2-redis/doc/api/2.0/yii-redis-connection#$database-detail) for each component’s connection to prevent inadvertently flushing important data! ::: #### Database Example @@ -501,7 +503,7 @@ return [ $config = [ 'class' => craft\mutex\Mutex::class, - // Alter just this nested property of the main mutex component: + // Swap out the default database driver: 'mutex' => [ 'class' => yii\mutex\FileMutex::class, 'fileMode' => $generalConfig->defaultFileMode, @@ -520,7 +522,47 @@ return [ The specific properties that you can (or must) use in the configuration object will differ based on the specified mutex class—check the driver’s documentation for instructions. ::: warning -The primary mutex _component_ should always be an instance of . We’re only modifying the existing `mutex` component’s nested _driver_ property and leaving the rest of its config as-is! +The primary mutex _component_ should always be an instance of . +We only need to replace the driver, using the component’s nested `mutex` property. +::: + + + +#### Redis Example + +Like the [session](#session), [cache](#cache), and [queue](#queue), the mutex component can take advantage of a Redis connection: + +```php + [ + 'mutex' => function() { + // Build a new configuration object: + $config = [ + 'class' => craft\mutex\Mutex::class, + 'mutex' => [ + 'class' => yii\redis\Mutex::class, + 'redis' => [ + 'class' => yii\redis\Connection::class, + 'hostname' => App::env('REDIS_HOSTNAME') ?: 'localhost', + 'port' => 6379, + 'password' => App::env('REDIS_PASSWORD') ?: null, + ], + ], + ]; + + // Return the initialized component: + return Craft::createObject($config); + } + ], +]; +``` + +::: warning +If you are also using Redis for the [cache](#cache-redis), [session](#session-redis) storage, or the [queue](#queue), you should [set a unique `database`](https://www.yiiframework.com/extension/yiisoft/yii2-redis/doc/api/2.0/yii-redis-connection#$database-detail) for each component’s connection to prevent inadvertently flushing important data! ::: ## Modules @@ -539,6 +581,11 @@ return [ ]; ``` +::: tip +Using the generator to scaffold a module will attempt to insert this configuration into `app.php` for you. +If it can’t, instructions for modifying it manually are output to the console. +::: + ## Requests + Responses To set arbitrary headers on every site response, attach to the root _web_ application, in `config/app.web.php`: From 1d5badf29c791d855aefb641991db0bd7f21ed5b Mon Sep 17 00:00:00 2001 From: August Miller Date: Wed, 14 Jan 2026 10:36:46 -0800 Subject: [PATCH 3/3] Note required package --- docs/5.x/reference/config/app.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/5.x/reference/config/app.md b/docs/5.x/reference/config/app.md index 94e47f587..3b1a5ca33 100644 --- a/docs/5.x/reference/config/app.md +++ b/docs/5.x/reference/config/app.md @@ -334,6 +334,8 @@ The `session` component should only be overridden from `app.web.php` so it gets #### Redis Example +To use Redis for session storage, install [yii2-redis](https://www.yiiframework.com/extension/yiisoft/yii2-redis) and replace your `session` component with `yii\redis\Session::class`, providing connection details to its nested `redis` property: + ```php // config/app.web.php