Valkey-PHP

About Valkey-PHP

Valkey-PHP is a comprehensive PHP client for Valkey, designed to provide a unified, high-performance interface for PHP applications. This project merges the best features of phpredis/phpredis and webdcg/redis into a single, well-maintained library under the Valkey Project by the Linux Foundation.

Key Features

• Complete Valkey Command Coverage: 100% support for all Valkey commands with comprehensive test coverage
• High-Level Abstractions: Similar to Valkeyson in Java, offering object-oriented interfaces for complex data structures
• Dual Interface: Both a PHP extension (for maximum performance) and a pure PHP implementation (for maximum compatibility)
• Forever Open Source: BSD-3-Clause license under the Linux Foundation ensures the project remains open and free
• Valkey Compatibility: Maintained in sync with Valkey development while preserving compatibility with Valkey OSS
• Enterprise-Ready: Clustering, sentinel support, connection pooling, and other features needed for production deployments

Installation

PHP Extension (Recommended for Production)

pecl install valkey

Add the following to your php.ini:

extension=valkey.so

Composer (PHP Library)

composer require valkey/valkey-php

Quick Start

<?php

// Using the extension
$valkey = new Valkey();
$valkey->connect('127.0.0.1', 6379);
$valkey->set('key', 'value');
echo $valkey->get('key'); // Outputs: value

// Using the PHP library with fluent interface
use Valkey\Client;

$valkey = new Client();
$valkey->connect('127.0.0.1', 6379)
       ->set('key', 'value')
       ->expire('key', 3600);
       
echo $valkey->get('key'); // Outputs: value

// Using high-level abstractions
$map = $valkey->getMap('user:profile:1');
$map->put('name', 'Robert');
$map->put('email', '[email protected]');

echo $map->get('name'); // Outputs: Robert

High-Level Abstractions

Valkey-PHP provides Valkeyson-like abstractions for complex data structures:

• Maps: php $map = $valkey->getMap('map-key');
• Lists: php $list = $valkey->getList('list-key');
• Sets: php $set = $valkey->getSet('set-key');
• Sorted Sets: php $zset = $valkey->getSortedSet('zset-key');
• Locks: php $lock = $valkey->getLock('lock-key');
• Pub/Sub: php $topic = $valkey->getTopic('channel');
• Streams: php $stream = $valkey->getStream('stream-key');

Project Goals

• Unified API: Merge the strengths of valkey-php (performance) and webdcg/redis (developer experience)
• 100% Command Coverage: Support all Valkey commands with comprehensive tests
• Open Source Forever: BSD-3-Clause license under Linux Foundation governance
• Valkey Compatibility: Stay in sync with Valkey while maintaining Valkey OSS compatibility
• High-Level Abstractions: Provide Java Valkeyson-like interfaces for PHP developers
• Performance: Optimize for speed while maintaining clean interfaces

Migrating from valkey-php or webdcg/redis

We provide compatibility layers to make migration from either library as smooth as possible:

// For PHPValkey users
use Valkey\Compat\Valkey;
$valkey = new Valkey();

// For webdcg/redis users
use Valkey\Compat\WebdcgValkey;
$valkey = new WebdcgValkey();

Documentation

Comprehensive documentation is available at valkey-php.dev/docs

Table of contents

1. Installation
2. Classes and methods
   • Usage
   • Bitmaps
   • Connection
   • Geospatial Indexes
   • Hashes
   • HyperLogLogs
   • Introspection
   • Keys
   • Lists
   • Pub/sub
   • Scripting
   • Sets
   • Sorted sets
   • Streams
   • Strings
   • Transactions

Classes and methods

Usage

$valkey = new Valkey();

Bitmaps

