A session cache. More...

Inheritance diagram for cache_session:

Public Member Functions
	__construct (cache_definition $definition, cache_store $store, $loader=null)
	Override the cache::construct method. More...

	delete ($key, $recurse=true)
	Delete the given key from the cache. More...

	delete_many (array $keys, $recurse=true)
	Delete all of the given keys from the cache. More...

	get ($key, $strictness=IGNORE_MISSING)
	Retrieves the value for the given key from the cache. More...

	get_many (array $keys, $strictness=IGNORE_MISSING)
	Retrieves an array of values for an array of keys. More...

	has ($key)
	Test is a cache has a key. More...

	has ($key, $tryloadifpossible=false)
	Test is a cache has a key. More...

	has_all (array $keys)
	Test is a cache has all of the given keys. More...

	has_any (array $keys)
	Test if a cache has at least one of the given keys. More...

	purge ()
	Purges the cache store, and loader if there is one. More...

	purge_current_user ()
	Purges the session cache of all data belonging to the current user. More...

	set ($key, $data)
	Sends a key => value pair to the cache. More...

	set_identifiers (array $identifiers)
	Alters the identifiers that have been provided to the definition. More...

	set_many (array $keyvaluearray)
	Sends several key => value pairs to the cache. More...

Static Public Member Functions
static	compare_purge_tokens ($tokena, $tokenb)
	Compare a pair of purge tokens. More...

static	get_purge_token ($reset=false)
	Get a 'purge' token used for cache invalidation handling. More...

static	make ($component, $area, array $identifiers=array(), $unused=null)
	Creates a new cache instance for a pre-defined definition. More...

static	make_from_params ($mode, $component, $area, array $identifiers=array(), array $options=array())
	Creates a new cache instance based upon the given params. More...

static	now ($float=false)
	Returns the timestamp from the first request for the time from the cache API. More...

Public Attributes
const	KEY_PREFIX = 'sess_'
	Constant used to prefix keys.

const	LASTACCESS = '__lastaccess__'
	This is the key used to track last access.

Protected Member Functions
	check_tracked_user ()
	Check that this cache instance is tracking the current user.

	deep_clone ($value)
	Creates a reference free clone of the given value. More...

	delete_from_persist_cache ()

	get_datasource ()
	Returns the data source associated with this cache. More...

	get_definition ()
	Returns the cache definition. More...

	get_from_persist_cache ()

	get_key_prefix ()
	Returns the prefix used for all keys. More...

	get_loader ()
	Returns the loader associated with this instance. More...

	get_store ()
	Returns the cache store. More...

	handle_invalidation_events ()
	Process any outstanding invalidation events for the cache we are registering,. More...

	has_a_ttl ()
	Returns true if the cache is making use of a ttl. More...

	is_in_persist_cache ()

	is_using_persist_cache ()

	parse_key ($key)
	Parses the key turning it into a string (or array is required) suitable to be passed to the cache store. More...

	requires_serialisation ($value, $depth=1)
	Checks to see if a var requires serialisation. More...

	set_data_source (cache_data_source $datasource)
	Set the data source for this cache. More...

	set_in_persist_cache ()

	set_is_sub_loader ($setting=true)
	Used to inform the loader of its state as a sub loader, or as the top of the chain. More...

	set_loader (cache_loader $loader)
	Set the loader for this cache. More...

	set_session_id ()
	Sets the session id for the loader.

	static_acceleration_delete ($key)
	Deletes an item from the static acceleration array. More...

	static_acceleration_get ($key)
	Returns the item from the static acceleration array if it exists there. More...

	static_acceleration_has ($key)
	Returns true if the requested key exists within the static acceleration array. More...

	static_acceleration_purge ()
	Purge the static acceleration cache.

	static_acceleration_set ($key, $data)
	Sets a key value pair into the static acceleration array. More...

	store_supports_key_awareness ()
	Returns true if the store supports key awareness. More...

	store_supports_native_locking ()
	Returns true if the store natively supports locking. More...

	store_supports_native_ttl ()
	Returns true if the cache store supports native ttl. More...

	unref ($data)
	Removes references where required. More...

	use_static_acceleration ()
	The session loader never uses static acceleration. More...

