Skip to content

fix: yiisoft/yii2-redis 2.1.x requires an explicit connection #752

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
AugustMiller merged 3 commits into from
Jan 14, 2026
Merged

fix: yiisoft/yii2-redis 2.1.x requires an explicit connection #752

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
59f368d
fix: yii/redis 2.1.x requires an explicit connection
roelvanhintum Dec 29, 2025
f51aecb
Add redis connection config to mutex and session
AugustMiller Jan 14, 2026
1d5badf
Note required package
AugustMiller Jan 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 48 additions & 4 deletions docs/4.x/config/app.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,6 +74,7 @@ return [
$config = [
'class' => yii\redis\Cache::class,
'redis' => [
'class' => yii\redis\Connection::class,
// ... Redis connection configuration
],
];
Expand Down Expand Up @@ -209,6 +210,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,
Expand All @@ -222,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
Expand Down Expand Up @@ -338,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,
Expand All @@ -351,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
Expand Down Expand Up @@ -433,6 +436,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,
Expand Down Expand Up @@ -471,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,
Expand All @@ -491,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 <craft4:craft\mutex\Mutex>. 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 <craft4:craft\mutex\Mutex>.
We only need to replace the driver, using the component’s nested `mutex` property.
:::

<a name="mutex-redis"></a>

#### Redis Example

Like the [session](#session), [cache](#cache), and [queue](#queue), the mutex component can take advantage of a Redis connection:

```php
<?php

use craft\helpers\App;

return [
'components' => [
'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
Expand Down
61 changes: 57 additions & 4 deletions docs/5.x/reference/config/app.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -85,6 +85,7 @@ return [
$config = [
'class' => yii\redis\Cache::class,
'redis' => [
'class' => yii\redis\Connection::class,
// ... Redis connection configuration
],
];
Expand Down Expand Up @@ -220,6 +221,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,
Expand All @@ -233,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
Expand Down Expand Up @@ -332,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
<?php
Expand All @@ -349,6 +353,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,
Expand All @@ -362,7 +367,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
Expand Down Expand Up @@ -444,6 +449,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,
Expand Down Expand Up @@ -499,7 +505,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,
Expand All @@ -518,7 +524,49 @@ 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 <craft5:craft\mutex\Mutex>. 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 <craft5:craft\mutex\Mutex>.
We only need to replace the driver, using the component’s nested `mutex` property.
:::

<a name="mutex-redis"></a>

#### Redis Example

Like the [session](#session), [cache](#cache), and [queue](#queue), the mutex component can take advantage of a Redis connection.

Install the [yii2-redis](https://www.yiiframework.com/extension/yiisoft/yii2-redis) package and replace your `mutex` component’s nested `mutex` property with `yii\redis\Mutex::class`, along with a complete connection object:

```php
<?php

use craft\helpers\App;

return [
'components' => [
'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
Expand All @@ -537,6 +585,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 <Since ver="5.3.0" feature="CORS and headers filters" />

To set arbitrary headers on every site response, attach <craft5:craft\filters\Headers> to the root _web_ application, in `config/app.web.php`:
Expand Down