Download the PHP package flytachi/winter-redis without Composer

Winter Redis

📖 Documentation · Configuration · Stores · Streams

Pooled Redis for PHP that stays resident.

A Redis connection is one socket with a sequential protocol. In classic PHP that never mattered: a process served one request and died. A worker that lives for weeks and serves many requests at once cannot share a socket between them, and cannot afford to open one per request either. This package puts a pool in between, and gives the application stores and typed handles instead of a raw client.

Built on flytachi/winter-cpool: under Swoole every coroutine gets its own connection and returns it automatically; everywhere else a single self-maintaining connection does the same job. The calling code is identical.

Installation

Requires PHP 8.4+ and ext-redis. ext-swoole is optional: with it you get real pooling, without it the same code keeps working through one connection.

Quick start

Declare an endpoint:

Declare a slice of it:

Use it:

No connection to obtain, none to return, no select(). The connection is taken on the first command and goes back to the pool when the request ends.

What you get from it

A connection per unit of work. Two coroutines never share a socket, so commands never interleave. The return is automatic — a coroutine defer, not a finally you have to remember.

A bounded number of connections. A thousand concurrent requests do not become a thousand connections: they queue, and a request fails on a timeout instead of the database answering max number of clients reached.

Connections that heal. An idle connection is probed before it is handed over, an aged one is rotated. A Redis restart stops poisoning the worker for the rest of its life.

A key prefix that means something. Several stores share one database without colliding, keys() and flush() are scoped to the store, and flush() refuses outright when there is no prefix to scope it to.

Refusals that look like refusals. phpredis reports a rejected command by returning false and parking the message on the connection; cast into a return type that becomes a counter reading 0. Here it is an exception, and the connection goes back clean.

A taste of the API

Fork safety and shutdown

reset() forgets inherited connections without closing them — a fork copies descriptors, and closing would tear down the parent's socket. shutdown() is the opposite and belongs at worker exit; it is only required if background housekeeping is enabled, because a live timer keeps the reactor from draining.

Under the Winter kernel both lines are already there: Kernel::init() registers them when it sees the package, and shutdown() runs on workerExit. The snippet above is for using this package on its own.

Observability

The numbers are per worker: each worker holds its own pool. active sitting at maximum while borrowers wait is the signal to raise the ceiling — or to find the request holding a connection while it waits on something else.

stats() reports coroutine pools, so outside Swoole it is empty by design: there is one self-maintaining connection per config and nothing to distribute. pingDetail() answers in both runtimes and is what a health endpoint should call.

Documentation

The user-facing documentation lives at winterframe.net/docs/redis (the link picks your language; RU and EN are both complete).

Start here

Structures

Operating it

Contributing

Internal technical notes — the connection model, the driver behaviours the code works around, and the rules for adding a structure — live in docs/. Read those before changing how a connection is obtained or returned.

XDEBUG_MODE=off matters: Xdebug's function observers do not survive coroutine stacks, so a green run can still exit 139.

• Setup, the testing philosophy and the documentation rules: CONTRIBUTING.md
• Changes and upgrade notes: CHANGELOG.md
• Reporting a vulnerability, and what the package does and does not guarantee: SECURITY.md

License

MIT License. See LICENSE.