WooCommerce Code Reference

ObjectCache
in package

Base class for caching objects (or associative arrays) that have a unique identifier.

At the very least, derived classes need to implement the 'get_object_type' method, but usually it will be convenient to override some of the other protected members.

The actual caching is delegated to an instance of CacheEngine. By default WpCacheEngine is used, but a different engine can be used by either overriding the get_cache_engine_instance method or capturing the wc_object_cache_get_engine filter.

Objects are identified by ids that are either integers or strings. The actual cache keys passed to the cache engine will be prefixed with the object type and a random string. The 'flush' operation just forces the generation a new prefix and lets the old cached objects expire.

Table of Contents

DEFAULT_EXPIRATION  = -1
Expiration value to be passed to 'set' to use the value of $default_expiration.
MAX_EXPIRATION  = MONTH_IN_SECONDS
Maximum expiration time value, in seconds, that can be passed to 'set'.
$default_expiration  : int
Default value for the duration of the objects in the cache, in seconds (may not be used depending on the cache engine used WordPress cache implementation).
$cache_engine  : CacheEngine|null
The cache engine to use.
$last_cached_data  : array<string|int, mixed>
Temporarily used when retrieving data in 'get'.
$object_type  : string
This needs to be set in each derived class.
__construct()  : mixed
Creates a new instance of the class.
flush()  : bool
Remove all the objects from the cache.
get()  : object|array<string|int, mixed>|null
Retrieve a cached object, and if no object is cached with the given id, try to get one via get_from_datastore method or by supplying a callback and then cache it.
get_default_expiration_value()  : int
Get the default expiration time for cached objects, in seconds.
get_object_type()  : string
Gets an identifier for the types of objects cached by this class.
is_cached()  : bool
Is a given object cached?
remove()  : bool
Remove an object from the cache.
set()  : bool
Add an object to the cache, or update an already cached object.
update_if_cached()  : bool
Update an object in the cache, but only if an object is already cached with the same id.
get_cache_engine_instance()  : CacheEngine
Get the instance of the cache engine to use.
get_object_id()  : int|string|null
Get the id of an object. This is used by 'set' when a null id is passed.
get_random_string()  : string
Get a random string to be used to compose the cache key prefix.
validate()  : array<string|int, mixed>|null
Validate an object before it's cached.
get_cache_engine()  : CacheEngine
Get the cache engine to use and cache it internally.
get_id_from_object_if_null()  : int|string|null
Get the id from an object if the id itself is null.
verify_expiration_value()  : void
Check if the given expiration time value is valid, throw an exception if not.

Constants

DEFAULT_EXPIRATION

Expiration value to be passed to 'set' to use the value of $default_expiration.

public mixed DEFAULT_EXPIRATION = -1

MAX_EXPIRATION

Maximum expiration time value, in seconds, that can be passed to 'set'.

public mixed MAX_EXPIRATION = MONTH_IN_SECONDS

Properties

$default_expiration

Default value for the duration of the objects in the cache, in seconds (may not be used depending on the cache engine used WordPress cache implementation).

protected int $default_expiration = HOUR_IN_SECONDS

$last_cached_data

Temporarily used when retrieving data in 'get'.

private array<string|int, mixed> $last_cached_data

Methods

__construct()

Creates a new instance of the class.

public __construct() : mixed
Tags
throws
CacheException

If get_object_type returns null or an empty string.

Return values
mixed —

flush()

Remove all the objects from the cache.

public flush() : bool
Return values
bool — True on success, false on error.

get()

Retrieve a cached object, and if no object is cached with the given id, try to get one via get_from_datastore method or by supplying a callback and then cache it.

public get(int|string $id[, int $expiration = self::DEFAULT_EXPIRATION ][, callable|null $get_from_datastore_callback = null ]) : object|array<string|int, mixed>|null

If you want to provide a callable but still use the default expiration value, pass "ObjectCache::DEFAULT_EXPIRATION" as the second parameter.

Parameters
$id : int|string

The id of the object to retrieve.

$expiration : int = self::DEFAULT_EXPIRATION

Expiration of the cached data in seconds from the current time, used if an object is retrieved from datastore and cached.

