Administration helper base class. More...

Inheritance diagram for core_cache\administration_helper:

Public Member Functions
	generate_admin_page (\core_cache\output\renderer $renderer)
	This function must be implemented to display the cache admin page.

	get_addable_lock_options ()
	This function must be implemented to get addable locks.

	get_definition_actions (\context $context, array $definitionsummary)
	This function must be implemented to display options for definition mappings.

	get_store_instance_actions (string $name, array $storedetails)
	This function must be implemented to display options for store instances.

	get_store_plugin_actions (string $name, array $plugindetails)
	This function must be implemented to display options for store plugins.

	get_usage (int $samplekeys)
	Gets usage information about the whole cache system.

	perform_cache_actions (string $action, array $forminfo)
	This function must be implemented to perform any page actions by a child class.

Static Public Member Functions
static	clean_old_session_data ($output=false)
	Cleans old session data from cache stores used for session based definitions.

static	cron ()
	Runs cron routines for MUC.

static	early_get_cache_plugins ()
	Returns an array of plugins without using core methods.

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

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

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

static	get_default_mode_stores ()
	Get the default stores for all modes.

static	get_definition_name ($definition)
	Returns the translated name of the definition.

static	get_definition_sharing_options (int $sharingoption, bool $isselectedoptions=true)
	Given a sharing option hash this function returns an array of strings that can be used to describe it.

static	get_definition_store_options (string $component, string $area)
	Get an array of stores that are suitable to be used for a given definition.

static	get_definition_summaries ()
	Returns an array about the definitions.

static	get_lock_summaries ()
	Returns an array summarising the locks available in the system.

static	get_site_identifier ()
	Returns the site identifier.

static	get_site_version ()
	Returns the site version.

static	get_stats ()
	Return the stats collected so far.

static	get_store_instance_summaries ()
	Returns an array containing all of the information about stores a renderer needs.

static	get_store_plugin_summaries ()
	Returns an array of information about plugins, everything a renderer needs.

static	get_stores_suitable_for_definition (cache_definition $definition)
	Returns stores suitable for use with a given definition.

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

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

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

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

static	is_cluster_available ()
	Checks whether the cluster mode is available in PHP.

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

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

static	purge_by_event ($event)
	Purges a cache of all information on a given event.

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

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

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

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

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

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

static	result_found ($value)
	A helper to determine whether a result was found.

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

static	update_site_identifier ($siteidentifier)
	Update the site identifier stored by the cache API.

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

Static Protected Member Functions
static	ensure_ready_for_stats ($store, $storeclass, $definition, $mode=cache_store::MODE_APPLICATION)
	Ensure that the stats array is ready to collect information for the given store and definition.

static	get_definition_stat_id_and_mode ($definition)
	Returns a string to describe the definition.

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

static	instance ()
	Returns an instance of the cache_helper.

Protected Attributes
array	$definitions = array()
	Used as a data store for initialised definitions.

array	$stores = array()
	Used as a data store for initialised cache stores We use this because we want to avoid establishing multiple instances of a single store.

Static Protected Attributes
static cache_helper	$instance
	The instance of the cache helper.

static string	$siteidentifier = null
	The site identifier used by the cache.

static array	$stats = array()
	Statistics gathered by the cache API during its operation will be used here.

Detailed Description

Administration helper base class.

Defines abstract methods for a subclass to define the admin page.

Author: Peter Burnett peter.nosp@m.burn.nosp@m.ett@c.nosp@m.atal.nosp@m.yst-a.nosp@m.u.ne.nosp@m.t

Copyright: 2020 Catalyst IT; 2012 Sam Hemelryk

License: http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

Member Function Documentation

◆ clean_old_session_data()

static cache_helper::clean_old_session_data ( $output = false )

staticinherited

Cleans old session data from cache stores used for session based definitions.

Parameters

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

◆ early_get_cache_plugins()

static cache_helper::early_get_cache_plugins ( )

staticinherited

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 values

array

◆ ensure_ready_for_stats()

static cache_helper::ensure_ready_for_stats	(	$store,
		$storeclass,
		$definition,
		$mode = cache_store::MODE_APPLICATION )

staticprotectedinherited

