1. trait
  2. Hypervel
  3. \
  4. Foundation
  5. \
  6. Testing
  7. \
  8. Concerns
  9. \
  10. InteractsWithRedis

InteractsWithRedis

trait InteractsWithRedis

Provides Redis integration testing support.

Auto-called by TestCase via setUpTraits():

  • setUpInteractsWithRedis() runs after app boots
  • tearDownInteractsWithRedis() runs via beforeApplicationDestroyed()

Tests that need Redis config overrides (prefix, DB number) should set them in defineEnvironment() via $app->make('config')->set(...).

Parallel Testing (ParaTest): Each ParaTest worker gets its own Redis DB number to prevent cross-process interference. Sequential runs use REDIS_DB directly. Parallel runs allocate worker databases from REDIS_TEST_DB_MIN through REDIS_TEST_DB_MAX.

Tests that need to call select() to switch databases should set REDIS_TEST_SECONDARY_DB and use getSecondaryRedisDb(). The secondary DB is shared by tests that explicitly request it; never call flushdb() on it. Use unique keys and clean them up with del().

Environment Variables:

  • REDIS_HOST: Redis host; must be set to enable Redis integration tests
  • REDIS_PORT: Redis port (default: 6379)
  • REDIS_DB: Base Redis database number (default: 0)
  • REDIS_TEST_DB_MIN: First Redis database available for parallel workers (default: REDIS_DB)
  • REDIS_TEST_DB_MAX: Last Redis database available for parallel workers (default: 15)
  • REDIS_TEST_SECONDARY_DB: Shared secondary database for select() tests (optional)
  • REDIS_PASSWORD: Redis password (optional)

Methods

void
setUpInteractsWithRedis()

Set up Redis for testing (auto-called by setUpTraits).

void
tearDownInteractsWithRedis()

Tear down Redis (auto-called via beforeApplicationDestroyed).

void
flushRedis()

Flush the Redis database.

bool
hasExplicitRedisConfig()

Check if REDIS_HOST was explicitly set in environment.

int
getBaseRedisDb()

Get the base Redis DB number from environment.

int
getRedisTestDbMin()

Get the first Redis DB number available for parallel test workers.

int
getRedisTestDbMax()

Get the last Redis DB number available for parallel test workers.

int|null
getConfiguredSecondaryRedisDb()

Get the configured secondary Redis DB number.

int
getParallelRedisDb()

Get the primary Redis DB number for the current test worker.

int
redisDatabaseForParallelToken(string $token)

Get the primary Redis DB number for a parallel testing token.

int
getSecondaryRedisDb()

Get the secondary Redis DB for tests that need to call select().

string|false
parallelTestingToken()

Get the current parallel testing token.

array
redisWorkerDatabases()

Get the configured Redis worker databases.

int
redisWorkerIndex(string $token)

Get the zero-based Redis worker index for a ParaTest token.

int
integerRedisEnvironment(string $key, int $default)

Get a non-negative integer Redis environment value.

int
integerRedisEnvironmentValue(string $key, mixed $value)

Parse a non-negative integer Redis environment value.

Redis
redisClient(string $connectionName = 'default')

Get a raw phpredis client for direct Redis operations.

Redis
rawRedisClientWithoutPrefix(string $connectionName = 'default')

Get a raw phpredis client WITHOUT any OPT_PREFIX.

void
cleanupKeysWithPattern(string $pattern)

Clean up keys matching a pattern using raw client (no prefix).

void
cleanupRedisKeysWithPatterns(string ...$patterns)

Clean up keys matching multiple patterns using the trait's standard Redis test semantics.

string
createRedisConnectionWithPrefix(string $optPrefix)

Create a named Redis connection with a specific OPT_PREFIX for testing.

string
createRedisConnectionWithOptions(string $name, array $options, int $maxConnections = 10)

Create a Redis connection with custom options for integration assertions.

Details

at line 55
protected void setUpInteractsWithRedis()

Set up Redis for testing (auto-called by setUpTraits).

Redis integration tests are opt-in via REDIS_HOST. Port, password, and database settings are only read after REDIS_HOST is present.

