This is a documentation-only PR!

I am on the Craft CMS team, and we got a few reports of configuration issues after updating to version 2.1.0:

• [5.x]: Incompatible with yiisoft/yii2-redis 2.1.0 craftcms/docs#754
• [5.x]: REDIS error following docs craftcms/cms#18236
• [5.x]: Not instantiable – yii\di\NotInstantiableException - Can not instantiate yii\redis\ConnectionInterface. craftcms/cms#18227

As best we could tell, this isn't the result of a bug per se, but rather a difference in how per-component connections need to be defined now that they are not initilized with a concrete class. This used to be an acceptable nested configuration array:

[
    'hostname' => 'localhost',
    'port' => 6379,
    'password' => 'pass',
    'database' => 0,
]

Now, a class key is required:

[
    'class' => yii\redis\Connection::class,
    'hostname' => 'localhost',
    'port' => 6379,
    'password' => 'pass',
    'database' => 0,
]

Anyone using the default connection (referred to by the component’s ID, 'redis') was not impacted. However, we have recommended using discrete connections for each component (cache, mutex, and sessions) due to the way flushing works when sharing a database.

This attempts to describe the tradeoffs involved with a centrally-defined connection (as its own redis component), versus discrete, nested connections for each component that uses it. It also modernizes some of the config syntax to use the ::class qualifier (rather than a string), adds a dedicated mutex page, and cleans up some grammar and cross-references, throughout.

Ultimately, it's a bit of an inversion in the recommendations—instead of saying "define your connection once; use it everywhere," the reality is that whether you use Redis in one component or many, you probably want to define the connection at the point of use.