Moodle PHP Documentation 4.3
Moodle 4.3.5 (Build: 20240610) (7dcfaa79f78)
|
Abstract cache store class. More...
Public Member Functions | |
__construct ($name, array $configuration=array()) | |
Constructs an instance of the cache store. | |
cache_size_details (int $samplekeys=50) | |
Gets the amount of memory used by this specific cache within the store, if known. | |
cleanup () | |
create_clone (array $details=array()) | |
Creates a clone of this store instance ready to be initialised. | |
delete ($key) | |
Deletes an item from the cache store. | |
delete_many (array $keys) | |
Deletes several keys from the cache in a single action. | |
estimate_stored_size ($key, $value) | |
Estimates the storage size used within this cache if the given value is stored with the given key. | |
get ($key) | |
Retrieves an item from the cache store given its key. | |
get_last_io_bytes () | |
Gets the number of bytes read from or written to cache as a result of the last action. | |
get_many ($keys) | |
Retrieves several items from the cache store in a single transaction. | |
get_warnings () | |
Can be overridden to return any warnings this store instance should make to the admin. | |
initialise (cache_definition $definition) | |
Initialises a new instance of the cache store given the definition the instance is to be used for. | |
instance_created () | |
Performs any necessary operation when the store instance has been created. | |
instance_deleted () | |
Performs any necessary operation when the store instance is being deleted. | |
is_initialised () | |
Returns true if this cache store instance has been initialised. | |
is_ready () | |
Returns true if this cache store instance is ready to use. | |
is_searchable () | |
Returns true if the store instance is searchable. | |
my_name () | |
Returns the name of this store instance. | |
purge () | |
Purges the cache deleting all items within it. | |
set ($key, $data) | |
Sets an item in the cache given its key and data value. | |
set_many (array $keyvaluearray) | |
Sets many items in the cache in a single transaction. | |
store_total_size () | |
Gets the amount of memory/storage currently used by this cache store if known. | |
supports_data_guarantee () | |
Returns true if the store instance guarantees data. | |
supports_dereferencing_objects () | |
Returns true if the store automatically dereferences objects. | |
supports_multiple_identifiers () | |
Returns true if the store instance supports multiple identifiers. | |
supports_native_ttl () | |
Returns true if the store instance supports native ttl. | |
Static Public Member Functions | |
static | are_requirements_met () |
Static method to check if the store requirements are met. | |
static | can_add_instance () |
Returns true if the user can add an instance of the store plugin. | |
static | get_supported_features (array $configuration=array()) |
Returns the supported features as a binary flag. | |
static | get_supported_modes (array $configuration=array()) |
Returns the supported modes as a binary flag. | |
static | initialise_test_instance (cache_definition $definition) |
Generates an instance of the cache store that can be used for testing. | |
static | is_supported_mode ($mode) |
Static method to check if a store is usable with the given mode. | |
static | ready_to_be_used_for_testing () |
Returns true if this cache store instance is both suitable for testing, and ready for testing. | |
static | unit_test_configuration () |
Generates the appropriate configuration required for unit testing. | |
Public Attributes | |
const | DEREFERENCES_OBJECTS = 16 |
The cache store dereferences objects. | |
const | IO_BYTES_NOT_SUPPORTED = -1 |
Returned from get_last_io_bytes if this cache store doesn't support counting bytes read/sent. | |
const | IS_SEARCHABLE = 8 |
The cache is searchable by key. | |
const | MODE_APPLICATION = 1 |
Application caches. | |
const | MODE_REQUEST = 4 |
Request caches. | |
const | MODE_SESSION = 2 |
Session caches. | |
const | STATIC_ACCEL = '** static accel. **' |
Static caches. | |
const | SUPPORTS_DATA_GUARANTEE = 2 |
Ensures data remains in the cache once set. | |
const | SUPPORTS_MULTIPLE_IDENTIFIERS = 1 |
Supports multi-part keys. | |
const | SUPPORTS_NATIVE_TTL = 4 |
Supports a native ttl system. | |
Abstract cache store class.
All cache store plugins must extend this base class. It lays down the foundation for what is required of a cache store plugin.
|
abstract |
Constructs an instance of the cache store.
The constructor should be responsible for creating anything needed by the store that is not specific to a definition. Tasks such as opening a connection to check it is available are best done here. Tasks that are definition specific such as creating a storage area for the definition data or creating key tables and indexs are best done within the initialise method.
Once a store has been constructed the cache API will check it is ready to be intialised with a definition by called $this->is_ready(). If the setup of the store failed (connection could not be established for example) then that method should return false so that the store instance is not selected for use.
string | $name | The name of the cache store |
array | $configuration | The configuration for this store instance. |
Reimplemented in cachestore_apcu, cachestore_dummy, cachestore_file, cachestore_redis, cachestore_session, and cachestore_static.
|
staticinherited |
Static method to check if the store requirements are met.
bool | True if the stores software/hardware requirements have been met and it can be used. False otherwise. |
Implemented in cachestore_apcu, cachestore_dummy, cachestore_file, cachestore_redis, cachestore_session, and cachestore_static.
cache_store::cache_size_details | ( | int | $samplekeys = 50 | ) |
Gets the amount of memory used by this specific cache within the store, if known.
This function may be slow and should not be called in normal usage, only for administration pages. The value is usually an estimate, and may not be available at all.
When estimating, a number of sample items will be used for the estimate. If set to 50 (default), then this function will retrieve 50 random items and use that to estimate the total size.
The return value has the following fields:
int | $samplekeys | Number of samples to use |
stdClass | Object with information about the store size |
Reimplemented in cachestore_file.
|
static |
Returns true if the user can add an instance of the store plugin.
bool |
Reimplemented in cachestore_dummy, cachestore_session, and cachestore_static.
cache_store::cleanup | ( | ) |
cache_store::create_clone | ( | array | $details = array() | ) |
Creates a clone of this store instance ready to be initialised.
This method is used so that a cache store needs only be constructed once. Future requests for an instance of the store will be given a cloned instance.
If you are writing a cache store that isn't compatible with the clone operation you can override this method to handle any situations you want before cloning.
array | $details | An array containing the details of the store from the cache config. |
cache_store |
|
abstract |
Deletes an item from the cache store.
string | $key | The key to delete. |
bool | Returns true if the operation was a success, false otherwise. |
Reimplemented in cachestore_apcu, cachestore_dummy, cachestore_file, cachestore_redis, cachestore_session, and cachestore_static.
|
abstract |
Deletes several keys from the cache in a single action.
array | $keys | The keys to delete |
int | The number of items successfully deleted. |
Reimplemented in cachestore_apcu, cachestore_dummy, cachestore_file, cachestore_redis, cachestore_session, and cachestore_static.
cache_store::estimate_stored_size | ( | $key, | |
$value ) |
Estimates the storage size used within this cache if the given value is stored with the given key.
This function is not exactly accurate; it does not necessarily take into account all the overheads involved. It is only intended to give a good idea of the relative size of different caches.
The default implementation serializes both key and value and sums the lengths (as a rough estimate which is probably good enough for everything unless the cache offers compression).
mixed | $key | Key |
mixed | $value | Value |
int | Size in bytes |
Reimplemented in cachestore_redis.
|
abstract |
Retrieves an item from the cache store given its key.
string | $key | The key to retrieve |
mixed | The data that was associated with the key, or false if the key did not exist. |
Reimplemented in cachestore_apcu, cachestore_dummy, cachestore_file, cachestore_redis, cachestore_session, and cachestore_static.
cache_store::get_last_io_bytes | ( | ) |
Gets the number of bytes read from or written to cache as a result of the last action.
This includes calls to the functions get(), get_many(), set(), and set_many(). The number is reset by calling any of these functions.
This should be the actual number of bytes of the value read from or written to cache, giving an impression of the network or other load. It will not be exactly the same amount as netowrk traffic because of protocol overhead, key text, etc.
If not supported, returns IO_BYTES_NOT_SUPPORTED.
int | Bytes read (or 0 if none/not supported) |
Reimplemented in cachestore_file, and cachestore_redis.
|
abstract |
Retrieves several items from the cache store in a single transaction.
If not all of the items are available in the cache then the data value for those that are missing will be set to false.
array | $keys | The array of keys to retrieve |
array | An array of items from the cache. There will be an item for each key, those that were not in the store will be set to false. |
Reimplemented in cachestore_apcu, cachestore_dummy, cachestore_file, cachestore_redis, cachestore_session, and cachestore_static.
|
staticinherited |
Returns the supported features as a binary flag.
array | $configuration | The configuration of a store to consider specifically. |
int | The supported features. |
Implemented in cachestore_apcu, cachestore_dummy, cachestore_file, cachestore_redis, cachestore_session, and cachestore_static.
|
staticinherited |
Returns the supported modes as a binary flag.
array | $configuration | The configuration of a store to consider specifically. |
int | The supported modes. |
Implemented in cachestore_apcu, cachestore_dummy, cachestore_file, cachestore_redis, cachestore_session, and cachestore_static.
cache_store::get_warnings | ( | ) |
Can be overridden to return any warnings this store instance should make to the admin.
This should be used to notify things like configuration conflicts etc. The warnings returned here will be displayed on the cache configuration screen.
string[] | An array of warning strings from the store instance. |
|
abstract |
Initialises a new instance of the cache store given the definition the instance is to be used for.
This function should be used to run any definition specific setup the store instance requires. Tasks such as creating storage areas, or creating indexes are best done here.
Its important to note that the initialise method is expected to always succeed. If there are setup tasks that may fail they should be done within the __construct method and should they fail is_ready should return false.
cache_definition | $definition |
Reimplemented in cachestore_apcu, cachestore_dummy, cachestore_file, cachestore_redis, cachestore_session, and cachestore_static.
|
staticinherited |
Generates an instance of the cache store that can be used for testing.
Returns an instance of the cache store, or false if one cannot be created.
cache_definition | $definition |
cache_store|false |
Implemented in cachestore_apcu, cachestore_dummy, cachestore_file, cachestore_redis, cachestore_session, and cachestore_static.
cache_store::instance_created | ( | ) |
Performs any necessary operation when the store instance has been created.
Reimplemented in cachestore_file.
cache_store::instance_deleted | ( | ) |
Performs any necessary operation when the store instance is being deleted.
This method may be called before the store has been initialised.
Reimplemented in cachestore_apcu, cachestore_dummy, cachestore_file, cachestore_redis, cachestore_session, and cachestore_static.
|
abstract |
Returns true if this cache store instance has been initialised.
bool |
Reimplemented in cachestore_apcu, cachestore_dummy, cachestore_file, cachestore_redis, cachestore_session, and cachestore_static.
cache_store::is_ready | ( | ) |
Returns true if this cache store instance is ready to use.
bool |
Reimplemented in cachestore_file, and cachestore_redis.
cache_store::is_searchable | ( | ) |
Returns true if the store instance is searchable.
bool |
|
staticinherited |
Static method to check if a store is usable with the given mode.
int | $mode | One of cache_store\MODE_* |
Implemented in cachestore_apcu, cachestore_dummy, cachestore_file, cachestore_redis, cachestore_session, and cachestore_static.
|
abstract |
Returns the name of this store instance.
string |
Reimplemented in cachestore_apcu, cachestore_dummy, cachestore_file, cachestore_redis, cachestore_session, and cachestore_static.
|
abstract |
Purges the cache deleting all items within it.
boolean | True on success. False otherwise. |
Reimplemented in cachestore_apcu, cachestore_dummy, cachestore_file, cachestore_redis, cachestore_session, and cachestore_static.
|
static |
Returns true if this cache store instance is both suitable for testing, and ready for testing.
Cache stores that support being used as the default store for unit and acceptance testing should override this function and return true if there requirements have been met.
bool |
Reimplemented in cachestore_apcu, and cachestore_redis.
|
abstract |
Sets an item in the cache given its key and data value.
string | $key | The key to use. |
mixed | $data | The data to set. |
bool | True if the operation was a success false otherwise. |
Reimplemented in cachestore_apcu, cachestore_dummy, cachestore_file, and cachestore_redis.
|
abstract |
Sets many items in the cache in a single transaction.
array | $keyvaluearray | An array of key value pairs. Each item in the array will be an associative array with two keys, 'key' and 'value'. |
int | The number of items successfully set. It is up to the developer to check this matches the number of items sent ... if they care that is. |
Reimplemented in cachestore_apcu, cachestore_dummy, cachestore_file, cachestore_redis, cachestore_session, and cachestore_static.
cache_store::store_total_size | ( | ) |
Gets the amount of memory/storage currently used by this cache store if known.
This value should be obtained quickly from the store itself, if available.
This is the total memory usage of the entire store, not for ther specific cache in question.
Where not supported (default), will always return null.
int|null | Amount of memory used in bytes or null |
Reimplemented in cachestore_file, and cachestore_redis.
cache_store::supports_data_guarantee | ( | ) |
Returns true if the store instance guarantees data.
bool |
cache_store::supports_dereferencing_objects | ( | ) |
Returns true if the store automatically dereferences objects.
bool |
cache_store::supports_multiple_identifiers | ( | ) |
Returns true if the store instance supports multiple identifiers.
bool |
Reimplemented in cachestore_file, cachestore_session, and cachestore_static.
cache_store::supports_native_ttl | ( | ) |
Returns true if the store instance supports native ttl.
bool |
|
staticinherited |
Generates the appropriate configuration required for unit testing.
array | Array of unit test configuration data to be used by initialise(). |
Implemented in cachestore_apcu, cachestore_dummy, cachestore_file, cachestore_redis, cachestore_session, and cachestore_static.
const cache_store::DEREFERENCES_OBJECTS = 16 |
The cache store dereferences objects.
When set, loaders will assume that all data coming from this store has already had all references resolved. So even for complex object structures it will not try to remove references again.
const cache_store::MODE_APPLICATION = 1 |
Application caches.
These are shared caches.
const cache_store::MODE_REQUEST = 4 |
Request caches.
Static caches really.
const cache_store::MODE_SESSION = 2 |
Session caches.
Just access to the PHP session.