Ensure that the stats array is ready to collect information for the given store and definition.

Parameters

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

◆ generate_admin_page()

core_cache\administration_helper::generate_admin_page ( \core_cache\output\renderer $renderer )

abstract

This function must be implemented to display the cache admin page.

Parameters

core_cache\output\renderer $renderer the renderer used to generate the page.

Return values

string the HTML for the page.

Reimplemented in core_cache\local\administration_display_helper.

◆ get_addable_lock_options()

core_cache\administration_helper::get_addable_lock_options ( )

This function must be implemented to get addable locks.

Return values

array array of locks that are addable.

Reimplemented in core_cache\local\administration_display_helper.

◆ get_cache_stores()

static cache_helper::get_cache_stores ( cache_definition $definition )

staticinherited

Returns the cache stores to be used with the given definition.

Parameters

cache_definition $definition

Return values

array

◆ get_cachelock_for_store()

static cache_helper::get_cachelock_for_store ( cache_store $store )

staticinherited

Returns a cache_lock instance suitable for use with the store.

Parameters

cache_store $store

Return values

cache_lock_interface

◆ get_class_for_mode()

static cache_helper::get_class_for_mode ( $mode )

staticinherited

Returns the class for use as a cache loader for the given mode.

Parameters

int $mode One of cache_store\MODE_

Return values

string

Exceptions

coding_exception

◆ get_default_mode_stores()

static core_cache\administration_helper::get_default_mode_stores ( )

static

Get the default stores for all modes.

Return values

array An array containing sub-arrays, one for each mode.

◆ get_definition_actions()

core_cache\administration_helper::get_definition_actions	(	\context	$context,
		array	$definitionsummary )

This function must be implemented to display options for definition mappings.

Parameters

context	$context	the context for the definition.
array	$definitionsummary	the definition summary.

Return values

array array of actions.

Reimplemented in core_cache\local\administration_display_helper.

◆ get_definition_name()

static cache_helper::get_definition_name ( $definition )

staticinherited

Returns the translated name of the definition.

Parameters

cache_definition $definition

Return values

lang_string

◆ get_definition_sharing_options()

static core_cache\administration_helper::get_definition_sharing_options	(	int	$sharingoption,
		bool	$isselectedoptions = true )

static

Given a sharing option hash this function returns an array of strings that can be used to describe it.

Parameters

int	$sharingoption	The sharing option hash to get strings for.
bool	$isselectedoptions	Set to true if the strings will be used to view the selected options.

Return values

array An array of lang_string's.

◆ get_definition_stat_id_and_mode()

static cache_helper::get_definition_stat_id_and_mode ( $definition )

staticprotectedinherited

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.

Since: 2.9

Parameters

cache_definition | string $definition

Return values

string

◆ get_definition_store_options()

static core_cache\administration_helper::get_definition_store_options	(	string	$component,
		string	$area )

static

Get an array of stores that are suitable to be used for a given definition.

Parameters

string	$component
string	$area

Return values

array

Array containing 3 elements

An array of currently used stores
An array of suitable stores
An array of default stores

◆ get_definition_summaries()

static core_cache\administration_helper::get_definition_summaries ( )

static

Returns an array about the definitions.

All the information a renderer needs.

Return values

array for each store, an array containing various information about each store. See the code below for details

◆ get_lock_summaries()

static core_cache\administration_helper::get_lock_summaries ( )

static

Returns an array summarising the locks available in the system.

Return values

array array of lock summaries.

◆ get_site_identifier()

static cache_helper::get_site_identifier ( )

staticinherited

Returns the site identifier.

Return values

string

◆ get_site_version()

static cache_helper::get_site_version ( )

staticinherited

Returns the site version.

Return values

string

◆ get_stats()

static cache_helper::get_stats ( )

staticinherited

Return the stats collected so far.

Return values

array

◆ get_store_instance_actions()

core_cache\administration_helper::get_store_instance_actions	(	string	$name,
		array	$storedetails )

This function must be implemented to display options for store instances.

Parameters

string	$name	the store instance name.
array	$storedetails	array of store instance details.

Return values

array array of actions.

Reimplemented in core_cache\local\administration_display_helper.

◆ get_store_instance_summaries()

