Skip to content

Add Valkey support to Winter CMS documentation #244

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

Open
rlunar wants to merge 1 commit into
base: develop
Choose a base branch
from
Open

Add Valkey support to Winter CMS documentation #244

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
14 changes: 11 additions & 3 deletions services/cache.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,17 +2,17 @@

## Configuration

Winter provides a unified API for various caching systems and the cache configuration is located at `config/cache.php`. In this file you may specify which cache driver you would like used by default throughout your application. Popular caching systems like [Memcached](http://memcached.org) and [Redis](http://redis.io) are supported out of the box.
Winter provides a unified API for various caching systems and the cache configuration is located at `config/cache.php`. In this file you may specify which cache driver you would like used by default throughout your application. Popular caching systems like [Memcached](http://memcached.org), [Redis](http://redis.io), and [Valkey](https://valkey.io) are supported out of the box.

The cache configuration file also contains various other options, which are documented within the file, so make sure to read over these options. By default, Winter CMS is configured to use the `file` cache driver which stores the serialized, cached objects in the filesystem. For larger applications, it is recommended that you use an in-memory cache such as Memcached or Redis. You may even configure multiple cache configurations for the same driver.
The cache configuration file also contains various other options, which are documented within the file, so make sure to read over these options. By default, Winter CMS is configured to use the `file` cache driver which stores the serialized, cached objects in the filesystem. For larger applications, it is recommended that you use an in-memory cache such as Memcached, Redis, or Valkey. You may even configure multiple cache configurations for the same driver.

## Pre-requisites

### Database

The `database` cache driver uses the database in lieu of the file system. There is no other configuration required to use this type as the database structure is already available.

Database caching can be less performant than using a dedicated caching system such as Memcached or Redis. For high-traffic or
Database caching can be less performant than using a dedicated caching system such as Memcached, Redis, or Valkey. For high-traffic or
larger applications, it is recommended to use one of these options instead.

### Memcached
Expand Down Expand Up @@ -114,6 +114,14 @@ When using `predis`, you may define an `options` array value in your Redis conne

If your Redis server requires authentication, you may supply a password by adding a `password` configuration item to your Redis server configuration array.

### Valkey

[Valkey](https://valkey.io) is an open-source, high-performance key-value datastore that serves as a drop-in replacement for Redis. It offers the same functionality and performance as Redis while being community-driven with improved governance.

Since Valkey is protocol-compatible with Redis, it uses the same configuration as Redis. You can use the existing Redis configuration section in `config/database.php` for Valkey connections. Both the `predis` and `phpredis` clients work seamlessly with Valkey, requiring no additional configuration changes.

To use Valkey instead of Redis, simply point your Redis configuration to your Valkey server instance. All Redis configuration examples in this documentation apply equally to Valkey.

Comment on lines +117 to +124
Copy link
Member

@bennothommo bennothommo Jul 31, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This section reads too much like a promotion of Valkey. I'd prefer if we do not include a section for Valkey and just change the Redis section above to "Redis / Valkey" instead as necessary, with maybe a small mention that Valkey is a drop-in replacement for Redis.

Suggested change
### Valkey
[Valkey](https://valkey.io) is an open-source, high-performance key-value datastore that serves as a drop-in replacement for Redis. It offers the same functionality and performance as Redis while being community-driven with improved governance.
Since Valkey is protocol-compatible with Redis, it uses the same configuration as Redis. You can use the existing Redis configuration section in `config/database.php` for Valkey connections. Both the `predis` and `phpredis` clients work seamlessly with Valkey, requiring no additional configuration changes.
To use Valkey instead of Redis, simply point your Redis configuration to your Valkey server instance. All Redis configuration examples in this documentation apply equally to Valkey.

### APCu

The APCu cache driver can be used in conjunction with the [APCu PECL extension](http://pecl.php.net/package/apcu). No configuration is required for this caching system, as this is configured through your `php.ini` configuration.
Expand Down
4 changes: 2 additions & 2 deletions services/queues.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@

Queues allow you to defer the processing of a time consuming task, such as sending an e-mail, until a later time, thus drastically speeding up the web requests to your application.

The queue configuration file is stored in `config/queue.php`. In this file you will find connection configurations for each of the queue drivers that are included, such as a database, [Beanstalkd](http://kr.github.com/beanstalkd), [IronMQ](http://iron.io), [Amazon SQS](http://aws.amazon.com/sqs) and [Redis](http://redis.io).
The queue configuration file is stored in `config/queue.php`. In this file you will find connection configurations for each of the queue drivers that are included, such as a database, [Beanstalkd](http://kr.github.com/beanstalkd), [IronMQ](http://iron.io), [Amazon SQS](http://aws.amazon.com/sqs), [Redis](http://redis.io), and [Valkey](https://valkey.io).

Two special queue drivers are also available:

Expand All @@ -13,7 +13,7 @@ Two special queue drivers are also available:

### Driver prerequisites

Before using the Amazon SQS, Beanstalkd, IronMQ or Redis drivers you will need to install [Drivers plugin](https://github.com/wintercms/wn-drivers-plugin).
Before using the Amazon SQS, Beanstalkd, IronMQ, Redis, or Valkey drivers you will need to install [Drivers plugin](https://github.com/wintercms/wn-drivers-plugin).

## Basic usage

Expand Down
4 changes: 2 additions & 2 deletions services/session.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

## Configuration

Since HTTP driven applications are stateless, sessions provide a way to store information about the user across requests. Winter ships with a variety of session backends available for use through a clean, unified API. Support for popular backends such as [Memcached](https://memcached.org), [Redis](https://redis.io), and databases is included out of the box.
Since HTTP driven applications are stateless, sessions provide a way to store information about the user across requests. Winter ships with a variety of session backends available for use through a clean, unified API. Support for popular backends such as [Memcached](https://memcached.org), [Redis](https://redis.io), [Valkey](https://valkey.io), and databases is included out of the box.

The session configuration is stored in `config/session.php`. Be sure to review the well documented options available to you in this file. By default, Winter is configured to use the `file` session driver, which will work well for the majority of applications.

Expand All @@ -11,7 +11,7 @@ The session configuration is stored in `config/session.php`. Be sure to review t
- `file` - sessions are stored in `storage/framework/sessions`.
- `cookie` - sessions are stored in secure, encrypted cookies.
- `database` - sessions are stored in a database used by your application.
- `memcached` / `redis` - sessions are stored in one of these fast, cache based stores.
- `memcached` / `redis` / `valkey` - sessions are stored in one of these fast, cache based stores.
Copy link
Member

@bennothommo bennothommo Jul 31, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

valkey is not an applicable session driver as far as I know. Valkey still uses the redis driver.

Suggested change
- `memcached` / `redis` / `valkey` - sessions are stored in one of these fast, cache based stores.
- `memcached` / `redis` - sessions are stored in one of these fast, cache based stores.

- `array` - sessions are stored in a simple PHP array and will not be persisted across requests.

</div>
Expand Down