Skip to content

Migration Guide PHPRedis

Jump to bottom
James Duong edited this page Sep 16, 2025 · 2 revisions

Migration Guide: From PHPRedis to Valkey GLIDE PHP

This guide helps you migrate from PHPRedis to Valkey GLIDE PHP, highlighting key differences and providing code examples for common use cases.

Overview

Valkey GLIDE PHP is a high-performance client for Valkey and Redis that provides:

  • Better performance through Rust-based core with FFI bindings
  • Connection pooling with automatic connection management
  • Type safety with comprehensive PHP type hints
  • Cluster support with automatic failover and resharding
  • Cross-platform compatibility (Linux, macOS, Windows)

Installation

PHPRedis (old)

pecl install redis

Valkey GLIDE PHP (new)

pie install valkey-io/valkey-glide-php

Or via Composer:

composer require valkey-io/valkey-glide-php

Basic Connection

PHPRedis

$redis = new Redis();
$redis->connect('127.0.0.1', 6379);
$redis->auth('password');
$redis->select(1);

Valkey GLIDE PHP

use ValkeyGlide\ValkeyGlide;

$client = new ValkeyGlide(
    addresses: [['host' => '127.0.0.1', 'port' => 6379]],
    use_tls: false,
    credentials: ['password'],
    database_id: 1
);

Cluster Connection

PHPRedis

$redis = new RedisCluster(null, ['127.0.0.1:7000', '127.0.0.1:7001']);

Valkey GLIDE PHP

use ValkeyGlide\ValkeyGlideCluster;

$client = new ValkeyGlideCluster([
    ['host' => '127.0.0.1', 'port' => 7000],
    ['host' => '127.0.0.1', 'port' => 7001]
]);

Common Operations

String Operations

PHPRedis

$redis->set('key', 'value');
$value = $redis->get('key');
$redis->setex('key', 3600, 'value'); // TTL in seconds
$redis->mset(['key1' => 'val1', 'key2' => 'val2']);
$values = $redis->mget(['key1', 'key2']);

Valkey GLIDE PHP

$client->set('key', 'value');
$value = $client->get('key');
$client->setex('key', 3600, 'value');
$client->mset(['key1' => 'val1', 'key2' => 'val2']);
$values = $client->mget(['key1', 'key2']);

Hash Operations

PHPRedis

$redis->hset('hash', 'field', 'value');
$value = $redis->hget('hash', 'field');
$redis->hmset('hash', ['field1' => 'val1', 'field2' => 'val2']);
$values = $redis->hmget('hash', ['field1', 'field2']);
$all = $redis->hgetall('hash');

Valkey GLIDE PHP

$client->hset('hash', 'field', 'value');
$value = $client->hget('hash', 'field');
$client->hmset('hash', ['field1' => 'val1', 'field2' => 'val2']);
$values = $client->hmget('hash', ['field1', 'field2']);
$all = $client->hgetall('hash');

List Operations

PHPRedis

$redis->lpush('list', 'value');
$redis->rpush('list', 'value');
$value = $redis->lpop('list');
$value = $redis->rpop('list');
$length = $redis->llen('list');
$range = $redis->lrange('list', 0, -1);

Valkey GLIDE PHP

$client->lpush('list', ['value']);
$client->rpush('list', ['value']);
$value = $client->lpop('list');
$value = $client->rpop('list');
$length = $client->llen('list');
$range = $client->lrange('list', 0, -1);

Set Operations

PHPRedis

$redis->sadd('set', 'member');
$redis->srem('set', 'member');
$members = $redis->smembers('set');
$exists = $redis->sismember('set', 'member');
$count = $redis->scard('set');

Valkey GLIDE PHP

$client->sadd('set', ['member']);
$client->srem('set', ['member']);
$members = $client->smembers('set');
$exists = $client->sismember('set', 'member');
$count = $client->scard('set');

Key Differences

1. Method Signatures

  • PHPRedis: Variadic arguments for multi-value operations
  • Valkey GLIDE: Supports both variadic arguments AND array parameters
// Both PHPRedis and Valkey GLIDE support variadic style
$redis->sadd('set', 'val1', 'val2', 'val3');
$client->sadd('set', 'val1', 'val2', 'val3');

