Inheritance diagram for Wikibase\Lib\SimpleCacheWithBagOStuff:

Collaboration diagram for Wikibase\Lib\SimpleCacheWithBagOStuff:

Public Member Functions
	__construct (BagOStuff $inner, string $prefix, string $secret)

	get ( $key, $default=null)
	Fetches a value from the cache.

	set ( $key, $value, $ttl=null)
	Persists data in the cache, uniquely referenced by a key with an optional expiration TTL time.

	delete ( $key)
	Delete an item from the cache by its unique key.

	clear ()
	Wipes clean the entire cache's keys.

	getMultiple ( $keys, $default=null)
	Obtains multiple cache items by their unique keys.

	setMultiple ( $values, $ttl=null)
	Persists a set of key => value pairs in the cache, with an optional TTL.

	deleteMultiple ( $keys)
	Deletes multiple cache items in a single operation.

	has ( $key)
	Determines whether an item is present in the cache.

Private Member Functions
	assertKeysAreValid ( $keys)

	assertKeyIsValid ( $key)

	toArray ( $var)

	toAssociativeArray ( $var)

	normalizeTtl ( $ttl)

	serialize ( $value)

	unserialize ( $string, $default, array $loggingContext)

	decode (string $string, array $loggingContext)
	Decode the data in the cache, which is expected to be a JSON-serialized array of the form `[ 2, "signatureToCheck", "phpSerializedData" ]` (where `2` is a version number that may be increased in future if necessary).

	validate (string $signatureToCheck, string $data, array $loggingContext)
	Validate the signature of the data from the cache.

	safelyUnserialize (string $decodedData, $default, array $loggingContext)
	Unserialize the data once it has been `decoded` and `validated`.

Private Attributes
BagOStuff	$inner

string	$prefix

string	$secret

Detailed Description

Copyright: GPL-2.0-or-later

Constructor & Destructor Documentation

◆ __construct()

Wikibase\Lib\SimpleCacheWithBagOStuff::__construct	(	BagOStuff	$inner,
		string	$prefix,
		string	$secret )

Parameters

BagOStuff	$inner
string	$prefix	While setting and getting all keys will be prefixed with this string
string	$secret	Will be used to create a signature for stored values

Exceptions

InvalidArgumentException If prefix has wrong format or secret is not a string or empty

Member Function Documentation

◆ assertKeyIsValid()

Wikibase\Lib\SimpleCacheWithBagOStuff::assertKeyIsValid ( $key )

private

Exceptions

CacheInvalidArgumentException

◆ assertKeysAreValid()

Wikibase\Lib\SimpleCacheWithBagOStuff::assertKeysAreValid ( $keys )

private

◆ clear()

Wikibase\Lib\SimpleCacheWithBagOStuff::clear ( )

Wipes clean the entire cache's keys.

Returns: bool True on success and false on failure.

◆ decode()

Wikibase\Lib\SimpleCacheWithBagOStuff::decode	(	string	$string,
		array	$loggingContext )

private

Decode the data in the cache, which is expected to be a JSON-serialized array of the form [ 2, "signatureToCheck", "phpSerializedData" ] (where 2 is a version number that may be increased in future if necessary).

Returns: string[]|null If successful, an array with 'signatureToCheck' and 'data'; null means that the data was invalid and an alert was already logged. Keep in mind that a successfully decoded value is not trustworthy until it has been validated.

◆ delete()

Wikibase\Lib\SimpleCacheWithBagOStuff::delete ( $key )

Delete an item from the cache by its unique key.

Parameters

string $key The unique cache key of the item to delete.

Returns: bool True if the item was successfully removed. False if there was an error.

Exceptions

CacheInvalidArgumentException MUST be thrown if the $key string is not a legal value.

◆ deleteMultiple()

Wikibase\Lib\SimpleCacheWithBagOStuff::deleteMultiple ( $keys )

Deletes multiple cache items in a single operation.

Parameters

iterable $keys A list of string-based keys to be deleted.

Returns: bool True if the items were successfully removed. False if there was an error.

Exceptions

CacheInvalidArgumentException MUST be thrown if $keys is neither an array nor a Traversable, or if any of the $keys are not a legal value.

◆ get()

Wikibase\Lib\SimpleCacheWithBagOStuff::get	(		$key,
			$default = null )

Fetches a value from the cache.

Parameters

string	$key	The unique key of this item in the cache.
mixed	$default	Default value to return if the key does not exist.

Returns: mixed The value of the item from the cache, or $default in case of cache miss.

Exceptions

CacheInvalidArgumentException MUST be thrown if the $key string is not a legal value.

◆ getMultiple()

Wikibase\Lib\SimpleCacheWithBagOStuff::getMultiple	(		$keys,
			$default = null )

Obtains multiple cache items by their unique keys.

Parameters

iterable	$keys	A list of keys that can obtained in a single operation.
mixed	$default	Default value to return for keys that do not exist.

Returns: iterable A list of key => value pairs. Cache keys that do not exist or are stale will have $default as value.