Protected Attributes
int	$currentuserid = null
	The userid this cache is currently using.

bool	$perfdebug = false
	Gets set to true if we want to collect performance information about the cache API.

array	$session = null
	The session data for the above session id.

array	$sessionid = null
	The session id we are currently using.

strubg	$storetype = 'unknown'
	Gets set to the class name of the store during initialisation. More...

bool	$subloader = false
	Determines if this loader is a sub loader, not the top of the chain.

Static Protected Attributes
static int	$loadeduserid = null
	The user the session has been established for.

static int	$now
	We need a timestamp to use within the cache API. More...

static string	$purgetoken
	A purge token used to distinguish between multiple cache purges in the same second. More...

Detailed Description

A session cache.

This class is used for session caches returned by the cache::make methods.

It differs from the application loader in a couple of noteable ways:

Sessions are always expected to exist. Because of this we don't ever use the static acceleration array.
Session data for a loader instance (store + definition) is consolidate into a single array for storage within the store. Along with this we embed a lastaccessed time with the data. This way we can check sessions for a last access time.
Session stores are required to support key searching and must implement cache_is_searchable. This ensures stores used for the cache can be targetted for garbage collection of session data.

This cache class should never be interacted with directly. Instead you should always use the cache::make methods. It is technically possible to call those methods through this class however there is no guarantee that you will get an instance of this class back again.

Todo:: we should support locking in the session as well. Should be pretty simple to set up.

Constructor & Destructor Documentation

◆ __construct()

cache_session::__construct	(	cache_definition	$definition,
		cache_store	$store,
			$loader = `null`
	)

Override the cache::construct method.

This function gets overriden so that we can process any invalidation events if need be. If the definition doesn't have any invalidation events then this occurs exactly as it would for the cache class. Otherwise we look at the last invalidation time and then check the invalidation data for events that have occured between then now.

You should not call this method from your code, instead you should use the cache::make methods.

Parameters

cache_definition	$definition
cache_store	$store
cache_loader \| cache_data_source	$loader

Reimplemented from cache.

Member Function Documentation

◆ compare_purge_tokens()

static cache::compare_purge_tokens	(	$tokena,
		$tokenb
	)

staticinherited

Compare a pair of purge tokens.

If the two tokens are identical, then the return value is 0. If the time component of token A is newer than token B, then a positive value is returned. If the time component of token B is newer than token A, then a negative value is returned.

Note: This function is intended for use from within the Cache API only and not by plugins, or cache stores.

Parameters

string	$tokena
string	$tokenb

Return values

int

◆ deep_clone()

cache::deep_clone ( $value )

protectedinherited

Creates a reference free clone of the given value.

Parameters

mixed $value

Return values

mixed

◆ delete()

cache_session::delete	(	$key,
		$recurse = `true`
	)

Delete the given key from the cache.

Parameters

string \| int	$key	The key to delete.
bool	$recurse	When set to true the key will also be deleted from all stacked cache loaders and their stores. This happens by default and ensure that all the caches are consistent. It is NOT recommended to change this.

Return values

bool	True of success, false otherwise.

Reimplemented from cache.

◆ delete_from_persist_cache()

cache::delete_from_persist_cache ( )

protectedinherited

Deprecated:: since 2.6

See also: cache::static_acceleration_delete()

◆ delete_many()

cache_session::delete_many	(	array	$keys,
			$recurse = `true`
	)

Delete all of the given keys from the cache.

Parameters

array	$keys	The key to delete.
bool	$recurse	When set to true the key will also be deleted from all stacked cache loaders and their stores. This happens by default and ensure that all the caches are consistent. It is NOT recommended to change this.