When running under ParaTest, assigns a configured per-worker Redis DB number to prevent cross-process interference.

Return Value

void

at line 72
protected void tearDownInteractsWithRedis()

Tear down Redis (auto-called via beforeApplicationDestroyed).

Return Value

void

at line 93
protected void flushRedis()

Flush the Redis database.

Return Value

void

at line 101
protected bool hasExplicitRedisConfig()

Check if REDIS_HOST was explicitly set in environment.

Return Value

bool

at line 115
protected int getBaseRedisDb()

Get the base Redis DB number from environment.

Reads from env directly (not config) because configureParallelRedisDb() mutates the config value — reading config here would cause the DB number to drift upward across tests in the same worker.

Default matches database.php: env('REDIS_DB', 0).

Return Value

int

at line 123
protected int getRedisTestDbMin()

Get the first Redis DB number available for parallel test workers.

Return Value

int

at line 131
protected int getRedisTestDbMax()

Get the last Redis DB number available for parallel test workers.

Return Value

int

at line 139
protected int|null getConfiguredSecondaryRedisDb()

Get the configured secondary Redis DB number.

Return Value

int|null

at line 147
protected int getParallelRedisDb()

Get the primary Redis DB number for the current test worker.

Return Value

int

at line 155
protected int redisDatabaseForParallelToken(string $token)

Get the primary Redis DB number for a parallel testing token.

Parameters

string $token

Return Value

int

at line 168
protected int getSecondaryRedisDb()

Get the secondary Redis DB for tests that need to call select().

Must always return a DB number different from getParallelRedisDb().

This DB is shared across all parallel workers. Never call flushdb() on it — use unique keys and clean up via del() instead.

Return Value

int

at line 194
protected string|false parallelTestingToken()

Get the current parallel testing token.

Return Value

string|false

at line 206
protected array redisWorkerDatabases()

Get the configured Redis worker databases.

Return Value

array

at line 214
protected int redisWorkerIndex(string $token)

Get the zero-based Redis worker index for a ParaTest token.

Parameters

string $token

Return Value

int

at line 222
protected int integerRedisEnvironment(string $key, int $default)

Get a non-negative integer Redis environment value.

Parameters

string $key
int $default

Return Value

int

at line 230
protected int integerRedisEnvironmentValue(string $key, mixed $value)

Parse a non-negative integer Redis environment value.

Parameters

string $key
mixed $value

Return Value

int

at line 241
protected Redis redisClient(string $connectionName = 'default')

Get a raw phpredis client for direct Redis operations.

This client has OPT_PREFIX set to the test prefix, so keys are automatically prefixed when using this client.

Parameters

string $connectionName

Return Value

Redis

at line 260
protected Redis rawRedisClientWithoutPrefix(string $connectionName = 'default')

Get a raw phpredis client WITHOUT any OPT_PREFIX.

Useful for verifying actual key names in Redis. Uses the per-worker DB number for parallel safety.

Parameters

string $connectionName

Return Value

Redis

at line 288
protected void cleanupKeysWithPattern(string $pattern)

Clean up keys matching a pattern using raw client (no prefix).

Parameters

string $pattern

Return Value

void

at line 305
protected void cleanupRedisKeysWithPatterns(string ...$patterns)

Clean up keys matching multiple patterns using the trait's standard Redis test semantics.

If Redis was not explicitly enabled, cleanup is skipped just like setUpInteractsWithRedis(). If REDIS_HOST is set, connection failures still propagate as real test environment errors.

Parameters

string ...$patterns

Return Value

void

at line 332
protected string createRedisConnectionWithPrefix(string $optPrefix)

Create a named Redis connection with a specific OPT_PREFIX for testing.

Use this when a test needs multiple connections with different prefixes. For a single no-prefix connection, just set the prefix on the default connection in defineEnvironment() instead.

Parameters

string $optPrefix

Return Value

string

at line 346
protected string createRedisConnectionWithOptions(string $name, array $options, int $maxConnections = 10)

Create a Redis connection with custom options for integration assertions.

Parameters

string $name
array $options
int $maxConnections

Return Value

string