// Valkey GLIDE also supports array style for consistency
$client->del(['key1', 'key2', 'key3']); // Array style
$client->del('key1', 'key2', 'key3');   // Variadic style

2. Return Types

  • PHPRedis: Mixed return types, sometimes inconsistent
  • Valkey GLIDE: Consistent, typed return values
// PHPRedis - returns int|false
$result = $redis->set('key', 'value');

// Valkey GLIDE - returns string "OK" or throws exception
$result = $client->set('key', 'value');

3. Error Handling

  • PHPRedis: Returns false on error, throws exceptions in constructors
  • Valkey GLIDE: Same pattern - returns false on method errors, throws exceptions only in constructors
// Both PHPRedis and Valkey GLIDE - constructors throw exceptions
try {
    $client = new ValkeyGlide($config);
} catch (Exception $e) {
    // Handle connection/configuration errors
}

// Both PHPRedis and Valkey GLIDE - methods return false on error
if ($client->get('nonexistent') === false) {
    // Could be error or key doesn't exist - check with exists()
}

4. Configuration

  • PHPRedis: Method chaining for configuration
  • Valkey GLIDE: Constructor parameters
// PHPRedis
$redis->setOption(Redis::OPT_SERIALIZER, Redis::SERIALIZER_JSON);
$redis->setOption(Redis::OPT_PREFIX, 'myapp:');

// Valkey GLIDE
$client = new ValkeyGlide(
    addresses: [['host' => '127.0.0.1', 'port' => 6379]],
    request_timeout: 5000,
    client_name: 'myapp'
);

Advanced Features

Note: Advanced features like transactions and pub/sub are planned for future releases.

Migration Checklist

  • Update installation method to use PIE or Composer
  • Replace connection code with ConnectionRequest pattern
  • Update method calls to use array parameters where needed
  • Add exception handling around all Redis operations
  • Update return type expectations for consistency
  • Test cluster failover scenarios if using cluster mode
  • Update configuration to use ConnectionRequest options
  • Verify serialization behavior matches expectations
  • Verify serialization behavior matches expectations
  • Performance test to validate improvements

Performance Benefits

Valkey GLIDE PHP typically provides:

  • 2-5x faster command execution
  • Lower memory usage due to efficient Rust core
  • Better connection pooling with automatic management
  • Reduced latency through optimized protocol handling

Compatibility Notes

  • PHP Version: Requires PHP 8.1+
  • Redis/Valkey: Compatible with Redis 6.0+ and all Valkey versions
  • Extensions: No conflicts with other Redis extensions
  • Serialization: Built-in support for JSON, PHP serialize, and custom serializers

Getting Help

Example: Complete Migration

Before (PHPRedis)

<?php
$redis = new Redis();
$redis->connect('127.0.0.1', 6379);
$redis->auth('mypassword');
$redis->select(2);

try {
    $redis->set('user:1', json_encode(['name' => 'John', 'age' => 30]));
    $userData = json_decode($redis->get('user:1'), true);
    
    $redis->hset('user:1:profile', 'email', '[email protected]');
    $email = $redis->hget('user:1:profile', 'email');
    
    echo "User: {$userData['name']}, Email: $email\n";
} catch (Exception $e) {
    echo "Error: " . $e->getMessage() . "\n";
}

After (Valkey GLIDE PHP)

<?php
use ValkeyGlide\ValkeyGlide;

$client = new ValkeyGlide(
    addresses: [['host' => '127.0.0.1', 'port' => 6379]],
    credentials: ['mypassword'],
    database_id: 2
);

try {
    $client->set('user:1', json_encode(['name' => 'John', 'age' => 30]));
    $userData = json_decode($client->get('user:1'), true);
    
    $client->hset('user:1:profile', 'email', '[email protected]');
    $email = $client->hget('user:1:profile', 'email');
    
    echo "User: {$userData['name']}, Email: $email\n";
} catch (Exception $e) {
    echo "Error: " . $e->getMessage() . "\n";
}

The migration provides immediate performance benefits while maintaining familiar Redis command patterns.

Clone this wiki locally