Return values

int	The number of items successfully deleted.

Reimplemented from cache.

◆ get()

cache_session::get	(	$key,
		$strictness = `IGNORE_MISSING`
	)

Retrieves the value for the given key from the cache.

Parameters

string \| int	$key	The key for the data being requested. It can be any structure although using a scalar string or int is recommended in the interests of performance. In advanced cases an array may be useful such as in situations requiring the multi-key functionality.
int	$strictness	One of IGNORE_MISSING \| MUST_EXIST

Return values

mixed|false The data from the cache or false if the key did not exist within the cache.

Exceptions

coding_exception

Reimplemented from cache.

◆ get_datasource()

cache::get_datasource ( )

protectedinherited

Returns the data source associated with this cache.

Since: Moodle 2.4.4

Return values

cache_data_source|false

◆ get_definition()

cache::get_definition ( )

protectedinherited

Returns the cache definition.

Return values

cache_definition

◆ get_from_persist_cache()

cache::get_from_persist_cache ( )

protectedinherited

Deprecated:: since 2.6

See also: cache::static_acceleration_get

◆ get_key_prefix()

cache_session::get_key_prefix ( )

protected

Returns the prefix used for all keys.

Return values

string

◆ get_loader()

cache::get_loader ( )

protectedinherited

Returns the loader associated with this instance.

Since: Moodle 2.4.4

Return values

cache|false

◆ get_many()

cache_session::get_many	(	array	$keys,
			$strictness = `IGNORE_MISSING`
	)

Retrieves an array of values for an array of keys.

Using this function comes with potential performance implications. Not all cache stores will support get_many/set_many operations and in order to replicate this functionality will call the equivalent singular method for each item provided. This should not deter you from using this function as there is a performance benefit in situations where the cache store does support it, but you should be aware of this fact.

Parameters

array	$keys	The keys of the data being requested. Each key can be any structure although using a scalar string or int is recommended in the interests of performance. In advanced cases an array may be useful such as in situations requiring the multi-key functionality.
int	$strictness	One of IGNORE_MISSING or MUST_EXIST.

Return values

array An array of key value pairs for the items that could be retrieved from the cache. If MUST_EXIST was used and not all keys existed within the cache then an exception will be thrown. Otherwise any key that did not exist will have a data value of false within the results.

Exceptions

coding_exception

Reimplemented from cache.

◆ get_purge_token()

static cache::get_purge_token ( $reset = false )

staticinherited

Get a 'purge' token used for cache invalidation handling.

Note: This function is intended for use from within the Cache API only and not by plugins, or cache stores.

Parameters

bool $reset Whether to reset the token and generate a new one.

Return values

string

◆ get_store()

cache::get_store ( )

protectedinherited

Returns the cache store.

Return values

cache_store

◆ handle_invalidation_events()

cache::handle_invalidation_events ( )

protectedinherited

Process any outstanding invalidation events for the cache we are registering,.

Identifiers and event invalidation are not compatible with each other at this time. As a result the cache does not need to consider identifiers when working out what to invalidate.

◆ has() [1/2]

cache_loader::has ( $key )

inherited

Test is a cache has a key.

The use of the has methods is strongly discouraged. In a high load environment the cache may well change between the test and any subsequent action (get, set, delete etc). Instead it is recommended to write your code in such a way they it performs the following steps:

Attempt to retrieve the information.
Generate the information.
Attempt to set the information

Its also worth mentioning that not all stores support key tests. For stores that don't support key tests this functionality is mimicked by using the equivalent get method. Just one more reason you should not use these methods unless you have a very good reason to do so.

Parameters

string | int $key

Return values

bool	True if the cache has the requested key, false otherwise.

◆ has() [2/2]

cache_session::has	(	$key,
		$tryloadifpossible = `false`
	)

Test is a cache has a key.

