cachestore_file Class Reference

The file store class. More...

Inheritance diagram for cachestore_file:

Public Member Functions
	__construct ($name, array $configuration=array())
	Constructs the store instance.
	acquire_lock ($key, $ownerid)
	Use lock factory to acquire a lock.
	cache_size_details (int $samplekeys=50)
	Gets total size for a specific cache.
	check_lock_state ($key, $ownerid)
	Use lock factory to determine the lock state.
	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.
	find_all ()
	Finds all of the keys being used by this cache store instance.
	find_by_prefix ($prefix)
	Finds all of the keys whose keys start with the given prefix.
	get ($key)
	Retrieves an item from the cache store given its key.
	get_last_io_bytes ()
	Gets bytes read by last get() or get_many(), or written by set() or set_many().
	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.
	has ($key)
	Checks if the store has a record for the given key and returns true if so.
	has_all (array $keys)
	Returns true if the store contains records for all of the given keys.
	has_any (array $keys)
	Returns true if the store contains records for any of the given keys.
	initialise (cache_definition $definition)
	Initialises the cache.
	instance_created ()
	Performs any necessary operation when the file store instance has been created.
	instance_deleted ()
	Performs any necessary clean up when the file store instance is being deleted.
	is_initialised ()
	Returns true once this instance has been initialised.
	is_ready ()
	Returns true if this store instance is ready to be used.
	is_searchable ()
	Returns true if the store instance is searchable.
	my_name ()
	Returns the name of this instance.
	purge ()
	Purges the cache definition deleting all the items within it.
	release_lock ($key, $ownerid)
	Use lock factory to release a lock.
	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 total size for the directory used by the cache store.
	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 false as this store does not support multiple identifiers.
	supports_native_ttl ()
	Returns true if the store instance supports native ttl.

Static Public Member Functions
static	are_requirements_met ()
	Returns true if the store requirements are met.
static	can_add_instance ()
	Returns true if the user can add an instance of the store plugin.
static	config_get_configuration_array ($data)
	Given the data from the add instance form this function creates a configuration array.
static	config_set_edit_form_data (moodleform $editform, array $config)
	Allows the cache store to set its data against the edit form before it is shown to the user.
static	get_supported_features (array $configuration=array())
	Returns the supported features as a combined int.
static	get_supported_modes (array $configuration=array())
	Returns the supported modes as a combined int.
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)
	Returns true if the given mode is supported by this store.
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.

Protected Member Functions
	ensure_path_exists ()
	Checks to make sure that the path for the file cache exists.
	file_path_for_key ($key, $create=false)
	Returns the file path to use for the given key.
	glob_keys_pattern ($prefix='')
	Gets a pattern suitable for use with glob to find all keys in the cache.
	prep_data_after_read ($data, $path)
	Prepares the data it has been read from the cache.
	prep_data_before_save ($data)
	Prepares data to be stored in a file.
	prescan_keys ()
	Pre-scan the cache to see which keys are present.
	purge_all_definitions ()
	Purges all the cache definitions deleting all items within them.
	write_file ($file, $content)
	Writes your madness to a file.

Protected Attributes
bool	$asyncpurge = false
	Set to true if new cache revision directory needs to be created.
bool	$autocreate = false
	Set to true when the path should be automatically created if it does not yet exist.
bool	$custompath = false
	Set to true if a custom path is being used.
cache_definition	$definition
	The cache definition this instance has been initialised with.
string	$filestorepath = false
	The path in which definition specific sub directories will be created for caching.
bool	$isready = false
	True when the store is ready to be initialised.
array	$keys = array()
	An array of keys we are sure about presently.
int	$lastiobytes = 0
	Bytes read or written by last call to set()/get() or set_many()/get_many().
core lock file_lock_factory	$lockfactory = null
	Instance of file_lock_factory configured to create locks in the cache directory.
array	$locks = []
	List of current locks.
int	$lockwait = 60
	Maximum number of seconds to wait for a lock before giving up.
string	$name
	The name of the store.
string	$path = false
	The path used to store files for this store and the definition it was initialised with.
bool	$prescan = false
	Set to true when a prescan has been performed.
