CoolCMS API

Config
in package

Configuration of the cache subsystem (wire-payload query cache with tag versions).

TTL strategy:

  • queryTtl caps staleness of a query payload; tag-bump invalidation handles the rest. Tags (tag:*) have no TTL because they are counters.
  • serviceTtl overrides queryTtl per service (FQCN to seconds) for services whose writes bump tags completely and whose result does not depend on time. A jitter of +-10 % is added to every TTL on write (TtlJitter).

Payload compression: lossless deflate above compressionThreshold bytes, level compressionLevel (1-9, higher = better ratio, slower).

Rollout: enabled is the global master toggle; enabledServices is a per-service allowlist (FQCN of service classes), so the cache can be on for one service only.

Table of Contents

Properties

$compressData  : bool
Enables lossless compression of cache values (deflate).
$compressionLevel  : int
Deflate compression level (1-9); higher = better ratio, slower.
$compressionThreshold  : int
Minimum size in bytes from which values are compressed.
$debug  : bool
Enables debug logging.
$enabled  : bool
Global master toggle of the cache subsystem.
$enabledServices  : array<string|int, string>
$keyPrefix  : string
Prefix of all cache keys (Redis instance shared by several apps).
$lockMs  : int
Single-flight lock against a thundering herd on hot lists, in milliseconds.
$logFile  : string
Path to the debug log file.
$queryTtl  : int
Query payload TTL in seconds (default 5 minutes).
$routerEnabled  : bool
Router route-table cache, independent of the master `$enabled` (which controls only the wire-payload query cache). Enable it separately in `local.neon` (`cache.config.routerEnabled: true`). Off by default.
$routerTtl  : int
Route table TTL in seconds; caps staleness caused by raw-SQL writes without a bump.
$serviceTtl  : array<string|int, mixed>
Per-service query cache payload TTL (FQCN of service class to seconds).
$settingsProbeEnabled  : bool
Settings read probe ({@see \App\Core\Cache\Probe\SettingReadProbe}) records which `cms_system_settings` keys are read through `SettingContext` at runtime.
$settingsProbeTtl  : int
TTL of the probe's Redis hashes in seconds, refreshed on every write. The data disappears on its own after the probe is switched off. `0` means no TTL.
$statsEnabled  : bool
Enables hit/miss/set/bump counters (Redis hash `{prefix}cache:stats:*`).
$writeOnly  : bool
Write-only mode: stores to the cache but never reads (for tests).

Methods

__construct()  : mixed
getCompressionInfo()  : array{enabled: bool, threshold: string, level: string}
Returns a summary of the compression settings (for debugging).
isRouterEnabled()  : bool
Returns whether the router route-table cache is on.
isServiceEnabled()  : bool
Returns whether the cache is active for the service class (master toggle plus allowlist).
queryTtlFor()  : int
Returns the base payload TTL of the service in seconds, without jitter.
setLogFile()  : void
Sets the path to the log file.
assertServiceTtl()  : void
Validates the per-service TTL map.

Properties

$compressData

Enables lossless compression of cache values (deflate).

public bool $compressData = true

Compressed values are detected by a magic-bytes prefix, so uncompressed values stay readable.

$compressionLevel

Deflate compression level (1-9); higher = better ratio, slower.

public int $compressionLevel = 6

$compressionThreshold

Minimum size in bytes from which values are compressed.

public int $compressionThreshold = 256

Smaller values cost more to compress than they save.

$debug

Enables debug logging.

public bool $debug = true

$enabled

Global master toggle of the cache subsystem.

public bool $enabled = true

$enabledServices

public array<string|int, string> $enabledServices = []

$keyPrefix

Prefix of all cache keys (Redis instance shared by several apps).

public string $keyPrefix = 'app:'

$lockMs

Single-flight lock against a thundering herd on hot lists, in milliseconds.

public int $lockMs = 3000

After a miss, before the database read, the request tries SET {prefix}cache:lock:{queryKey} 1 NX PX lockMs. The holder reads the database and stores the payload; others poll the cache briefly and, when no payload appears, read the database without writing so the stampede is not doubled. The value is the upper bound of how long a lock survives a crashed holder. 0 disables single-flight (behaves as without a lock).

$logFile

Path to the debug log file.

public string $logFile = ''

$queryTtl

Query payload TTL in seconds (default 5 minutes).

public int $queryTtl = 300

Upper bound of staleness when a bump was forgotten or Redis was down during the bump. Use 60 for near real time, 600 for high traffic, 3600 for static data.

$routerEnabled

Router route-table cache, independent of the master `$enabled` (which controls only the wire-payload query cache). Enable it separately in `local.neon` (`cache.config.routerEnabled: true`). Off by default.

