phpdot/redis

Coroutine-safe Redis client wrapping ext-redis with auto-reconnect, exponential backoff, exception translation, and a pool connector for phpdot/pool.

v0.1.1 2026-07-18 19:00 UTC

Requires

• php: >=8.5
• ext-redis: ^6.0
• phpdot/contracts: ^0.1

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.94
• phpdot/container: ^0.1
• phpstan/phpstan: ^2.0
• phpstan/phpstan-strict-rules: ^2.0
• phpunit/phpunit: ^13.0

MIT

• Omar Hamdan

• redis
• phpredis
• swoole
• connection-pool
• coroutine-safe
• phpdot
• ext-redis

Published on Packagist.org on 2026-07-18 19:57 UTC

README

A coroutine-safe Redis client wrapping ext-redis (phpredis). It adds automatic reconnection with exponential backoff, translates driver errors into typed exceptions, and ships a connector so phpdot/pool can hold and recycle connections. One \Redis client lives per connection, so a pool gives each Swoole coroutine its own.

Table of Contents

• Requirements
• Installation
• Usage
• Architecture
• Testing
• License

Requirements

Requirement	Constraint
PHP	>= 8.5
ext-redis	^6.0
phpdot/contracts	^0.1

phpdot/container is a dev-only suggestion — the #[Config('redis')] attribute on RedisConfig is inert until a phpdot application reflects it.

Installation

composer require phpdot/redis

Usage

Connecting

use PHPdot\Redis\Config\RedisConfig;
use PHPdot\Redis\RedisConnection;

$connection = new RedisConnection(new RedisConfig(
    host: '127.0.0.1',
    port: 6379,
    password: 'secret',
    database: 0,
));

$connection->connect();

// Reach the underlying ext-redis \Redis client for commands
$connection->getClient()->set('hello', 'world');
$connection->getClient()->get('hello'); // 'world'

$connection->close();

RedisConfig is an immutable value object carrying every ext-redis connection option — host/port or a Unix socket path, username/password (ACL or legacy AUTH), database, TLS with stream SSL options, timeouts, and maxRetries for the backoff.

Resilience

connect() retries with exponential backoff (100ms, 200ms, 400ms, …) up to maxRetries before throwing a ConnectionException. Authentication failures throw an AuthenticationException immediately — retrying bad credentials never helps. Both extend the package's RedisException base.

Pooling

RedisConnector adapts a RedisConnection to phpdot/pool's ConnectorInterface, so a pool can build, health-check, and recycle connections:

use PHPdot\Redis\RedisConnector;

$connector = new RedisConnector(new RedisConfig(host: '127.0.0.1'));
// hand $connector to a phpdot/pool Pool — connect() opens, isAlive() pings, close() tears down

Architecture

RedisConnection owns one ext-redis \Redis client and drives its lifecycle — connecting with backoff, pinging for liveness, and translating RedisExceptions into the package's typed hierarchy. RedisConnector is the thin bridge to phpdot/pool, so the connection type stays pool-agnostic.

graph TD
    APP["Application / phpdot/pool"]
    CONNECTOR["RedisConnector<br/><br/>Contracts Pool ConnectorInterface:<br/>connect / isAlive / close"]
    CONN["RedisConnection<br/><br/>lifecycle, backoff reconnect,<br/>exception translation"]
    CONFIG["RedisConfig<br/><br/>immutable connection settings<br/>(#[Config('redis')])"]
    EXT["ext-redis \\Redis<br/><br/>the phpredis client"]

    APP --> CONNECTOR
    CONNECTOR --> CONN
    CONFIG --> CONN
    CONN --> EXT

Loading

Testing

composer install
composer test        # PHPUnit
composer analyse     # PHPStan, level max + strict rules
composer cs-check    # PHP-CS-Fixer
composer check       # All three

The unit suite covers the disconnected-state contract with no server. The integration suite connects to a live Redis at 127.0.0.1:6379 and skips automatically when none is reachable.

License

MIT.

This repository is a read-only mirror, generated by CI from phpdot/monorepo. Pull requests and issues belong in the monorepo.