$get_from_datastore_callback : callable|null = null

Optional callback to get the object if it's not cached, it must return an object/array or null.

Tags
throws
CacheException

Invalid id parameter.

Return values
object|array<string|int, mixed>|null — Cached object, or null if it's not cached and can't be retrieved from datastore or via callback.

get_default_expiration_value()

Get the default expiration time for cached objects, in seconds.

public get_default_expiration_value() : int
Return values
int —

get_object_type()

Gets an identifier for the types of objects cached by this class.

public abstract get_object_type() : string

This identifier will be used to compose the keys passed to the cache engine, to the name of the option that stores the cache prefix, and the names of the hooks used. It must be unique for each class inheriting from ObjectCache.

Return values
string —

is_cached()

Is a given object cached?

public is_cached(int|string $id) : bool
Parameters
$id : int|string

The id of the object to check.

Return values
bool — True if there's a cached object with the specified id.

remove()

Remove an object from the cache.

public remove(int|string $id) : bool
Parameters
$id : int|string

The id of the object to remove.

Return values
bool — True if the object is removed from the cache successfully, false otherwise (because the object wasn't cached or for other reason).

set()

Add an object to the cache, or update an already cached object.

public set(object|array<string|int, mixed> $object[, int|string|null $id = null ][, int $expiration = self::DEFAULT_EXPIRATION ]) : bool
Parameters
$object : object|array<string|int, mixed>

The object to be cached.

$id : int|string|null = null

Id of the object to be cached, if null, get_object_id will be used to get it.

$expiration : int = self::DEFAULT_EXPIRATION

Expiration of the cached data in seconds from the current time, or DEFAULT_EXPIRATION to use the default value.

Tags
throws
CacheException

Invalid parameter, or null id was passed and get_object_id returns null too.

Return values
bool — True on success, false on error.

update_if_cached()

Update an object in the cache, but only if an object is already cached with the same id.

public update_if_cached(object|array<string|int, mixed> $object[, int|string|null $id = null ][, int $expiration = self::DEFAULT_EXPIRATION ]) : bool
Parameters
$object : object|array<string|int, mixed>

The new object that will replace the already cached one.

$id : int|string|null = null

Id of the object to be cached, if null, get_object_id will be used to get it.

$expiration : int = self::DEFAULT_EXPIRATION

Expiration of the cached data in seconds from the current time, or DEFAULT_EXPIRATION to use the default value.

Tags
throws
CacheException

Invalid parameter, or null id was passed and get_object_id returns null too.

Return values
bool — True on success, false on error or if no object wiith the supplied id was cached.

get_object_id()

Get the id of an object. This is used by 'set' when a null id is passed.

protected abstract get_object_id(array<string|int, mixed>|object $object) : int|string|null

If the object id can't be determined the method must return null.

Parameters
$object : array<string|int, mixed>|object

The object to get the id for.

Return values
int|string|null —

get_random_string()

Get a random string to be used to compose the cache key prefix.

protected get_random_string() : string

It should return a different string each time.

Return values
string —

validate()

Validate an object before it's cached.

protected abstract validate(array<string|int, mixed>|object $object) : array<string|int, mixed>|null
Parameters
$object : array<string|int, mixed>|object

Object to validate.

Return values
array<string|int, mixed>|null — An array with validation error messages, null or an empty array if there are no errors.

get_id_from_object_if_null()

Get the id from an object if the id itself is null.

private get_id_from_object_if_null(object|array<string|int, mixed> $object, int|string|null $id) : int|string|null
Parameters
$object : object|array<string|int, mixed>

The object to get the id from.

$id : int|string|null

An object id or null.

Tags
throws
CacheException

Passed $id is null and get_object_id returned null too.

Return values
int|string|null — Passed $id if it wasn't null, otherwise id obtained from $object using get_object_id.

verify_expiration_value()

Check if the given expiration time value is valid, throw an exception if not.

private verify_expiration_value(int $expiration) : void
Parameters
$expiration : int

Expiration time to check.

Tags
throws
CacheException

Expiration time is negative or higher than MAX_EXPIRATION.

Return values
void —