public bool $routerEnabled = false

$routerTtl

Route table TTL in seconds; caps staleness caused by raw-SQL writes without a bump.

public int $routerTtl = 300

A jitter of +-10 % is added. The table changes rarely, so the value can be raised.

$serviceTtl

Per-service query cache payload TTL (FQCN of service class to seconds).

public array<string|int, mixed> $serviceTtl = []

Empty means all services use $queryTtl. A longer TTL belongs only to a service whose writes bump tags completely (no raw-SQL write without a bump, no deliberately non-bumping counter that is displayed) and whose result does not depend on time (a "valid until" or "topped until" filter computed in SQL). For it the TTL is only a cap for a Redis outage during the bump. An unknown FQCN is silently ignored.

$settingsProbeEnabled

Settings read probe ({@see \App\Core\Cache\Probe\SettingReadProbe}) records which `cms_system_settings` keys are read through `SettingContext` at runtime.

public bool $settingsProbeEnabled = false

Independent of the master $enabled. Off by default; enable in config/Shared/local.neon (cache.config.settingsProbeEnabled: true) and switch off again after collecting data.

$settingsProbeTtl

TTL of the probe's Redis hashes in seconds, refreshed on every write. The data disappears on its own after the probe is switched off. `0` means no TTL.

public int $settingsProbeTtl = 7776000

$statsEnabled

Enables hit/miss/set/bump counters (Redis hash `{prefix}cache:stats:*`).

public bool $statsEnabled = true

The increments are pipelined on the hot path (one round trip). When off, the counters are no-ops and issue no extra Redis command.

$writeOnly

Write-only mode: stores to the cache but never reads (for tests).

public bool $writeOnly = false

Methods

__construct()

public __construct([bool $enabled = true ][, bool $debug = true ][, bool $writeOnly = false ][, int $queryTtl = 300 ][, string $keyPrefix = 'app:' ][, string $logFile = '' ][, bool $compressData = true ][, int $compressionThreshold = 256 ][, int $compressionLevel = 6 ][, array<string|int, string> $enabledServices = [] ][, bool $statsEnabled = true ][, int $lockMs = 3000 ][, bool $routerEnabled = false ][, int $routerTtl = 300 ][, bool $settingsProbeEnabled = false ][, int $settingsProbeTtl = 7776000 ][, array<string, int> $serviceTtl = [] ]) : mixed
Parameters
$enabled : bool = true
$debug : bool = true
$writeOnly : bool = false
$queryTtl : int = 300
$keyPrefix : string = 'app:'
$logFile : string = ''
$compressData : bool = true
$compressionThreshold : int = 256
$compressionLevel : int = 6
$enabledServices : array<string|int, string> = []

per-service rollout allowlist (FQCN of service classes); empty means no service is cached even when enabled

$statsEnabled : bool = true
$lockMs : int = 3000
$routerEnabled : bool = false
$routerTtl : int = 300
$settingsProbeEnabled : bool = false
$settingsProbeTtl : int = 7776000
$serviceTtl : array<string, int> = []

per-service payload TTL (FQCN of service class to seconds); a service outside the map uses queryTtl

getCompressionInfo()

Returns a summary of the compression settings (for debugging).

public getCompressionInfo() : array{enabled: bool, threshold: string, level: string}
Return values
array{enabled: bool, threshold: string, level: string}

isRouterEnabled()

Returns whether the router route-table cache is on.

public isRouterEnabled() : bool

Independent of the master $enabled (see $routerEnabled).

Return values
bool

isServiceEnabled()

Returns whether the cache is active for the service class (master toggle plus allowlist).

public isServiceEnabled(string $serviceClass) : bool

The wildcard '*' in enabledServices means all services; the master enabled still applies. Use it only once raw-DBAL writes bump tags for every service, otherwise stale payloads are served; until then list services by name.

Parameters
$serviceClass : string
Return values
bool

queryTtlFor()

Returns the base payload TTL of the service in seconds, without jitter.

public queryTtlFor(string $serviceClass) : int

Takes the $serviceTtl override, otherwise $queryTtl. The jitter is added on write (TtlJitter).

Parameters
$serviceClass : string
Return values
int

setLogFile()

Sets the path to the log file.

public setLogFile(string $filePath) : void
Parameters
$filePath : string

assertServiceTtl()

Validates the per-service TTL map.

private static assertServiceTtl(array<string|int, mixed> $serviceTtl) : void

A typo in neon (list instead of map, string, 0, negative) fails immediately instead of silently producing keys with a different TTL. The parameter is array<mixed> on purpose because neon does not guarantee the PHPDoc type.

Parameters
$serviceTtl : array<string|int, mixed>
On this page

Search results