static core_cache\administration_helper::get_store_instance_summaries ( )

static

Returns an array containing all of the information about stores a renderer needs.

Return values

array

◆ get_store_plugin_actions()

core_cache\administration_helper::get_store_plugin_actions	(	string	$name,
		array	$plugindetails )

This function must be implemented to display options for store plugins.

Parameters

string	$name	the name of the store plugin.
array	$plugindetails	array of store plugin details.

Return values

array array of actions.

Reimplemented in core_cache\local\administration_display_helper.

◆ get_store_plugin_summaries()

static core_cache\administration_helper::get_store_plugin_summaries ( )

static

Returns an array of information about plugins, everything a renderer needs.

Return values

array for each store, an array containing various information about each store. See the code below for details

◆ get_stores_suitable_for_definition()

static cache_helper::get_stores_suitable_for_definition ( cache_definition $definition )

staticinherited

Returns stores suitable for use with a given definition.

Parameters

cache_definition $definition

Return values

cache_store[]

◆ get_stores_suitable_for_mode_default()

static cache_helper::get_stores_suitable_for_mode_default ( )

staticinherited

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 values

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

◆ get_usage()

core_cache\administration_helper::get_usage ( int $samplekeys )

abstract

Gets usage information about the whole cache system.

This is a slow function and should only be used on an admin information page.

The returned array lists all cache definitions with fields 'cacheid' and 'stores'. For each store, the following fields are available:

name (store name)
class (e.g. cachestore_redis)
supported (true if we have any information)
items (number of items stored)
mean (mean size of item)
sd (standard deviation for item sizes)
margin (margin of error for mean at 95% confidence)
storetotal (total usage for store if known, otherwise null)

The storetotal field will be the same for every cache that uses the same store.

Parameters

int $samplekeys Number of keys to sample when checking size of large caches

Return values

array Details of cache usage

Reimplemented in core_cache\local\administration_display_helper.

◆ hash_key()

static cache_helper::hash_key	(		$key,
		cache_definition	$definition )

staticinherited

Hashes a descriptive key to make it shorter and still unique.

Parameters

string \| int	$key
cache_definition	$definition

Return values

string

◆ initialise_cachestore_instances()

static cache_helper::initialise_cachestore_instances	(	array	$stores,
		cache_definition	$definition )

staticprotectedinherited

Internal function for initialising an array of stores against a given cache definition.

Parameters

array	$stores
cache_definition	$definition

Return values

cache_store[]

◆ instance()

static cache_helper::instance ( )

staticprotectedinherited

Returns an instance of the cache_helper.

This is designed for internal use only and acts as a static store. @staticvar null $instance

Return values

cache_helper

◆ invalidate_by_definition()

static cache_helper::invalidate_by_definition	(		$component,
			$area,
		array	$identifiers = array(),
			$keys = array() )

staticinherited

Invalidates a given set of keys from a given definition.

Todo: Invalidating by definition should also add to the event cache so that sessions can be invalidated (when required).

Parameters

string	$component
string	$area
array	$identifiers
array \| string \| int	$keys

Return values

boolean

Exceptions

coding_exception

◆ invalidate_by_event()

static cache_helper::invalidate_by_event	(		$event,
		array	$keys )

staticinherited

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.

Parameters

string	$event
array	$keys

◆ is_cluster_available()

static cache_helper::is_cluster_available ( )

staticinherited

Checks whether the cluster mode is available in PHP.

Return values

bool	Return true if the PHP supports redis cluster, otherwise false.

◆ perform_cache_actions()

core_cache\administration_helper::perform_cache_actions	(	string	$action,
		array	$forminfo )

abstract

This function must be implemented to perform any page actions by a child class.

Parameters

string	$action	the action to perform.
array	$forminfo	empty array to be set by actions.

Return values

array array of form info.

Reimplemented in core_cache\local\administration_display_helper.

◆ purge_all()

static cache_helper::purge_all ( $usewriter = false )

staticinherited

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.

Parameters

bool $usewriter If set to true the cache_config_writer class is used. This class is special as it avoids it is still usable when caches have been disabled. Please use this option only if you really must. It's purpose is to allow the cache to be purged when it would be otherwise impossible.

