Oihana PHP

CacheableTrait

Provides a standardized caching layer for classes using PSR-16 (Simple Cache).

This trait manages:

  • Instance-level caching: Easily enable/disable cache per object.
  • Dependency Injection: Can resolve cache instances from a PSR-11 Container.
  • Flexible TTL: Defines a default Time To Live (TTL) that can be overridden at call time.
  • Fluent Initialization: Provides methods to hydrate the cache configuration from arrays.
  • Expected configuration keys in $init arrays:
  • 'cache' (string|CacheInterface): The cache instance or its container ID.
  • 'cacheable' (bool): Toggle to enable/disable the cache functionality.
  • 'ttl' (int|DateInterval|null): The default expiration time.

Mix this trait into any model or service that needs an optional, swappable PSR-16 cache. When $cacheable is false (or no cache is set) the read/write helpers degrade gracefully: writes become no-ops returning false and reads return null, so callers never have to branch on whether caching is enabled.

Tags
author

Marc Alcaraz (ekameleon)

since
1.0.0

Table of Contents

Constants

CACHE  : string = 'cache'
The 'cache' parameter constant.
CACHEABLE  : string = 'cacheable'
The 'cacheable' parameter constant.
TTL  : string = 'ttl'
The 'ttl' parameter constant.

Properties

$cache  : CacheInterface|mixed|null
The PSR-16 cache reference.
$cacheable  : bool
Indicates if the instance use an internal PSR-16 cache.
$ttl  : null|int|DateInterval
Default TTL for cache items.

Methods

clearCache()  : void
Clears the whole cache.
deleteCache()  : void
Deletes a single entry from the cache.
getCache()  : mixed
Returns the value stored under the given cache key.
hasCache()  : bool
Indicates whether a given key is present in the cache.
initializeCache()  : static
Initializes the cache reference, then the `cacheable` and `ttl` properties.
initializeCacheable()  : static
Initializes the `$cacheable` flag from an initialization array.
initializeTtl()  : static
Initializes the default `$ttl` from an initialization array.
isCacheable()  : bool
Indicates whether the resource may actually use the cache.
setCache()  : bool
Persists data in the cache, uniquely referenced by a key with an optional expiration TTL time.
setCacheMultiple()  : bool
Persists a set of key => value pairs in the cache, with an optional TTL.

Constants

CACHE

The 'cache' parameter constant.

public string CACHE = 'cache'

CACHEABLE

The 'cacheable' parameter constant.

public string CACHEABLE = 'cacheable'

Properties

$cache

The PSR-16 cache reference.

public CacheInterface|mixed|null $cache = null

$cacheable

Indicates if the instance use an internal PSR-16 cache.

public bool $cacheable = true

$ttl

Default TTL for cache items.

public null|int|DateInterval $ttl = null

Methods

clearCache()

Clears the whole cache.

public clearCache() : void

No-op when no cache instance is attached.

deleteCache()

Deletes a single entry from the cache.

public deleteCache(string $key) : void

No-op when no cache instance is attached.

Parameters
$key : string

The cache key to remove.

Tags
throws
InvalidArgumentException

If the $key is not a legal cache key.

getCache()

Returns the value stored under the given cache key.

public getCache(string $key) : mixed
Parameters
$key : string

The cache key to read.

Tags
throws
InvalidArgumentException

If the $key is not a legal cache key.

example 
if ( !$this->hasCache( 'products' ) )
{
    $this->setCache( 'products' , $this->fetchProducts() , 3600 );
}

$products = $this->getCache( 'products' );
Return values
mixed —

The cached value, or null when the key is missing or no cache is attached.

hasCache()

Indicates whether a given key is present in the cache.

public hasCache(string|null $key) : bool
Parameters
$key : string|null

The cache key to test; null always returns false.

Tags
throws
InvalidArgumentException

If the $key is a non-null but illegal cache key.

Return values
bool —

true if the key exists in the attached cache, false otherwise (or when no cache is attached).

initializeCache()

Initializes the cache reference, then the `cacheable` and `ttl` properties.

public initializeCache([array<string|int, mixed> $init = [] ][, Container|null $container = null ]) : static

The cache is read from the self::CACHE key of $init (falling back to the current $cache). When that value is a string and a container is provided, it is resolved as a container service id. Any value that is not a CacheInterface results in a null cache.

Parameters
$init : array<string|int, mixed> = []

Initialization options (keys: cache, cacheable, ttl).

$container : Container|null = null

Optional DI container used to resolve a string cache id.

Tags
throws
DependencyException

If the dependency cannot be resolved by the container.

NotFoundException

If no entry is found for the given identifier in the container.

Return values
static —

The current instance, for fluent chaining.

initializeCacheable()

Initializes the `$cacheable` flag from an initialization array.

public initializeCacheable([array<string|int, mixed> $init = [] ]) : static

Read from the self::CACHEABLE key when present; otherwise the current value is kept.

Parameters
$init : array<string|int, mixed> = []

Initialization options.

Return values
static —

The current instance, for fluent chaining.

initializeTtl()

Initializes the default `$ttl` from an initialization array.

public initializeTtl([array<string|int, mixed> $init = [] ]) : static

Read from the self::TTL key when present; otherwise the current value is kept.

Parameters
$init : array<string|int, mixed> = []

Initialization options.

Return values
static —

The current instance, for fluent chaining.

isCacheable()

Indicates whether the resource may actually use the cache.

public isCacheable([array<string|int, mixed> $init = [] ]) : bool

Returns true only when a cache instance is attached and caching is enabled — either by the runtime self::CACHEABLE flag in $init or, as a fallback, by the $cacheable property.

Parameters
$init : array<string|int, mixed> = []

Optional runtime options; a cacheable boolean key overrides the property.

Return values
bool —

true if the cache can be used, false otherwise.

setCache()

Persists data in the cache, uniquely referenced by a key with an optional expiration TTL time.

public setCache(string $key, mixed $value[, null|int|DateInterval $ttl = null ]) : bool
Parameters
$key : string

The key of the item to store.

$value : mixed

The value of the item to store, must be serializable.

$ttl : null|int|DateInterval = null

Optional TTL (Time to Live)value of this item. If no value is sent and the driver supports TTL then the library may set a default value for it or let the driver take care of that.

Tags
throws
InvalidArgumentException

MUST be thrown if the $key string is not a legal value.

example 
// Cache for one hour
$this->setCache( 'user:42' , $user , 3600 );

// Cache using the default TTL of the instance
$this->setCache( 'config' , $config );
Return values
bool —

True on success and false on failure (including when caching is disabled or no cache is attached).

setCacheMultiple()

Persists a set of key => value pairs in the cache, with an optional TTL.

public setCacheMultiple(array<string|int, mixed> $values[, null|int|DateInterval $ttl = null ]) : bool
Parameters
$values : array<string|int, mixed>

A list of key => value pairs for a multiple-set operation.

$ttl : null|int|DateInterval = null

Optional TTL (Time to Live) value of this item. If no value is sent and the driver supports TTL then the library may set a default value for it or let the driver take care of that.

Tags
throws
InvalidArgumentException

If any of the $values keys is not a legal cache key.

Return values
bool —

True on success and false on failure (including when caching is disabled or no cache is attached).

On this page

Search results