1. class
  2. Drupal
  3. \
  4. Core
  5. \
  6. Cache
  7. \
  8. DatabaseBackend

DatabaseBackend

class DatabaseBackend implements CacheBackendInterface (View source)

Defines a default cache implementation.

This is Drupal's default cache implementation. It uses the database to store cached data. Each cache bin corresponds to a database table by the same name.

Constants

DEFAULT_MAX_ROWS

The default maximum number of rows that this cache bin table can store.

This maximum is introduced to ensure that the database is not filled with hundred of thousand of cache entries with gigabytes in size.

Read about how to change it in the @link cache Cache API topic. @endlink
MAXIMUM_NONE

-1 means infinite allows numbers of rows for the cache backend.

Properties

protected int $maxRows

The maximum number of rows that this cache bin table is allowed to store.
protected string $bin
protected Connection $connection

The database connection.
protected CacheTagsChecksumInterface $checksumProvider

The cache tags checksum provider.

Methods

__construct(Connection $connection, CacheTagsChecksumInterface $checksum_provider, string $bin, int $max_rows = NULL)

Constructs a DatabaseBackend object.

object|false
get(string $cid, bool $allow_invalid = FALSE)

Returns data from the persistent cache.

array
getMultiple(array $cids, bool $allow_invalid = FALSE)

Returns data from the persistent cache when given an array of cache IDs.

mixed|false
prepareItem(object $cache, bool $allow_invalid)

Prepares a cached item.

set(string $cid, mixed $data, int $expire = Cache::PERMANENT, array $tags = [])

Stores data in the persistent cache.

setMultiple(array $items)

Store multiple items in the persistent cache.

doSetMultiple(array $items)

Stores multiple items in the persistent cache.

delete(string $cid)

Deletes an item from the cache.

deleteMultiple(array $cids)

Deletes multiple items from the cache.

deleteAll()

Deletes all cache items in a bin.

invalidate(string $cid)

Marks a cache item as invalid.

invalidateMultiple(array $cids)

Marks cache items as invalid.

invalidateAll()

Marks all cache items as invalid.

garbageCollection()

Performs garbage collection on a cache bin.

removeBin()

Remove a cache bin.

ensureBinExists()

Check if the cache bin exists and create it if not.

catchException(Exception $e, string|null $table_name = NULL)

Act on an exception when cache might be stale.

string
normalizeCid(string $cid)

Normalizes a cache ID in order to comply with database limitations.

schemaDefinition()

Defines the schema for the {cache_*} bin tables.

int
getMaxRows()

The maximum number of rows that this cache bin table is allowed to store.

Details

at line 77
__construct(Connection $connection, CacheTagsChecksumInterface $checksum_provider, string $bin, int $max_rows = NULL)

Constructs a DatabaseBackend object.

Parameters

Connection $connection

The database connection.
CacheTagsChecksumInterface $checksum_provider

The cache tags checksum provider.
string $bin

The cache bin for which the object is created.
int $max_rows

(optional) The maximum number of rows that are allowed in this cache bin table.

at line 90
object|false get(string $cid, bool $allow_invalid = FALSE)

Returns data from the persistent cache.

Parameters

string $cid

The cache ID of the data to retrieve.
bool $allow_invalid

(optional) If TRUE, a cache item may be returned even if it is expired or has been invalidated. Such items may sometimes be preferred, if the alternative is recalculating the value stored in the cache, especially if another concurrent request is already recalculating the same value. The "valid" property of the returned object indicates whether the item is valid or not. Defaults to FALSE.

Return Value

object|false

The cache item or FALSE on failure.

at line 99
array getMultiple(array $cids, bool $allow_invalid = FALSE)

Returns data from the persistent cache when given an array of cache IDs.

Parameters

array $cids

An array of cache IDs for the data to retrieve. This is passed by reference, and will have the IDs successfully returned from cache removed.
bool $allow_invalid

(optional) If TRUE, cache items may be returned even if they have expired or been invalidated. Such items may sometimes be preferred, if the alternative is recalculating the value stored in the cache, especially if another concurrent thread is already recalculating the same value. The "valid" property of the returned objects indicates whether the items are valid or not. Defaults to FALSE.

Return Value

array

An array of cache item objects indexed by cache ID.

at line 146
protected mixed|false prepareItem(object $cache, bool $allow_invalid)

Prepares a cached item.

Checks that items are either permanent or did not expire, and unserializes data as appropriate.

Parameters

object $cache

An item loaded from self::get() or self::getMultiple().
bool $allow_invalid

If FALSE, the method returns FALSE if the cache item is not valid.

