Search moodle.org's
Developer Documentation

See Release Notes

  • Bug fixes for general core bugs in 4.2.x will end 22 April 2024 (12 months).
  • Bug fixes for security issues in 4.2.x will end 7 October 2024 (18 months).
  • PHP version: minimum PHP 8.0.0 Note: minimum PHP version has increased since Moodle 4.1. PHP 8.1.x is supported too.

Differences Between: [Versions 310 and 402] [Versions 311 and 402] [Versions 39 and 402] [Versions 400 and 402] [Versions 401 and 402]

Cache helper class This file is part of Moodle's cache API, affectionately called MUC. It contains the components that are requried in order to use caching.

Copyright: 2012 Sam Hemelryk
License: http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
File Size: 876 lines (36 kb)
Included or required:0 times
Referenced: 0 times
Includes or requires: 0 files

Defines 1 class


Class: cache_helper  - X-Ref

The cache helper class.

The cache helper class provides common functionality to the cache API and is useful to developers within to interact with
the cache API in a general way.

ready_for_early_init()   X-Ref
Returns true if the cache API can be initialised before Moodle has finished initialising itself.

This check is essential when trying to cache the likes of configuration information. It checks to make sure that the cache
configuration file has been created which allows use to set up caching when ever is required.

return: bool

instance()   X-Ref
Returns an instance of the cache_helper.

This is designed for internal use only and acts as a static store.
return: cache_helper

__construct()   X-Ref
Constructs an instance of the cache_helper class. Again for internal use only.


get_class_for_mode($mode)   X-Ref
Returns the class for use as a cache loader for the given mode.

param: int $mode One of cache_store::MODE_
return: string

get_cache_stores(cache_definition $definition)   X-Ref
Returns the cache stores to be used with the given definition.

param: cache_definition $definition
return: array

initialise_cachestore_instances(array $stores, cache_definition $definition)   X-Ref
Internal function for initialising an array of stores against a given cache definition.

param: array $stores
param: cache_definition $definition
return: cache_store[]

get_cachelock_for_store(cache_store $store)   X-Ref
Returns a cache_lock instance suitable for use with the store.

param: cache_store $store
return: cache_lock_interface

early_get_cache_plugins()   X-Ref
Returns an array of plugins without using core methods.

This function explicitly does NOT use core functions as it will in some circumstances be called before Moodle has
finished initialising. This happens when loading configuration for instance.

return: array