$valkey = new Valkey();
$valkey->bitCount('key');
$valkey->bitField('key', 'INCRBY, 'i5', 100, 1, 'GET', 'u4', 0);
$valkey->bitFieldReadOnly('key', 'INCRBY, 'i5', 100, 1, 'GET', 'u4', 0);
$valkey->bitOp('and', 'testBitOpAnd', 'testBit1', 'testBit2');
$valkey->bitpos('key', 0);
$valkey->getBit('key', 5);
$valkey->setBit('key', 8, 1);

Connection

$valkey = new Valkey();
$valkey->connect('127.0.0.1', 6379);
$valkey->open('127.0.0.1', 6379);
$valkey->pconnect('127.0.0.1', 6379);
$valkey->popen('127.0.0.1', 6379);
$valkey->auth('secret');
$valkey->select(1);
$valkey->swapdb(0, 1);
$valkey->close();
$valkey->setOption(Valkey::OPT_PREFIX, 'redis:');
$valkey->getOption(Valkey::OPT_PREFIX)
$valkey->ping('pong');
$valkey->echo('redis');

Geospatial Indexes

$valkey = new Valkey();
$valkey->connect('127.0.0.1', 6379);
$options = ['WITHDIST'];
$valkey->geoAdd('Geocoding', -122.431, 37.773, 'San Francisco');
$valkey->geoAdd('Geocoding', -73.935242, 40.730610, 'New York');
$valkey->geoHash('Geocoding', 'San Francisco');
$valkey->geoPos('Geocoding', 'San Francisco');
$valkey->geoDist('Geocoding', 'San Francisco', 'New York');
$valkey->geoRadius("Geocoding", -157.858, 21.306, 300, 'mi', $options);
$valkey->geoRadiusByMember("Geocoding", 'San Francisco', 300, 'mi', $options);

Hashes

$valkey = new Valkey();
$valkey->connect('127.0.0.1', 6379);
$valkey->hSet('hash', 'key1', 'hello'); /* 1, 'key1' => 'hello' in the hash at "h" */
$valkey->hGet('hash', 'key1'); /* returns "hello" */
$valkey->hSetNx('hash', 'key1', 'hello'); /* TRUE, 'key1' => 'hello' in the hash at "hash" */
$valkey->hLen('hash'); /* returns 2 */
$valkey->hGetAll('hash');
$valkey->hKeys('hash');
$valkey->hVals('hash');

HyperLogLogs

$valkey->pfAdd('HyperLogLog', ['a', 'b', 'c']);
$valkey->pfCount('HyperLogLog'); // 3
$valkey->pfAdd('HyperLogLog2', ['b', 'd']);
$valkey->pfMerge('HyperLogLogMerged', ['HyperLogLog', 'HyperLogLog2']);
$valkey->pfCount('HyperLogLogMerged'); // 4 => a, b, c, d

Introspection

$valkey = new Valkey();
$valkey->connect('127.0.0.1', 6379);
$valkey->isConnected();
$valkey->getHost();
$valkey->getPort();
$valkey->getDbNum();
$valkey->getTimeout();
$valkey->getReadTimeout();
$valkey->getPersistentID();
$valkey->getAuth();

Keys

$valkey = new Valkey();
$valkey->connect('127.0.0.1', 6379);
$valkey->del('key');
$valkey->delete('key');
$valkey->unlink('key');
$valkey->dump('key');
$valkey->exists('key');
$valkey->expire('key', 123);
$valkey->expireAt('key', 1743016214.623306);
$valkey->keys();
$valkey->scan();
$valkey->migrate('key');
$valkey->move('key');
$valkey->object('key');
$valkey->persist('key');
$valkey->randomKey('key');
$valkey->rename('key', 'yek');
$valkey->renameNx('key', 'yek');
$valkey->type('key');
$valkey->sort('key');
$valkey->ttl('key');
$valkey->restore('key');

Lists

$valkey = new Valkey();
$valkey->connect('127.0.0.1', 6379);
/* Non blocking feature */
$valkey->lPush('key1', 'A');
$valkey->del('key2');
$valkey->blPop('key1', 'key2', 10); /* ['key1', 'A'] */
$valkey->rPush('key1', 'A');
$valkey->lInsert('key1', Valkey::AFTER, 'A', 'X'); /* 0 */
$valkey->lRange('key1', 0, -1); /* ['A', 'B', 'X', 'C'] */

Pub/sub

$valkey = new Valkey();
$valkey->connect('127.0.0.1', 6379);
/* Non blocking feature */
$valkey->lPush('key1', 'A');
$valkey->del('key2');
$valkey->blPop('key1', 'key2', 10); /* ['key1', 'A'] */
$valkey->rPush('key1', 'A');
$valkey->lInsert('key1', Valkey::AFTER, 'A', 'X'); /* 0 */
$valkey->lRange('key1', 0, -1); /* ['A', 'B', 'X', 'C'] */

Scripting

$valkey = new Valkey();
$valkey->connect('127.0.0.1', 6379);
$valkey->eval("return 1"); // Returns an integer: 1
$valkey->eval("return {1,2,3}"); // Returns [1,2,3]
$valkey->del('mylist');
$valkey->rpush('mylist','a');
$valkey->rpush('mylist','b');
$valkey->rpush('mylist','c');
// Nested response:  [1,2,3,['a','b','c']];
$valkey->eval("return {1,2,3,redis.call('lrange','mylist',0,-1)}");

Sets

$valkey = new Valkey();
$valkey->connect('127.0.0.1', 6379);
$valkey->sAdd('key1' , 'member1');
$valkey->sAdd('key1' , 'member2');
$valkey->sAdd('key1' , 'member3'); /* 'key1' => {'member1', 'member2', 'member3'}*/
$valkey->sCard('key1'); /* 3 */
$valkey->sIsMember('key1', 'member1'); /* TRUE */
$valkey->sIsMember('key1', 'memberX'); /* FALSE */

Sorted Sets

$valkey = new Valkey();
$valkey->connect('127.0.0.1', 6379);
$valkey->zAdd('key', 1, 'val1');
$valkey->zAdd('key', 0, 'val0');
$valkey->zAdd('key', 5, 'val5');
$valkey->zRange('key', 0, -1); // [val0, val1, val5]
// From Valkey 3.0.2 it's possible to add options like XX, NX, CH, INCR
$valkey->zAdd('key', ['CH'], 5, 'val5', 10, 'val10', 15, 'val15');

Streams

$valkey = new Valkey();
$valkey->connect('127.0.0.1', 6379);
$obj_redis->xAdd('mystream', "*", ['field' => 'value']);
$obj_redis->xAdd('mystream', "*", ['field' => 'value'], 1000); // set max length of stream to 1000
$obj_redis->xAdd('mystream', "*", ['field' => 'value'], 1000, true); // set max length of stream to ~1000
$obj_redis->xAck('mystream', 'group1', ['1530063064286-0', '1530063064286-1']);
/* Get everything in this stream */
$obj_redis->xRange('mystream', '-', '+');
/* Only the first two messages */
$obj_redis->xRange('mystream', '-', '+', 2);
$obj_redis->xInfo('STREAM', 'mystream', 'FULL', 10);
$obj_redis->xRead(['stream1' => '1535222584555-0', 'stream2' => '1535222584555-0']);
$obj_redis->xDel('mystream', ['1530115304877-0', '1530115305731-0']);

Strings

$valkey = new Valkey();
$valkey->connect('127.0.0.1', 6379);
// Simple key -> value set
$valkey->set('key', 'value');
// Will redirect, and actually make an SETEX call
$valkey->set('key', 'value', 10);
// Will set the key, if it doesn't exist, with a ttl of 10 seconds
$valkey->set('key:'.time(), 'value', ['nx', 'ex' => 10]);
// Will set a key, if it does exist, with a ttl of 1000 miliseconds
$valkey->set('key', 'value', ['xx', 'px' => 1000]);
$valkey->setEx('key', 10, 'value1');
$valkey->append('key', 'value2'); /* 12 */
$valkey->get('key'); /* 'value1value2' */
$valkey->exists('key'); /* 1 */
$valkey->exists('NonExistingKey'); /* 0 */
$valkey->mset(['foo' => 'foo', 'bar' => 'bar', 'baz' => 'baz']);
$valkey->exists(['foo', 'bar', 'baz']); /* 3 */

Transactions

$valkey = new Valkey();
$valkey->connect('127.0.0.1', 6379);
$ret = $valkey->multi()
    ->set('key1', 'val1')
    ->get('key1')
    ->set('key2', 'val2')
    ->get('key2')
    ->exec();

Contributing

We welcome contributions! Please see CONTRIBUTING.md for details on how to get started.

License

Valkey-PHP is open-sourced software licensed under the BSD-3-Clause license.

Credits

• Roberto Luna Rojas
• Adrian Luna Rojas
• All Contributors

Acknowledgements

This project builds upon the excellent work of:

• phpredis/phpredis
• webdcg/redis

We thank all the contributors to these projects for their valuable work.

Support

• GitHub Issues
• Discord Community
• Stack Overflow