Return Value

mixed|false

The item with data unserialized as appropriate and a property indicating whether the item is valid, or FALSE if there is no valid item to load.

at line 176
set(string $cid, mixed $data, int $expire = Cache::PERMANENT, array $tags = [])

Stores data in the persistent cache.

Core cache implementations set the created time on cache item with microtime(TRUE) rather than REQUEST_TIME_FLOAT, because the created time of cache items should match when they are created, not when the request started. Apart from being more accurate, this increases the chance an item will legitimately be considered valid.

Parameters

string $cid

The cache ID of the data to store.
mixed $data

The data to store in the cache. Some storage engines only allow objects up to a maximum of 1MB in size to be stored by default. When caching large arrays or similar, take care to ensure $data does not exceed this size.
int $expire

One of the following values:

  • CacheBackendInterface::CACHE_PERMANENT: Indicates that the item should not be removed unless it is deleted explicitly.
  • A Unix timestamp: Indicates that the item will be considered invalid after this time, i.e. it will not be returned by get() unless $allow_invalid has been set to TRUE. When the item has expired, it may be permanently deleted by the garbage collector at any time.
array $tags

An array of tags to be stored with the cache item. These should normally identify objects used to build the cache item, which should trigger cache invalidation when updated. For example if a cached item represents a node, both the node ID and the author's user ID might be passed in as tags. For example ['node:123', 'node:456', 'user:789'].

at line 189
setMultiple(array $items)

Store multiple items in the persistent cache.

Parameters

array $items

An array of cache items, keyed by cid. In the form: @code $items = array( $cid => array( // Required, will be automatically serialized if not a string. 'data' => $data, // Optional, defaults to CacheBackendInterface::CACHE_PERMANENT. 'expire' => CacheBackendInterface::CACHE_PERMANENT, // (optional) The cache tags for this item, see CacheBackendInterface::set(). 'tags' => array(), ), ); @endcode

at line 217
protected doSetMultiple(array $items)

Stores multiple items in the persistent cache.

Parameters

array $items

An array of cache items, keyed by cid.

See also

CacheBackendInterface::setMultiple

at line 279
delete(string $cid)

Deletes an item from the cache.

If the cache item is being deleted because it is no longer "fresh", you may consider using invalidate() instead. This allows callers to retrieve the invalid item by calling get() with $allow_invalid set to TRUE. In some cases an invalid item may be acceptable rather than having to rebuild the cache.

Parameters

string $cid

The cache ID to delete.

at line 286
deleteMultiple(array $cids)

Deletes multiple items from the cache.

If the cache items are being deleted because they are no longer "fresh", you may consider using invalidateMultiple() instead. This allows callers to retrieve the invalid items by calling get() with $allow_invalid set to TRUE. In some cases an invalid item may be acceptable rather than having to rebuild the cache.

Parameters

array $cids

An array of cache IDs to delete.

at line 309
deleteAll()

Deletes all cache items in a bin.

at line 326
invalidate(string $cid)

Marks a cache item as invalid.

Invalid items may be returned in later calls to get(), if the $allow_invalid argument is TRUE.

Parameters

string $cid

The cache ID to invalidate.

at line 333
invalidateMultiple(array $cids)

Marks cache items as invalid.

Invalid items may be returned in later calls to get(), if the $allow_invalid argument is TRUE.

Parameters

array $cids

An array of cache IDs to invalidate.

at line 352
invalidateAll()

Marks all cache items as invalid.

Invalid items may be returned in later calls to get(), if the $allow_invalid argument is TRUE.

at line 366
garbageCollection()

Performs garbage collection on a cache bin.

The backend may choose to delete expired or invalidated items.

at line 399
removeBin()

Remove a cache bin.

at line 411
protected ensureBinExists()

Check if the cache bin exists and create it if not.

at line 443
protected catchException(Exception $e, string|null $table_name = NULL)

Act on an exception when cache might be stale.

If the table does not yet exist, that's fine, but if the table exists and yet the query failed, then the cache is stale and the exception needs to propagate.

Parameters

Exception $e

The exception.
string|null $table_name

The table name. Defaults to $this->bin.

Exceptions

Exception

at line 458
protected string normalizeCid(string $cid)

Normalizes a cache ID in order to comply with database limitations.

Parameters

string $cid

The passed in cache ID.

Return Value

string

An ASCII-encoded cache ID that is at most 255 characters long.

at line 478
schemaDefinition()

internal  
 

Defines the schema for the {cache_*} bin tables.

at line 544
int getMaxRows()

The maximum number of rows that this cache bin table is allowed to store.

Return Value

int