Exceptions

CacheInvalidArgumentException MUST be thrown if $keys is neither an array nor a Traversable, or if any of the $keys are not a legal value.

◆ has()

Wikibase\Lib\SimpleCacheWithBagOStuff::has ( $key )

Determines whether an item is present in the cache.

NOTE: It is recommended that has() is only to be used for cache warming type purposes and not to be used within your live applications operations for get/set, as this method is subject to a race condition where your has() will return true and immediately after, another script can remove it making the state of your app out of date.

Parameters

string $key The cache item key.

Returns: bool

Exceptions

CacheInvalidArgumentException MUST be thrown if the $key string is not a legal value.

◆ normalizeTtl()

Wikibase\Lib\SimpleCacheWithBagOStuff::normalizeTtl ( $ttl )

private

Parameters

null | int | DateInterval $ttl The TTL value of this item. If no value is sent and the driver supports TTL then the library may set a default value for it or let the driver take care of that.

Returns: int Time to live in form of seconds from now

Exceptions

CacheInvalidArgumentException

◆ safelyUnserialize()

Wikibase\Lib\SimpleCacheWithBagOStuff::safelyUnserialize	(	string	$decodedData,
			$default,
		array	$loggingContext )

private

Unserialize the data once it has been decoded and validated.

Even then, we only support unserializing stdClass, no other classes.

Returns: mixed

◆ serialize()

Wikibase\Lib\SimpleCacheWithBagOStuff::serialize ( $value )

private

◆ set()

Wikibase\Lib\SimpleCacheWithBagOStuff::set	(	$key,
		$value,
		$ttl = null )

Persists data in the cache, uniquely referenced by a key with an optional expiration TTL time.

Parameters

string	$key	The key of the item to store.
mixed	$value	The value of the item to store, must be serializable.
null \| int \| DateInterval	$ttl	Optional. The TTL value of this item. If no value is sent and the driver supports TTL then the library may set a default value for it or let the driver take care of that.

Returns: bool True on success and false on failure.

Exceptions

CacheInvalidArgumentException MUST be thrown if the $key string is not a legal value.

◆ setMultiple()

Wikibase\Lib\SimpleCacheWithBagOStuff::setMultiple	(		$values,
			$ttl = null )

Persists a set of key => value pairs in the cache, with an optional TTL.

Parameters

iterable	$values	A list of key => value pairs for a multiple-set operation.
null \| int \| DateInterval	$ttl	Optional. The TTL value of this item. If no value is sent and the driver supports TTL then the library may set a default value for it or let the driver take care of that.

Returns: bool True on success and false on failure.

Exceptions

CacheInvalidArgumentException MUST be thrown if $values is neither an array nor a Traversable, or if any of the $values are not a legal value.

◆ toArray()

Wikibase\Lib\SimpleCacheWithBagOStuff::toArray ( $var )

private

Parameters

mixed $var the object to turn to array

Returns: array

Exceptions

CacheInvalidArgumentException

◆ toAssociativeArray()

Wikibase\Lib\SimpleCacheWithBagOStuff::toAssociativeArray ( $var )

private

Parameters

mixed $var the object to turn to associative array

Returns: array

Exceptions

CacheInvalidArgumentException

◆ unserialize()

Wikibase\Lib\SimpleCacheWithBagOStuff::unserialize	(		$string,
			$default,
		array	$loggingContext )

private

Parameters

string	$string
mixed	$default
array	$loggingContext

Returns: mixed

Exceptions

Exception

Note: This implementation is so complicated because we cannot use PHP serialization due to the possibility of Object Injection attack.

See also: https://phabricator.wikimedia.org/T161647; https://secure.php.net/manual/en/function.unserialize.php; https://www.owasp.org/index.php/PHP_Object_Injection

◆ validate()

Wikibase\Lib\SimpleCacheWithBagOStuff::validate	(	string	$signatureToCheck,
		string	$data,
		array	$loggingContext )

private

Validate the signature of the data from the cache.

Returns: bool Whether the signature is valid or not. In case of an invalid signature, an alert is logged.

Member Data Documentation

◆ $inner

BagOStuff Wikibase\Lib\SimpleCacheWithBagOStuff::$inner

private

◆ $prefix

string Wikibase\Lib\SimpleCacheWithBagOStuff::$prefix

private

◆ $secret

string Wikibase\Lib\SimpleCacheWithBagOStuff::$secret

private

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

lib/includes/SimpleCacheWithBagOStuff.php

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ __construct()

Member Function Documentation

◆ assertKeyIsValid()

◆ assertKeysAreValid()

◆ clear()

◆ decode()

◆ delete()

◆ deleteMultiple()

◆ get()

◆ getMultiple()

◆ has()

◆ normalizeTtl()

◆ safelyUnserialize()

◆ serialize()

◆ set()

◆ setMultiple()

◆ toArray()

◆ toAssociativeArray()

◆ unserialize()

◆ validate()

Member Data Documentation

◆ $inner

◆ $prefix

◆ $secret