invalidate_by_definition($component, $area, array $identifiers = array()   X-Ref
Invalidates a given set of keys from a given definition.

param: string $component
param: string $area
param: array $identifiers
param: array|string|int $keys
return: boolean

invalidate_by_event($event, array $keys)   X-Ref
Invalidates a given set of keys by means of an event.

Events cannot determine what identifiers might need to be cleared. Event based purge and invalidation
are only supported on caches without identifiers.

param: string $event
param: array $keys

purge_by_definition($component, $area, array $identifiers = array()   X-Ref
Purges the cache for a specific definition.

param: string $component
param: string $area
param: array $identifiers
return: bool

purge_by_event($event)   X-Ref
Purges a cache of all information on a given event.

Events cannot determine what identifiers might need to be cleared. Event based purge and invalidation
are only supported on caches without identifiers.

param: string $event

ensure_ready_for_stats($store, $storeclass, $definition, $mode = cache_store::MODE_APPLICATION)   X-Ref
Ensure that the stats array is ready to collect information for the given store and definition.

param: string $store
param: string $storeclass
param: string $definition A string that identifies the definition.
param: int $mode One of cache_store::MODE_*. Since 2.9.

get_definition_stat_id_and_mode($definition)   X-Ref
Returns a string to describe the definition.

This method supports the definition as a string due to legacy requirements.
It is backwards compatible when a string is passed but is not accurate.

param: cache_definition|string $definition
return: string

record_cache_hit($store, $definition, int $hits = 1, int $readbytes = cache_store::IO_BYTES_NOT_SUPPORTED)   X-Ref
Record a cache hit in the stats for the given store and definition.

In Moodle 2.9 the $definition argument changed from accepting only a string to accepting a string or a
cache_definition instance. It is preferable to pass a cache definition instance.

In Moodle 3.9 the first argument changed to also accept a cache_store.

param: string|cache_store $store
param: cache_definition $definition You used to be able to pass a string here, however that is deprecated please pass the
param: int $hits The number of hits to record (by default 1)
param: int $readbytes Number of bytes read from the cache or cache_store::IO_BYTES_NOT_SUPPORTED

record_cache_miss($store, $definition, $misses = 1)   X-Ref
Record a cache miss in the stats for the given store and definition.

In Moodle 2.9 the $definition argument changed from accepting only a string to accepting a string or a
cache_definition instance. It is preferable to pass a cache definition instance.

In Moodle 3.9 the first argument changed to also accept a cache_store.

param: string|cache_store $store
param: cache_definition $definition You used to be able to pass a string here, however that is deprecated please pass the
param: int $misses The number of misses to record (by default 1)

record_cache_set($store, $definition, int $sets = 1,int $writebytes = cache_store::IO_BYTES_NOT_SUPPORTED)   X-Ref
Record a cache set in the stats for the given store and definition.

In Moodle 2.9 the $definition argument changed from accepting only a string to accepting a string or a
cache_definition instance. It is preferable to pass a cache definition instance.

In Moodle 3.9 the first argument changed to also accept a cache_store.

param: string|cache_store $store
param: cache_definition $definition You used to be able to pass a string here, however that is deprecated please pass the
param: int $sets The number of sets to record (by default 1)
param: int $writebytes Number of bytes written to the cache or cache_store::IO_BYTES_NOT_SUPPORTED

get_stats()   X-Ref
Return the stats collected so far.

return: array

purge_all($usewriter = false)   X-Ref
Purge all of the cache stores of all of their data.

Think twice before calling this method. It will purge **ALL** caches regardless of whether they have been used recently or
anything. This will involve full setup of the cache + the purge operation. On a site using caching heavily this WILL be
painful.

param: bool $usewriter If set to true the cache_config_writer class is used. This class is special as it avoids

purge_store($storename, cache_config $config = null)   X-Ref
Purges a store given its name.

param: string $storename
param: cache_config $config
return: bool

purge_stores_used_by_definition($component, $area)   X-Ref
Purges all of the stores used by a definition.

Unlike cache_helper::purge_by_definition this purges all of the data from the stores not
just the data relating to the definition.
This function is useful when you must purge a definition that requires setup but you don't
want to set it up.

param: string $component
param: string $area

get_definition_name($definition)   X-Ref
Returns the translated name of the definition.

param: cache_definition $definition
return: lang_string

hash_key($key, cache_definition $definition)   X-Ref
Hashes a descriptive key to make it shorter and still unique.

param: string|int $key
param: cache_definition $definition
return: string

update_definitions($coreonly = false)   X-Ref
Finds all definitions and updates them within the cache config file.

param: bool $coreonly If set to true only core definitions will be updated.

update_site_identifier($siteidentifier)   X-Ref
Update the site identifier stored by the cache API.

param: string $siteidentifier
return: string The new site identifier.

get_site_identifier()   X-Ref
Returns the site identifier.

return: string

get_site_version()   X-Ref
Returns the site version.

return: string

cron()   X-Ref
Runs cron routines for MUC.


clean_old_session_data($output = false)   X-Ref
Cleans old session data from cache stores used for session based definitions.

param: bool $output If set to true output will be given.

get_stores_suitable_for_mode_default()   X-Ref
Returns an array of stores that would meet the requirements for every definition.

These stores would be 100% suitable to map as defaults for cache modes.

return: array[] An array of stores, keys are the store names.

get_stores_suitable_for_definition(cache_definition $definition)   X-Ref
Returns stores suitable for use with a given definition.

param: cache_definition $definition
return: cache_store[]

warnings(array $stores = null)   X-Ref
Returns an array of warnings from the cache API.

The warning returned here are for things like conflicting store instance configurations etc.
These get shown on the admin notifications page for example.

param: array|null $stores An array of stores to get warnings for, or null for all.
return: string[]

result_found($value)   X-Ref
A helper to determine whether a result was found.

This has been deemed required after people have been confused by the fact that [] == false.

param: mixed $value
return: bool