Cache

Berlioz Framework ships with a PSR-16 (Simple Cache) cache used internally by the kernel (compiled configuration, service container, routes…) and available to your application.

The cache is held by the Core object and managed by Berlioz\Core\Cache\CacheManager. It is provided to the kernel at bootstrap time, through the second argument of the Core constructor.

use Berlioz\Core\Core;
use Berlioz\Http\Core\App\HttpApp;

$app = new HttpApp(new Core(cache: $cache));

The cache is an infrastructure service of the framework. It is configured by code at bootstrap, not through the configuration files, because the cache is needed before the configuration is loaded.

Drivers

All drivers implement Psr\SimpleCache\CacheInterface.

By default, when you pass true (or nothing) to the Core constructor, the FileCacheDriver is used. Passing false uses the MemoryCacheDriver. Passing a CacheInterface instance uses it as-is.

File driver

use Berlioz\Core\Cache\FileCacheDriver;

// From a directory path
$cache = new FileCacheDriver('/var/cache');

// From the framework directories (historical usage, still supported)
$cache = new FileCacheDriver($core->getDirectories());

Redis driver

The RedisCacheDriver is well-suited for multi-server deployments and containerized / ephemeral environments, where a shared and persistent cache is required across nodes. It takes an already-connected Redis instance and an optional key namespace (used to prefix every key and to scope clear()).

use Redis;
use Berlioz\Core\Cache\RedisCacheDriver;

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

$cache = new RedisCacheDriver(
    redis: $redis,            // Connected Redis instance
    namespace: 'my-project',  // Key prefix (default: "berlioz")
);

Key characteristics:

• Namespaced keys: every key is prefixed with the namespace, so several applications can share the same Redis instance without collisions.
• Native TTL: expirations are handled by Redis itself (millisecond precision via PSETEX).
• Scoped clear(): only the keys of the configured namespace are removed (via SCAN + DEL); the rest of the Redis instance is never flushed.

Fallback driver

The FallbackCacheDriver chains several drivers, ordered from the most preferred to the fallback one. If an operation fails on a driver (for example, Redis becomes unreachable), it is retried on the next driver. A cache miss is not a failure and does not trigger any fallback. Once a driver fails, it is short-circuited for the lifetime of the instance.

use Berlioz\Core\Cache\FallbackCacheDriver;
use Berlioz\Core\Cache\FileCacheDriver;
use Berlioz\Core\Cache\MemoryCacheDriver;
use Berlioz\Core\Cache\RedisCacheDriver;

$cache = new FallbackCacheDriver([
    new RedisCacheDriver($redis, 'my-project'),
    new FileCacheDriver('/var/cache'),
    new MemoryCacheDriver(),
]);

With this configuration, the application keeps working even if Redis goes down: it transparently falls back to the file cache, then to the in-memory cache.

Cache driver factory

Berlioz\Core\Cache\CacheDriverFactory provides convenient ways to build a cache driver.

From an array

use Berlioz\Core\Cache\CacheDriverFactory;

$cache = CacheDriverFactory::create([
    'driver' => 'redis',       // redis | file | memory | null
    'host' => '127.0.0.1',     // redis only
    'port' => 6379,            // redis only
    'auth' => 'secret',        // redis only, optional
    'database' => 0,           // redis only, optional
    'timeout' => 0.0,          // redis only, optional
    'namespace' => 'my-project', // redis only, optional
]);

// File driver
$cache = CacheDriverFactory::create(['driver' => 'file', 'path' => '/var/cache']);

From environment variables

fromEnv() reads the following variables (prefix BERLIOZ_CACHE_ by default):

use Berlioz\Core\Cache\CacheDriverFactory;

$cache = CacheDriverFactory::fromEnv();

From a JSON file

The file must contain a JSON object matching the options of create().

{
  "driver": "redis",
  "host": "127.0.0.1",
  "port": 6379,
  "namespace": "my-project"
}

use Berlioz\Core\Cache\CacheDriverFactory;

$cache = CacheDriverFactory::fromFile('/path/to/cache.json');

Automatic detection

auto() builds a sensible driver from the environment (defaulting to the file cache, or to memory when no path is available) and wraps any persistent driver in a FallbackCacheDriver with a MemoryCacheDriver fallback, so the cache keeps working if the main driver becomes unavailable.

use Berlioz\Core\Cache\CacheDriverFactory;
use Berlioz\Core\Core;

$app = new HttpApp(new Core(cache: CacheDriverFactory::auto()));

Using the cache in your application

The cache is accessible from the Core object:

/** @var \Psr\SimpleCache\CacheInterface $cache */
$cache = $this->getApp()->getCore()->getCache();

$cache->set('my-key', $value, 3600);
$value = $cache->get('my-key', 'default');

Requirements

To use the RedisCacheDriver, the phpredis extension (ext-redis) must be installed:

pecl install redis