bool	$singledirectory = false
	Set to true if we should store files within a single directory.

Detailed Description

The file store class.

Copyright

2012 Sam Hemelryk

License

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

Configuration options path: string: path to the cache directory, if left empty one will be created in the cache directory autocreate: true, false prescan: true, false

Copyright

2012 Sam Hemelryk

License

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

Constructor & Destructor Documentation

__construct()

cachestore_file::__construct	(		$name,
		array	$configuration = array() )

Constructs the store instance.

Noting that this function is not an initialisation. It is used to prepare the store for use. The store will be initialised when required and will be provided with a cache_definition at that time.

Parameters

string	$name
array	$configuration

Reimplemented from cache_store.

Member Function Documentation

acquire_lock()

cachestore_file::acquire_lock	(		$key,
			$ownerid )

Use lock factory to acquire a lock.

Parameters

string	$key	Lock identifier
string	$ownerid	Cache identifier

Return values

bool

Exceptions

cache_exception

Implements cache_is_lockable.

are_requirements_met()

static cachestore_file::are_requirements_met ( )

static

Returns true if the store requirements are met.

Return values

bool

Implements cache_store_interface.

cache_size_details()

cachestore_file::cache_size_details

(

int

$samplekeys = 50

)

Gets total size for a specific cache.

With the file cache we can just look at the directory listing without having to actually load any files, so the $samplekeys parameter is ignored.

Parameters

int

$samplekeys

Unused

Return values

stdClass

Cache details

Reimplemented from cache_store.

can_add_instance()

static cache_store::can_add_instance ( )

staticinherited

Returns true if the user can add an instance of the store plugin.

Return values

bool

Reimplemented in cachestore_dummy, cachestore_session, and cachestore_static.

check_lock_state()

cachestore_file::check_lock_state	(		$key,
			$ownerid )

Use lock factory to determine the lock state.

Parameters

string	$key	Lock identifier
string	$ownerid	Cache identifier

Return values

bool|null

Implements cache_is_lockable.

cleanup()

cache_store::cleanup ( )

inherited

Deprecated

since 2.5

See also

cache_store\instance_deleted()

Reimplemented in cachestore_dummy.

config_get_configuration_array()

static cachestore_file::config_get_configuration_array ( $data )

static

Given the data from the add instance form this function creates a configuration array.

Parameters

stdClass

$data

Return values

array

Implements cache_is_configurable.

config_set_edit_form_data()

static cachestore_file::config_set_edit_form_data ( moodleform $editform, array $config )

static

Allows the cache store to set its data against the edit form before it is shown to the user.

Parameters

moodleform	$editform
array	$config

Implements cache_is_configurable.

create_clone()

cache_store::create_clone ( array $details = array() )

inherited

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.

Parameters

array

$details

An array containing the details of the store from the cache config.

Return values

cache_store

delete()

cachestore_file::delete

(

$key

)

Deletes an item from the cache store.

Parameters

string

$key

The key to delete.

Return values

bool	Returns true if the operation was a success, false otherwise.

Reimplemented from cache_store.

delete_many()

cachestore_file::delete_many

(

array

$keys

)

Deletes several keys from the cache in a single action.

Parameters

array

$keys

The keys to delete

Return values

int	The number of items successfully deleted.

Reimplemented from cache_store.

ensure_path_exists()

cachestore_file::ensure_path_exists ( )

protected

Checks to make sure that the path for the file cache exists.

Return values

bool

Exceptions

coding_exception

estimate_stored_size()

cache_store::estimate_stored_size ( $key, $value )

inherited

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).

Parameters

mixed	$key	Key
mixed	$value	Value

Return values

int	Size in bytes

Reimplemented in cachestore_redis.

file_path_for_key()

cachestore_file::file_path_for_key ( $key, $create = false )

protected

Returns the file path to use for the given key.

Parameters

string	$key	The key to generate a file path for.
bool	$create	If set to the true the directory structure the key requires will be created.

Return values

string

The full path to the file that stores a particular cache key.

find_all()

cachestore_file::find_all

(

)

Finds all of the keys being used by this cache store instance.

Return values

array