The use of the has methods is strongly discouraged. In a high load environment the cache may well change between the test and any subsequent action (get, set, delete etc). Instead it is recommended to write your code in such a way they it performs the following steps:

Attempt to retrieve the information.
Generate the information.
Attempt to set the information

Its also worth mentioning that not all stores support key tests. For stores that don't support key tests this functionality is mimicked by using the equivalent get method. Just one more reason you should not use these methods unless you have a very good reason to do so.

Parameters

string \| int	$key
bool	$tryloadifpossible	If set to true, the cache doesn't contain the key, and there is another cache loader or data source then the code will try load the key value from the next item in the chain.

Return values

bool	True if the cache has the requested key, false otherwise.

Reimplemented from cache.

◆ has_a_ttl()

cache::has_a_ttl ( )

protectedinherited

Returns true if the cache is making use of a ttl.

Return values

bool

◆ has_all()

cache_session::has_all ( array $keys )

Test is a cache has all of the given keys.

It is strongly recommended to avoid the use of this function if not absolutely required. In a high load environment the cache may well change between the test and any subsequent action (get, set, delete etc).

Its also worth mentioning that not all stores support key tests. For stores that don't support key tests this functionality is mimicked by using the equivalent get method. Just one more reason you should not use these methods unless you have a very good reason to do so.

Parameters

array $keys

Return values

bool	True if the cache has all of the given keys, false otherwise.

Reimplemented from cache.

◆ has_any()

cache_session::has_any ( array $keys )

Test if a cache has at least one of the given keys.

It is strongly recommended to avoid the use of this function if not absolutely required. In a high load environment the cache may well change between the test and any subsequent action (get, set, delete etc).

Its also worth mentioning that not all stores support key tests. For stores that don't support key tests this functionality is mimicked by using the equivalent get method. Just one more reason you should not use these methods unless you have a very good reason to do so.

Parameters

array $keys

Return values

bool	True if the cache has at least one of the given keys

Reimplemented from cache.

◆ is_in_persist_cache()

cache::is_in_persist_cache ( )

protectedinherited

See also: cache::static_acceleration_has

Deprecated:: since 2.6

◆ is_using_persist_cache()

cache::is_using_persist_cache ( )

protectedinherited

Deprecated:: since 2.6

See also: cache::use_static_acceleration()

◆ make()

static cache::make	(		$component,
			$area,
		array	$identifiers = `array()`,
			$unused = `null`
	)

staticinherited

Creates a new cache instance for a pre-defined definition.

Parameters

string	$component	The component for the definition
string	$area	The area for the definition
array	$identifiers	Any additional identifiers that should be provided to the definition.
string	$unused	Used to be datasourceaggregate but that was removed and this is now unused.

Return values

cache_application|cache_session|cache_store

◆ make_from_params()

static cache::make_from_params	(		$mode,
			$component,
			$area,
		array	$identifiers = `array()`,
		array	$options = `array()`
	)

staticinherited

Creates a new cache instance based upon the given params.

Parameters

int	$mode	One of cache_store::MODE_*
string	$component	The component this cache relates to.
string	$area	The area this cache relates to.
array	$identifiers	Any additional identifiers that should be provided to the definition.
array	$options	An array of options, available options are: simplekeys : Set to true if the keys you will use are a-zA-Z0-9_ simpledata : Set to true if the type of the data you are going to store is scalar, or an array of scalar vars staticacceleration : If set to true the cache will hold onto data passing through it. staticaccelerationsize : The max size for the static acceleration array.

Return values

cache_application|cache_session|cache_store

◆ now()

static cache::now ( $float = false )

staticinherited

Returns the timestamp from the first request for the time from the cache API.

This stamp needs to be used for all ttl and time based operations to ensure that we don't end up with timing issues.

Parameters

bool $float Whether to use floating precision accuracy.

Return values

int|float

◆ parse_key()

cache_session::parse_key ( $key )

protected

