Connections

For the most part, Relay can be used just like PhpRedis. There are some exceptions.

$redis = new Relay;
$redis->connect('127.0.0.1', 6379);
$redis->auth('secret');

However Relay will (unlike PhpRedis) reuse socket connections to Redis across all FPM workers.

$relay1 = new Relay(host: '127.0.0.1');
$relay2 = new Relay(host: '127.0.0.1');

// different objects
spl_object_id($relay1); // int(1337)
spl_object_id($relay2); // int(1338)

// same connection
$relay1->socketId(); // int(42)
$relay2->socketId(); // int(42)

While each constructor will instantiate a unique PHP object, under the hood Relay will use the same socket as long as these connection options are the same:

  • Host
  • Port
  • Database
  • Username (ACLs)

Distinct connections are firewalled, which includes event listeners.

$relay1 = new Relay(host: '127.0.0.1');
$relay2 = new Relay(host: '127.0.0.1', port: 7000);
$relay3 = new Relay(host: '127.0.0.1', db: 12);

// different connections
$relay1->socketId(); // int(42)
$relay2->socketId(); // int(47)
$relay3->socketId(); // int(314)

Switching databases will establish a new, distinct connection.

$relay = new Relay;
$relay->connect('127.0.0.1');

$relay->socketId(); // int(42)
$relay->select(2);
$relay->socketId(); // int(47)

Timeouts

The timeout option is currently being used for establishing a connection to Redis, as well as the timeout for Relay performing in-memory requests.

The read_timeout option is used when Relay is reading from Redis Server.

The retry_interval is currently not being used.

Authentication

Given that all of Relay’s connections are persistent, it has to store passwords in memory. To protect against side-channel attacks, all secrets are encrypted with the XTEA block cipher, and decoded only when needed for authentication/re-authentication.

To authenticate, use the auth() method:

$relay = new Relay;
$relay->connect('localhost', 6379);
$relay->auth('password');

// When using Redis 6 ACLs:
$relay->auth(['username', 'password']);

When using Relay’s modern syntax, use the context parameter:

$relay = new Relay(
    host: 'localhost',
    port: 6379,
    context: [
        'auth' => ['username', 'password']
    ],
);

Secure Connections

When using secure sockets, ensure that the socket timeout is set to at least one second. Setting the timeout too low can lead to numerous timeouts when the server load is high. Setting it too high can result in your application taking a long time to detect connection issues.

$relay = new Relay(
    host: 'tls://...cache.amazonaws.com',
    port: 19139,
    timeout: 2.5,
    context: [
        'stream' => [
            'verify_peer' => false,
            'verify_peer_name' => false,
        ]
    ],
);