Implements cache_is_searchable.

find_by_prefix()

cachestore_file::find_by_prefix

(

$prefix

)

Finds all of the keys whose keys start with the given prefix.

Parameters

string

$prefix

Implements cache_is_searchable.

get()

cachestore_file::get

(

$key

)

Retrieves an item from the cache store given its key.

Parameters

string

$key

The key to retrieve

Return values

mixed

The data that was associated with the key, or false if the key did not exist.

Reimplemented from cache_store.

get_last_io_bytes()

cachestore_file::get_last_io_bytes

(

)

Gets bytes read by last get() or get_many(), or written by set() or set_many().

Return values

int	Bytes read or written

Since

Moodle 4.0

Reimplemented from cache_store.

get_many()

cachestore_file::get_many

(

$keys

)

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.

Parameters

array

$keys

The array of keys to retrieve

Return values

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 from cache_store.

get_supported_features()

static cachestore_file::get_supported_features ( array $configuration = array() )

static

Returns the supported features as a combined int.

Parameters

array

$configuration

Return values

int

Implements cache_store_interface.

get_supported_modes()

static cachestore_file::get_supported_modes ( array $configuration = array() )

static

Returns the supported modes as a combined int.

Parameters

array

$configuration

Return values

int

Implements cache_store_interface.

get_warnings()

cache_store::get_warnings ( )

inherited

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.

Return values

string[]

An array of warning strings from the store instance.

glob_keys_pattern()

cachestore_file::glob_keys_pattern ( $prefix = '' )

protected

Gets a pattern suitable for use with glob to find all keys in the cache.

Parameters

string

$prefix

A prefix to use.

Return values

string

The pattern.

has()

cachestore_file::has

(

$key

)

Checks if the store has a record for the given key and returns true if so.

Parameters

string

$key

Return values

bool

Implements cache_is_key_aware.

has_all()

cachestore_file::has_all

(

array

$keys

)

Returns true if the store contains records for all of the given keys.

Parameters

array

$keys

Return values

bool

Implements cache_is_key_aware.

has_any()

cachestore_file::has_any

(

array

$keys

)

Returns true if the store contains records for any of the given keys.

Parameters

array

$keys

Return values

bool

Implements cache_is_key_aware.

initialise()

cachestore_file::initialise

(

cache_definition

$definition

)

Initialises the cache.

Once this has been done the cache is all set to be used.

Parameters

cache_definition

$definition

Reimplemented from cache_store.

initialise_test_instance()

static cachestore_file::initialise_test_instance ( cache_definition $definition )

static

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.

Parameters

cache_definition

$definition

Return values

cachestore_file

Implements cache_store_interface.

instance_created()

cachestore_file::instance_created

(

)

Performs any necessary operation when the file store instance has been created.

Reimplemented from cache_store.

instance_deleted()

cachestore_file::instance_deleted

(

)

Performs any necessary clean up when the file store instance is being deleted.

1. Purges the cache directory.
2. Deletes the directory we created for the given definition.

Reimplemented from cache_store.

is_initialised()

cachestore_file::is_initialised

(

)

Returns true once this instance has been initialised.

Return values

bool

Reimplemented from cache_store.

is_ready()

cachestore_file::is_ready

(

)

Returns true if this store instance is ready to be used.

Return values

bool

Reimplemented from cache_store.

is_searchable()

cache_store::is_searchable ( )

inherited

Returns true if the store instance is searchable.

Return values

bool

is_supported_mode()

static cachestore_file::is_supported_mode ( $mode )

static

Returns true if the given mode is supported by this store.

Parameters

int

$mode

One of cache_store\MODE_*

Return values

bool

Implements cache_store_interface.

my_name()

cachestore_file::my_name

(

)

Returns the name of this instance.

Return values

string

Reimplemented from cache_store.

prep_data_after_read()

cachestore_file::prep_data_after_read ( $data, $path )

protected

Prepares the data it has been read from the cache.

Undoing what was done in prep_data_before_save.

Parameters

string	$data
string	$path

Return values

mixed

prep_data_before_save()

cachestore_file::prep_data_before_save ( $data )

protected

Prepares data to be stored in a file.