Parses the key turning it into a string (or array is required) suitable to be passed to the cache store.

This function is called for every operation that uses keys. For this reason we use this function to also check that the current user is the same as the user who last used this cache.

On top of that if prepends the string 'sess_' to the start of all keys. The _ ensures things are easily identifiable.

Parameters

string | int $key As passed to get|set|delete etc.

Return values

string|array String unless the store supports multi-identifiers in which case an array if returned.

Reimplemented from cache.

◆ purge()

cache_session::purge ( )

Purges the cache store, and loader if there is one.

Return values

bool	True on success, false otherwise

Reimplemented from cache.

◆ purge_current_user()

cache_session::purge_current_user ( )

Purges the session cache of all data belonging to the current user.

Reimplemented from cache.

◆ requires_serialisation()

cache::requires_serialisation	(	$value,
		$depth = `1`
	)

protectedinherited

Checks to see if a var requires serialisation.

Parameters

mixed	$value	The value to check.
int	$depth	Used to ensure we don't enter an endless loop (think recursion).

Return values

bool	Returns true if the value is going to require serialisation in order to ensure a reference free copy or false if its safe to clone.

◆ set()

cache_session::set	(	$key,
		$data
	)

Sends a key => value pair to the cache.

// This code will add four entries to the cache, one for each url. $cache->set('main', 'http://moodle.org'); $cache->set('docs', 'http://docs.moodle.org'); $cache->set('tracker', 'http://tracker.moodle.org'); $cache->set('qa', 'http://qa.moodle.net');

Parameters

string \| int	$key	The key for the data being requested. It can be any structure although using a scalar string or int is recommended in the interests of performance. In advanced cases an array may be useful such as in situations requiring the multi-key functionality.
mixed	$data	The data to set against the key.

Return values

bool	True on success, false otherwise.

Reimplemented from cache.

◆ set_data_source()

cache::set_data_source ( cache_data_source $datasource )

protectedinherited

Set the data source for this cache.

Parameters

cache_data_source $datasource

◆ set_identifiers()

cache::set_identifiers ( array $identifiers )

inherited

Alters the identifiers that have been provided to the definition.

This is an advanced method and should not be used unless really needed. It allows the developer to slightly alter the definition without having to re-establish the cache. It will cause more processing as the definition will need to clear and reprepare some of its properties.

Parameters

array $identifiers

◆ set_in_persist_cache()

cache::set_in_persist_cache ( )

protectedinherited

Deprecated:: since 2.6

See also: cache::static_acceleration_set

◆ set_is_sub_loader()

cache::set_is_sub_loader ( $setting = true )

protectedinherited

Used to inform the loader of its state as a sub loader, or as the top of the chain.

This is important as it ensures that we do not have more than one loader keeping static acceleration data. Subloaders need to be "pure" loaders in the sense that they are used to store and retrieve information from stores or the next loader/data source in the chain. Nothing fancy, nothing flash.

Parameters

bool $setting

◆ set_loader()

cache::set_loader ( cache_loader $loader )

protectedinherited

Set the loader for this cache.

Parameters

cache_loader $loader

◆ set_many()

cache_session::set_many ( array $keyvaluearray )

Sends several key => value pairs to the cache.

Using this function comes with potential performance implications. Not all cache stores will support get_many/set_many operations and in order to replicate this functionality will call the equivalent singular method for each item provided. This should not deter you from using this function as there is a performance benefit in situations where the cache store does support it, but you should be aware of this fact.

// This code will add four entries to the cache, one for each url. $cache->set_many(array( 'main' => 'http://moodle.org', 'docs' => 'http://docs.moodle.org', 'tracker' => 'http://tracker.moodle.org', 'qa' => ''http://qa.moodle.net' ));

Parameters

array $keyvaluearray An array of key => value pairs to send to the cache.

Return values

int	The number of items successfully set. It is up to the developer to check this matches the number of items. ... if they care that is.

