PHPackages                             karmabunny/rdb - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Caching](/categories/caching)
4. /
5. karmabunny/rdb

ActiveLibrary[Caching](/categories/caching)

karmabunny/rdb
==============

Redis wrapper for KB things

v1.33.21(2mo ago)04.0k↓42.5%2MITPHPPHP >=7.2CI passing

Since Apr 30Pushed 2mo ago7 watchersCompare

[ Source](https://github.com/Karmabunny/kbrdb)[ Packagist](https://packagist.org/packages/karmabunny/rdb)[ RSS](/packages/karmabunny-rdb/feed)WikiDiscussions master Synced 1mo ago

READMEChangelogDependencies (18)Versions (61)Used By (2)

Rdb
===

[](#rdb)

Like Pdb, but for Redis. I guess.

This wraps existing Redis clients and normalises the API (between server versions and client implementations). It also introduces a few additional helpers:

- Object serialization
- Leaky bucket rate limiting
- Locking
- Export/import
- Session handler

Also because I don't want a hard dependency on either predis or php-redis. They both have their problems (vague magical commands API, binary extension, etc). Or wouldn't it be wonderful if a 3rd option showed up /s. Also supports credis.

### Install

[](#install)

Add as a dependency:

```
composer require karmabunny/rdb
```

### Adapters

[](#adapters)

- php-redis (binary extension)
- predis (composer package)
- credis (composer package)

This library doesn't implement a redis client itself, only wraps existing clients. After much effort trying to normalise the responses from all these client, it might seem like a good idea to just write our own that isn't so inconsistent.

But consider that we only *know* how inconsistent these libraries are because we've spent so much time trying to make them all behave the same. For example, client 'A' might do 'B' well but 'C' badly. Then client 'D' does 'B' badly but 'C' really well.

So as I sit here and scoff at their feeble attempts, I am reminded of a few things:

1. I've already introduced so many of my own bugs during this journey.
2. Unit testing is a gift from heaven.
3. Normalising these inconsistencies has improved our own consistency, something probably not as achievable when writing a new client from scratch.
4. also this:

### Version support

[](#version-support)

This wrapper doesn't try to polyfill any missing features. It targets Redis server v3.0, as that's the common support among all the adapters.

This library wouldn't ever try to *hide* features behind target versions, but perhaps it could help smooth out any differences. Lua scripting could polyfill a lot of things tbh.

For example, `BRPOPLPUSH` is deprecated in v6.2 and might be removed in the distant future. In this case, the library would be able to dynamically replace (based on the server version) this with `BLMOVE`.

### Plans for v2

[](#plans-for-v2)

**TTL params**

There is a preference for the millisecond version of a command, particularly TTL parameters. This is clearly misleading and already wildly inconsistent. Ideally this changes so that a 'float' is converted to the millisecond version and integer remains unchanged. Thus the input is always 'seconds'. The implementation should include the 'p' millisecond version of each command, similar to how we've implemented `incr/decr`.

**Type errors**

Type errors are currently (hopefully) always a `null` return. This can quite confusing at times, or helpful in others. Version 2 will likely permit both, defaulting to emitting exceptions.

**Object methods**

The expected type in the object method is currently optional, but most drivers required it. Version 2 will make them required.

### Config

[](#config)

KeyDefaultDescriptionhost127.0.0.1Server name + portprefix''Key prefixadapter'predis'Adapter type: predis, php-redis, credisobject\_driverPhpObjectDriverObject driver classtimeout5Connection timeout, in secondslock\_sleep5Tick size for locking, in millisecondschunk\_size50Max key size for mscan methodsscan\_size1000Count hint for scan methodsscan\_keysfalseReplace keys() with scan()options\[\]Adapter specific optionsNotes:

- The port number is default 6379 unless specified in the `host` option.
- The protocol can be adjusted in the `host` option too: prefix `tcp://` or `udp://`.

```
return [
    'host' => 'localhost',
    'prefix' => 'sitecode:',

    // Defaults
    'adapter' => 'predis',
    'object_driver' => JsonObjectDriver::class,
    'timeout' => 5,
    'lock_sleep' => 5,
    'chunk_size' => 50,
    'scan_size' => 1000,
    'scan_keys' => false,
    'options' => [],
];
```

#### Adapter options

[](#adapter-options)

**Predis**

The predis adapter accepts any options supported by the Predis client.

OptionDescriptionuse\_predis\_sessionUse the predis session handlerexceptionsEnable exceptions on errorsconnectionsConnection settingsclusterCluster configurationreplicationReplication configuration**PhpRedis**

OptionDescriptionuse\_native\_sessionUse the native session handlerretry\_intervalTime between reconnection attemptsread\_timeoutSocket read timeout**Credis**

OptionDescriptionuse\_native\_sessiononly if `standalone = false`standaloneForce standalone mode vs phpredis### Object drivers

[](#object-drivers)

The object driver is responsible for serialising and deserialising objects for the 'object methods'.

These are:

- `setObject`
- `getObject`
- `mSetObjects`
- `mGetObjects`

Available drivers:

- `PhpObjectDriver` (default)
- `JsonObjectDriver`
- `MsgPackObjectDriver`
- `HashObjectDriver`

### Usage

[](#usage)

Basic usage with a TTL. Great for caching.

```
use karmabunny\rdb\Rdb;

$config = require 'config.php';
$rdb = Rdb::create($config);

// Store 'blah' for 100 ms
$rdb->set('key', 'blah', 100);

$rdb->get('key');
// => blah

usleep(150 * 1000);

$rdb->get('key');
// => NULL
```

Object extensions will serialize in the PHP format. These have builtin assertions so things are always the correct shape.

```
$model = new MyModel('etc');
$rdb->setObject('objects:key', $model);

$rdb->getObject('objects:key', MyModel::class);
// => MyModel( etc )

$rdb->getObject('objects:key', OtherModel::class);
// => NULL
```

Locking provides a mechanism to restrict atomic access to a resource.

```
// Wait for a lock for up to 10 seconds.
$lock = $rdb->lock('locks:key', 10 * 1000);

if ($lock === null) {
    echo "Busy - too much contention\n";
}
else {
    // Do atomic things.
    $lock->release();
}
```

[Leaky bucket](https://en.wikipedia.org/wiki/Leaky_bucket) is a rate-limiting algorithm. It's cute, easy to understand, and not too complex.

```
// A bucket with 60 drips per minute.
$bucket = $rdb->getBucket([
    'key' => 'key',

    // Defaults.
    'capacity' => 60,
    'drip_rate' => 1,

    // Optional.
    'prefix' => 'drips:',
    'costs' => [
        'GET' => 1,
        'POST' => 10,
    ],
]);

// One drip.
$full = $bucket->drip();

if ($full) {
    echo "We're full, please wait {$bucket->getWait()} ms\n";
}
else {
    // Do things.
}

// Big drip.
$bucket->drip(20);

// Named drip (10 drips).
$bucket->drip('POST');

// Write out the status to the headers for easy debugging.
$bucket->writeHeaders();
```

### Contributing

[](#contributing)

Submit a PR if you like. But before you do, please do the following:

1. Run `composer analyse` and fix any complaints there
2. Run `composer compat` and fix those too
3. Write some tests and run `composer tests`
4. Document the methods here

### Methods

[](#methods)

#### Core Methods

[](#core-methods)

- keys
- scan
- del
- exists
- ttl
- expire
- expireat
- type
- rename
- move
- select
- dump/restore

scalar:

- get
- set
- mGet
- mSet
- append
- substr
- getRange
- incrBy
- decrBy
- incrByFloat
- decrByFloat

sets:

- sMembers
- sAdd
- sRem
- sCard
- sIsMember
- sMove
- sScan
- TODO sRandMember
- TODO sDiff (+ store)
- TODO sInter (+ store)
- TODO sUnion (+ store)

lists:

- lLen
- lRange
- lTrim
- lSet
- lRem
- lIndex
- lPush
- lPop
- blPop
- rPush
- rPop
- brPop
- brPoplPush

sorted sets:

- zAdd
- zIncrBy
- zRange
- zRem
- zCard
- zCount
- zScore
- zRank
- zRevRank

hashes:

- hSet
- hGet
- hExists
- hDel
- hmSet
- hmGet
- hGetAll
- hIncrBy/hIncrByFloat
- hKeys
- hVals
- hLen
- hScan
- hStrLen

#### Extended/Wrapper Methods

[](#extendedwrapper-methods)

- mScan
- getObject
- setObject
- mGetObjects
- mScanObjects
- mSetObjects
- setJson
- getJson
- setHash/getHash (nested arrays in hash)
- pack/unpack (MessagePack format)
- incr/decr
- hIncr/hDecr
- export/import

#### Builtin Utilities

[](#builtin-utilities)

- 'Leaky bucket' rate limiting
- Locking

###  Health Score

49

—

FairBetter than 95% of packages

Maintenance86

Actively maintained with recent releases

Popularity22

Limited adoption so far

Community16

Small or concentrated contributor base

Maturity61

Established project with proven stability

 Bus Factor1

Top contributor holds 98.1% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~32 days

Total

56

Last Release

70d ago

PHP version history (3 changes)v1.10.7PHP >=7.0

v1.15.8PHP >=7.1

v1.20.9PHP >=7.2

### Community

Maintainers

![](https://www.gravatar.com/avatar/11b33084210490439a6fb2c0b277e0bf39f8d0e368f20bebb703834003a617df?d=identicon)[karmabunny](/maintainers/karmabunny)

---

Top Contributors

[![gwillz](https://avatars.githubusercontent.com/u/3466850?v=4)](https://github.com/gwillz "gwillz (302 commits)")[![jamiemonksuk](https://avatars.githubusercontent.com/u/25573428?v=4)](https://github.com/jamiemonksuk "jamiemonksuk (6 commits)")

---

Tags

redisRDB

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Type Coverage Yes

### Embed Badge

![Health badge](/badges/karmabunny-rdb/health.svg)

```
[![Health](https://phpackages.com/badges/karmabunny-rdb/health.svg)](https://phpackages.com/packages/karmabunny-rdb)
```

###  Alternatives

[rhubarbgroup/redis-cache

A persistent object cache backend for WordPress powered by Redis. Supports Predis, PhpRedis, Relay, replication, sentinels, clustering and WP-CLI.

51795.3k1](/packages/rhubarbgroup-redis-cache)[resque/php-resque

Redis backed library for creating background jobs and processing them later. Based on resque for Ruby.

2371.8M7](/packages/resque-php-resque)[predis/predis-async

Asynchronous version of Predis

366348.4k](/packages/predis-predis-async)[monospice/laravel-redis-sentinel-drivers

Redis Sentinel integration for Laravel and Lumen.

103830.5k](/packages/monospice-laravel-redis-sentinel-drivers)[predis/service-provider

Predis service provider for the Silex microframework

68546.6k1](/packages/predis-service-provider)[jamescauwelier/psredis

Sentinel client for the popular php redis client

77392.9k5](/packages/jamescauwelier-psredis)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)