Parameters

mixed

$data

Return values

string

purge()

cachestore_file::purge

(

)

Purges the cache definition deleting all the items within it.

Return values

boolean

True on success. False otherwise.

Reimplemented from cache_store.

purge_all_definitions()

cachestore_file::purge_all_definitions ( )

protected

Purges all the cache definitions deleting all items within them.

Return values

boolean

True on success. False otherwise.

ready_to_be_used_for_testing()

static cache_store::ready_to_be_used_for_testing ( )

staticinherited

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.

Return values

bool

Reimplemented in cachestore_apcu, and cachestore_redis.

release_lock()

cachestore_file::release_lock	(		$key,
			$ownerid )

Use lock factory to release a lock.

Parameters

string	$key	Lock identifier
string	$ownerid	Cache identifier

Return values

bool

Implements cache_is_lockable.

set()

cachestore_file::set	(		$key,
			$data )

Sets an item in the cache given its key and data value.

Parameters

string	$key	The key to use.
mixed	$data	The data to set.

Return values

bool	True if the operation was a success false otherwise.

Reimplemented from cache_store.

set_many()

cachestore_file::set_many

(

array

$keyvaluearray

)

Sets many items in the cache in a single transaction.

Parameters

array

$keyvaluearray

An array of key value pairs. Each item in the array will be an associative array with two keys, 'key' and 'value'.

Return values

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 from cache_store.

store_total_size()

cachestore_file::store_total_size

(

)

Gets total size for the directory used by the cache store.

Return values

int	Total size in bytes

Reimplemented from cache_store.

supports_data_guarantee()

cache_store::supports_data_guarantee ( )

inherited

Returns true if the store instance guarantees data.

Return values

bool

supports_dereferencing_objects()

cache_store::supports_dereferencing_objects ( )

inherited

Returns true if the store automatically dereferences objects.

Return values

bool

supports_multiple_identifiers()

cachestore_file::supports_multiple_identifiers

(

)

Returns false as this store does not support multiple identifiers.

(This optional function is a performance optimisation; it must be consistent with the value from get_supported_features.)

Return values

bool

False

Reimplemented from cache_store.

supports_native_ttl()

cache_store::supports_native_ttl ( )

inherited

Returns true if the store instance supports native ttl.

Return values

bool

unit_test_configuration()

static cachestore_file::unit_test_configuration ( )

static

Generates the appropriate configuration required for unit testing.

Return values

array

Array of unit test configuration data to be used by initialise().

Implements cache_store_interface.

write_file()

cachestore_file::write_file ( $file, $content )

protected

Writes your madness to a file.

There are several things going on in this function to try to ensure what we don't end up with partial writes etc.

1. Files for writing are opened with the mode xb, the file must be created and can not already exist.
2. Renaming, data is written to a temporary file, where it can be verified using md5 and is then renamed.

Parameters

string	$file	Absolute file path
string	$content	The content to write.

Return values

bool

Member Data Documentation

$asyncpurge

bool cachestore_file::$asyncpurge = false

protected

Set to true if new cache revision directory needs to be created.

Old directory will be purged asynchronously via Schedule task.

$lockfactory

core lock file_lock_factory cachestore_file::$lockfactory = null

protected

Instance of file_lock_factory configured to create locks in the cache directory.

$lockfactory

$locks

array cachestore_file::$locks = []

protected

List of current locks.

$locks

$singledirectory

bool cachestore_file::$singledirectory = false

protected

Set to true if we should store files within a single directory.

By default we use a nested structure in order to reduce the chance of conflicts and avoid any file system limitations such as maximum files per directory.

DEREFERENCES_OBJECTS

const cache_store::DEREFERENCES_OBJECTS = 16

inherited

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.

MODE_APPLICATION

const cache_store::MODE_APPLICATION = 1

inherited

Application caches.

These are shared caches.

MODE_REQUEST

const cache_store::MODE_REQUEST = 4

inherited

Request caches.

Static caches really.

MODE_SESSION

const cache_store::MODE_SESSION = 2

inherited

Session caches.

Just access to the PHP session.

---

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

• cache/stores/file/lib.php