Reimplemented from cache.

◆ static_acceleration_delete()

cache::static_acceleration_delete ( $key )

protectedinherited

Deletes an item from the static acceleration array.

Parameters

string | int $key As given to get|set|delete

Return values

bool	True on success, false otherwise.

◆ static_acceleration_get()

cache::static_acceleration_get ( $key )

protectedinherited

Returns the item from the static acceleration array if it exists there.

Parameters

string $key The parsed key

Return values

mixed|false Dereferenced data from the static acceleration array or false if it wasn't there.

◆ static_acceleration_has()

cache::static_acceleration_has ( $key )

protectedinherited

Returns true if the requested key exists within the static acceleration array.

Parameters

string $key The parsed key

Return values

bool

◆ static_acceleration_set()

cache::static_acceleration_set	(	$key,
		$data
	)

protectedinherited

Sets a key value pair into the static acceleration array.

Parameters

string	$key	The parsed key
mixed	$data

Return values

bool

◆ store_supports_key_awareness()

cache::store_supports_key_awareness ( )

protectedinherited

Returns true if the store supports key awareness.

Return values

bool

◆ store_supports_native_locking()

cache::store_supports_native_locking ( )

protectedinherited

Returns true if the store natively supports locking.

Return values

bool

◆ store_supports_native_ttl()

cache::store_supports_native_ttl ( )

protectedinherited

Returns true if the cache store supports native ttl.

Return values

bool

◆ unref()

cache::unref ( $data )

protectedinherited

Removes references where required.

Parameters

stdClass | array $data

Return values

mixed What ever was put in but without any references.

◆ use_static_acceleration()

cache_session::use_static_acceleration ( )

protected

The session loader never uses static acceleration.

Instead it stores things in the static $session variable. Shared between all session loaders.

Return values

bool

Reimplemented from cache.

Member Data Documentation

◆ $now

int cache::$now

staticprotectedinherited

We need a timestamp to use within the cache API.

This stamp needs to be used for all ttl and time based operations to ensure that we don't end up with timing issues.

◆ $purgetoken

string cache::$purgetoken

staticprotectedinherited

A purge token used to distinguish between multiple cache purges in the same second.

This is in the format <microtime>-<random string>.

◆ $storetype

strubg cache::$storetype = 'unknown'

protectedinherited

Gets set to the class name of the store during initialisation.

This is used several times in the cache class internally and having it here helps speed up processing.

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

cache/classes/loaders.php

Public Member Functions

Static Public Member Functions

Public Attributes

Protected Member Functions

Protected Attributes

Static Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ __construct()

Member Function Documentation

◆ compare_purge_tokens()

◆ deep_clone()

◆ delete()

◆ delete_from_persist_cache()

◆ delete_many()

◆ get()

◆ get_datasource()

◆ get_definition()

◆ get_from_persist_cache()

◆ get_key_prefix()

◆ get_loader()

◆ get_many()

◆ get_purge_token()

◆ get_store()

◆ handle_invalidation_events()

◆ has() [1/2]

◆ has() [2/2]

◆ has_a_ttl()

◆ has_all()

◆ has_any()

◆ is_in_persist_cache()

◆ is_using_persist_cache()

◆ make()

◆ make_from_params()

◆ now()

◆ parse_key()

◆ purge()

◆ purge_current_user()

◆ requires_serialisation()

◆ set()

◆ set_data_source()

◆ set_identifiers()

◆ set_in_persist_cache()

◆ set_is_sub_loader()

◆ set_loader()

◆ set_many()

◆ static_acceleration_delete()

◆ static_acceleration_get()

◆ static_acceleration_has()

◆ static_acceleration_set()

◆ store_supports_key_awareness()

◆ store_supports_native_locking()

◆ store_supports_native_ttl()

◆ unref()

◆ use_static_acceleration()

Member Data Documentation

◆ $now

◆ $purgetoken

◆ $storetype