◆ purge_by_definition()

static cache_helper::purge_by_definition	(		$component,
			$area,
		array	$identifiers = array() )

staticinherited

Purges the cache for a specific definition.

Parameters

string	$component
string	$area
array	$identifiers

Return values

bool

◆ purge_by_event()

static cache_helper::purge_by_event ( $event )

staticinherited

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.

Parameters

string $event

◆ purge_store()

static cache_helper::purge_store	(		$storename,
		cache_config	$config = null )

staticinherited

Purges a store given its name.

Parameters

string	$storename
cache_config	$config

Return values

bool

◆ purge_stores_used_by_definition()

static cache_helper::purge_stores_used_by_definition	(		$component,
			$area )

staticinherited

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.

Parameters

string	$component
string	$area

◆ ready_for_early_init()

static cache_helper::ready_for_early_init ( )

staticinherited

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 values

bool

◆ record_cache_hit()

static cache_helper::record_cache_hit	(		$store,
			$definition,
		int	$hits = 1,
		int	$readbytes = cache_store::IO_BYTES_NOT_SUPPORTED )

staticinherited

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.

◆ record_cache_miss()

static cache_helper::record_cache_miss	(	$store,
		$definition,
		$misses = 1 )

staticinherited

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.

◆ record_cache_set()

static cache_helper::record_cache_set	(		$store,
			$definition,
		int	$sets = 1,
		int	$writebytes = cache_store::IO_BYTES_NOT_SUPPORTED )

staticinherited

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.

◆ result_found()

static cache_helper::result_found ( $value )

staticinherited

A helper to determine whether a result was found.

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

Parameters

mixed $value

Return values

bool

◆ update_definitions()

static cache_helper::update_definitions ( $coreonly = false )

staticinherited

Finds all definitions and updates them within the cache config file.

Parameters

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

◆ update_site_identifier()

static cache_helper::update_site_identifier ( $siteidentifier )

staticinherited

Update the site identifier stored by the cache API.

Parameters

string $siteidentifier

Return values

string The new site identifier.

◆ warnings()

static cache_helper::warnings ( array $stores = null )

staticinherited

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.

Parameters

array | null $stores An array of stores to get warnings for, or null for all.

Return values

string[]

Member Data Documentation

◆ $siteidentifier

string cache_helper::$siteidentifier = null

staticprotectedinherited

The site identifier used by the cache.

Set the first time get_site_identifier is called.

The documentation for this class was generated from the following file:

cache/classes/administration_helper.php

Public Member Functions

Static Public Member Functions

Static Protected Member Functions

Protected Attributes

Static Protected Attributes

Detailed Description

Member Function Documentation

◆ clean_old_session_data()

◆ early_get_cache_plugins()

◆ ensure_ready_for_stats()

◆ generate_admin_page()

◆ get_addable_lock_options()

◆ get_cache_stores()

◆ get_cachelock_for_store()

◆ get_class_for_mode()

◆ get_default_mode_stores()

◆ get_definition_actions()

◆ get_definition_name()

◆ get_definition_sharing_options()

◆ get_definition_stat_id_and_mode()

◆ get_definition_store_options()

◆ get_definition_summaries()

◆ get_lock_summaries()

◆ get_site_identifier()

◆ get_site_version()

◆ get_stats()

◆ get_store_instance_actions()

◆ get_store_instance_summaries()

◆ get_store_plugin_actions()

◆ get_store_plugin_summaries()

◆ get_stores_suitable_for_definition()

◆ get_stores_suitable_for_mode_default()

◆ get_usage()

◆ hash_key()

◆ initialise_cachestore_instances()

◆ instance()

◆ invalidate_by_definition()

◆ invalidate_by_event()

◆ is_cluster_available()

◆ perform_cache_actions()

◆ purge_all()

◆ purge_by_definition()

◆ purge_by_event()

◆ purge_store()

◆ purge_stores_used_by_definition()

◆ ready_for_early_init()

◆ record_cache_hit()

◆ record_cache_miss()

◆ record_cache_set()

◆ result_found()

◆ update_definitions()

◆ update_site_identifier()

◆ warnings()

Member Data Documentation

◆ $siteidentifier