annotate core/lib/Drupal/Core/Cache/DatabaseBackend.php @ 19:fa3358dc1485 tip

Add ndrum files
author Chris Cannam
date Wed, 28 Aug 2019 13:14:47 +0100
parents af1871eacc83
children
rev   line source
Chris@0 1 <?php
Chris@0 2
Chris@0 3 namespace Drupal\Core\Cache;
Chris@0 4
Chris@14 5 use Drupal\Component\Assertion\Inspector;
Chris@0 6 use Drupal\Component\Utility\Crypt;
Chris@0 7 use Drupal\Core\Database\Connection;
Chris@0 8 use Drupal\Core\Database\SchemaObjectExistsException;
Chris@0 9
Chris@0 10 /**
Chris@0 11 * Defines a default cache implementation.
Chris@0 12 *
Chris@0 13 * This is Drupal's default cache implementation. It uses the database to store
Chris@0 14 * cached data. Each cache bin corresponds to a database table by the same name.
Chris@0 15 *
Chris@0 16 * @ingroup cache
Chris@0 17 */
Chris@0 18 class DatabaseBackend implements CacheBackendInterface {
Chris@0 19
Chris@0 20 /**
Chris@0 21 * The default maximum number of rows that this cache bin table can store.
Chris@0 22 *
Chris@0 23 * This maximum is introduced to ensure that the database is not filled with
Chris@0 24 * hundred of thousand of cache entries with gigabytes in size.
Chris@0 25 *
Chris@0 26 * Read about how to change it in the @link cache Cache API topic. @endlink
Chris@0 27 */
Chris@0 28 const DEFAULT_MAX_ROWS = 5000;
Chris@0 29
Chris@0 30 /**
Chris@0 31 * -1 means infinite allows numbers of rows for the cache backend.
Chris@0 32 */
Chris@0 33 const MAXIMUM_NONE = -1;
Chris@0 34
Chris@0 35 /**
Chris@0 36 * The maximum number of rows that this cache bin table is allowed to store.
Chris@0 37 *
Chris@0 38 * @see ::MAXIMUM_NONE
Chris@0 39 *
Chris@0 40 * @var int
Chris@0 41 */
Chris@0 42 protected $maxRows;
Chris@0 43
Chris@0 44 /**
Chris@0 45 * @var string
Chris@0 46 */
Chris@0 47 protected $bin;
Chris@0 48
Chris@0 49
Chris@0 50 /**
Chris@0 51 * The database connection.
Chris@0 52 *
Chris@0 53 * @var \Drupal\Core\Database\Connection
Chris@0 54 */
Chris@0 55 protected $connection;
Chris@0 56
Chris@0 57 /**
Chris@0 58 * The cache tags checksum provider.
Chris@0 59 *
Chris@0 60 * @var \Drupal\Core\Cache\CacheTagsChecksumInterface
Chris@0 61 */
Chris@0 62 protected $checksumProvider;
Chris@0 63
Chris@0 64 /**
Chris@0 65 * Constructs a DatabaseBackend object.
Chris@0 66 *
Chris@0 67 * @param \Drupal\Core\Database\Connection $connection
Chris@0 68 * The database connection.
Chris@0 69 * @param \Drupal\Core\Cache\CacheTagsChecksumInterface $checksum_provider
Chris@0 70 * The cache tags checksum provider.
Chris@0 71 * @param string $bin
Chris@0 72 * The cache bin for which the object is created.
Chris@0 73 * @param int $max_rows
Chris@0 74 * (optional) The maximum number of rows that are allowed in this cache bin
Chris@0 75 * table.
Chris@0 76 */
Chris@0 77 public function __construct(Connection $connection, CacheTagsChecksumInterface $checksum_provider, $bin, $max_rows = NULL) {
Chris@0 78 // All cache tables should be prefixed with 'cache_'.
Chris@0 79 $bin = 'cache_' . $bin;
Chris@0 80
Chris@0 81 $this->bin = $bin;
Chris@0 82 $this->connection = $connection;
Chris@0 83 $this->checksumProvider = $checksum_provider;
Chris@0 84 $this->maxRows = $max_rows === NULL ? static::DEFAULT_MAX_ROWS : $max_rows;
Chris@0 85 }
Chris@0 86
Chris@0 87 /**
Chris@0 88 * {@inheritdoc}
Chris@0 89 */
Chris@0 90 public function get($cid, $allow_invalid = FALSE) {
Chris@0 91 $cids = [$cid];
Chris@0 92 $cache = $this->getMultiple($cids, $allow_invalid);
Chris@0 93 return reset($cache);
Chris@0 94 }
Chris@0 95
Chris@0 96 /**
Chris@0 97 * {@inheritdoc}
Chris@0 98 */
Chris@0 99 public function getMultiple(&$cids, $allow_invalid = FALSE) {
Chris@0 100 $cid_mapping = [];
Chris@0 101 foreach ($cids as $cid) {
Chris@0 102 $cid_mapping[$this->normalizeCid($cid)] = $cid;
Chris@0 103 }
Chris@0 104 // When serving cached pages, the overhead of using ::select() was found
Chris@0 105 // to add around 30% overhead to the request. Since $this->bin is a
Chris@0 106 // variable, this means the call to ::query() here uses a concatenated
Chris@0 107 // string. This is highly discouraged under any other circumstances, and
Chris@0 108 // is used here only due to the performance overhead we would incur
Chris@0 109 // otherwise. When serving an uncached page, the overhead of using
Chris@0 110 // ::select() is a much smaller proportion of the request.
Chris@0 111 $result = [];
Chris@0 112 try {
Chris@0 113 $result = $this->connection->query('SELECT cid, data, created, expire, serialized, tags, checksum FROM {' . $this->connection->escapeTable($this->bin) . '} WHERE cid IN ( :cids[] ) ORDER BY cid', [':cids[]' => array_keys($cid_mapping)]);
Chris@0 114 }
Chris@0 115 catch (\Exception $e) {
Chris@0 116 // Nothing to do.
Chris@0 117 }
Chris@0 118 $cache = [];
Chris@0 119 foreach ($result as $item) {
Chris@0 120 // Map the cache ID back to the original.
Chris@0 121 $item->cid = $cid_mapping[$item->cid];
Chris@0 122 $item = $this->prepareItem($item, $allow_invalid);
Chris@0 123 if ($item) {
Chris@0 124 $cache[$item->cid] = $item;
Chris@0 125 }
Chris@0 126 }
Chris@0 127 $cids = array_diff($cids, array_keys($cache));
Chris@0 128 return $cache;
Chris@0 129 }
Chris@0 130
Chris@0 131 /**
Chris@0 132 * Prepares a cached item.
Chris@0 133 *
Chris@0 134 * Checks that items are either permanent or did not expire, and unserializes
Chris@0 135 * data as appropriate.
Chris@0 136 *
Chris@0 137 * @param object $cache
Chris@18 138 * An item loaded from self::get() or self::getMultiple().
Chris@0 139 * @param bool $allow_invalid
Chris@0 140 * If FALSE, the method returns FALSE if the cache item is not valid.
Chris@0 141 *
Chris@0 142 * @return mixed|false
Chris@0 143 * The item with data unserialized as appropriate and a property indicating
Chris@0 144 * whether the item is valid, or FALSE if there is no valid item to load.
Chris@0 145 */
Chris@0 146 protected function prepareItem($cache, $allow_invalid) {
Chris@0 147 if (!isset($cache->data)) {
Chris@0 148 return FALSE;
Chris@0 149 }
Chris@0 150
Chris@0 151 $cache->tags = $cache->tags ? explode(' ', $cache->tags) : [];
Chris@0 152
Chris@0 153 // Check expire time.
Chris@0 154 $cache->valid = $cache->expire == Cache::PERMANENT || $cache->expire >= REQUEST_TIME;
Chris@0 155
Chris@0 156 // Check if invalidateTags() has been called with any of the items's tags.
Chris@0 157 if (!$this->checksumProvider->isValid($cache->checksum, $cache->tags)) {
Chris@0 158 $cache->valid = FALSE;
Chris@0 159 }
Chris@0 160
Chris@0 161 if (!$allow_invalid && !$cache->valid) {
Chris@0 162 return FALSE;
Chris@0 163 }
Chris@0 164
Chris@0 165 // Unserialize and return the cached data.
Chris@0 166 if ($cache->serialized) {
Chris@0 167 $cache->data = unserialize($cache->data);
Chris@0 168 }
Chris@0 169
Chris@0 170 return $cache;
Chris@0 171 }
Chris@0 172
Chris@0 173 /**
Chris@0 174 * {@inheritdoc}
Chris@0 175 */
Chris@0 176 public function set($cid, $data, $expire = Cache::PERMANENT, array $tags = []) {
Chris@0 177 $this->setMultiple([
Chris@0 178 $cid => [
Chris@0 179 'data' => $data,
Chris@0 180 'expire' => $expire,
Chris@0 181 'tags' => $tags,
Chris@0 182 ],
Chris@0 183 ]);
Chris@0 184 }
Chris@0 185
Chris@0 186 /**
Chris@0 187 * {@inheritdoc}
Chris@0 188 */
Chris@0 189 public function setMultiple(array $items) {
Chris@0 190 $try_again = FALSE;
Chris@0 191 try {
Chris@0 192 // The bin might not yet exist.
Chris@0 193 $this->doSetMultiple($items);
Chris@0 194 }
Chris@0 195 catch (\Exception $e) {
Chris@0 196 // If there was an exception, try to create the bins.
Chris@0 197 if (!$try_again = $this->ensureBinExists()) {
Chris@0 198 // If the exception happened for other reason than the missing bin
Chris@0 199 // table, propagate the exception.
Chris@0 200 throw $e;
Chris@0 201 }
Chris@0 202 }
Chris@0 203 // Now that the bin has been created, try again if necessary.
Chris@0 204 if ($try_again) {
Chris@0 205 $this->doSetMultiple($items);
Chris@0 206 }
Chris@0 207 }
Chris@0 208
Chris@0 209 /**
Chris@0 210 * Stores multiple items in the persistent cache.
Chris@0 211 *
Chris@0 212 * @param array $items
Chris@0 213 * An array of cache items, keyed by cid.
Chris@0 214 *
Chris@0 215 * @see \Drupal\Core\Cache\CacheBackendInterface::setMultiple()
Chris@0 216 */
Chris@0 217 protected function doSetMultiple(array $items) {
Chris@0 218 $values = [];
Chris@0 219
Chris@0 220 foreach ($items as $cid => $item) {
Chris@0 221 $item += [
Chris@0 222 'expire' => CacheBackendInterface::CACHE_PERMANENT,
Chris@0 223 'tags' => [],
Chris@0 224 ];
Chris@0 225
Chris@14 226 assert(Inspector::assertAllStrings($item['tags']), 'Cache Tags must be strings.');
Chris@0 227 $item['tags'] = array_unique($item['tags']);
Chris@0 228 // Sort the cache tags so that they are stored consistently in the DB.
Chris@0 229 sort($item['tags']);
Chris@0 230
Chris@0 231 $fields = [
Chris@0 232 'cid' => $this->normalizeCid($cid),
Chris@0 233 'expire' => $item['expire'],
Chris@0 234 'created' => round(microtime(TRUE), 3),
Chris@0 235 'tags' => implode(' ', $item['tags']),
Chris@0 236 'checksum' => $this->checksumProvider->getCurrentChecksum($item['tags']),
Chris@0 237 ];
Chris@0 238
Chris@0 239 if (!is_string($item['data'])) {
Chris@0 240 $fields['data'] = serialize($item['data']);
Chris@0 241 $fields['serialized'] = 1;
Chris@0 242 }
Chris@0 243 else {
Chris@0 244 $fields['data'] = $item['data'];
Chris@0 245 $fields['serialized'] = 0;
Chris@0 246 }
Chris@0 247 $values[] = $fields;
Chris@0 248 }
Chris@0 249
Chris@0 250 // Use an upsert query which is atomic and optimized for multiple-row
Chris@0 251 // merges.
Chris@0 252 $query = $this->connection
Chris@0 253 ->upsert($this->bin)
Chris@0 254 ->key('cid')
Chris@0 255 ->fields(['cid', 'expire', 'created', 'tags', 'checksum', 'data', 'serialized']);
Chris@0 256 foreach ($values as $fields) {
Chris@0 257 // Only pass the values since the order of $fields matches the order of
Chris@0 258 // the insert fields. This is a performance optimization to avoid
Chris@0 259 // unnecessary loops within the method.
Chris@0 260 $query->values(array_values($fields));
Chris@0 261 }
Chris@0 262
Chris@0 263 $query->execute();
Chris@0 264 }
Chris@0 265
Chris@0 266 /**
Chris@0 267 * {@inheritdoc}
Chris@0 268 */
Chris@0 269 public function delete($cid) {
Chris@0 270 $this->deleteMultiple([$cid]);
Chris@0 271 }
Chris@0 272
Chris@0 273 /**
Chris@0 274 * {@inheritdoc}
Chris@0 275 */
Chris@0 276 public function deleteMultiple(array $cids) {
Chris@0 277 $cids = array_values(array_map([$this, 'normalizeCid'], $cids));
Chris@0 278 try {
Chris@0 279 // Delete in chunks when a large array is passed.
Chris@0 280 foreach (array_chunk($cids, 1000) as $cids_chunk) {
Chris@0 281 $this->connection->delete($this->bin)
Chris@0 282 ->condition('cid', $cids_chunk, 'IN')
Chris@0 283 ->execute();
Chris@0 284 }
Chris@0 285 }
Chris@0 286 catch (\Exception $e) {
Chris@0 287 // Create the cache table, which will be empty. This fixes cases during
Chris@0 288 // core install where a cache table is cleared before it is set
Chris@0 289 // with {cache_render} and {cache_data}.
Chris@0 290 if (!$this->ensureBinExists()) {
Chris@0 291 $this->catchException($e);
Chris@0 292 }
Chris@0 293 }
Chris@0 294 }
Chris@0 295
Chris@0 296 /**
Chris@0 297 * {@inheritdoc}
Chris@0 298 */
Chris@0 299 public function deleteAll() {
Chris@0 300 try {
Chris@0 301 $this->connection->truncate($this->bin)->execute();
Chris@0 302 }
Chris@0 303 catch (\Exception $e) {
Chris@0 304 // Create the cache table, which will be empty. This fixes cases during
Chris@0 305 // core install where a cache table is cleared before it is set
Chris@0 306 // with {cache_render} and {cache_data}.
Chris@0 307 if (!$this->ensureBinExists()) {
Chris@0 308 $this->catchException($e);
Chris@0 309 }
Chris@0 310 }
Chris@0 311 }
Chris@0 312
Chris@0 313 /**
Chris@0 314 * {@inheritdoc}
Chris@0 315 */
Chris@0 316 public function invalidate($cid) {
Chris@0 317 $this->invalidateMultiple([$cid]);
Chris@0 318 }
Chris@0 319
Chris@0 320 /**
Chris@0 321 * {@inheritdoc}
Chris@0 322 */
Chris@0 323 public function invalidateMultiple(array $cids) {
Chris@0 324 $cids = array_values(array_map([$this, 'normalizeCid'], $cids));
Chris@0 325 try {
Chris@0 326 // Update in chunks when a large array is passed.
Chris@0 327 foreach (array_chunk($cids, 1000) as $cids_chunk) {
Chris@0 328 $this->connection->update($this->bin)
Chris@0 329 ->fields(['expire' => REQUEST_TIME - 1])
Chris@0 330 ->condition('cid', $cids_chunk, 'IN')
Chris@0 331 ->execute();
Chris@0 332 }
Chris@0 333 }
Chris@0 334 catch (\Exception $e) {
Chris@0 335 $this->catchException($e);
Chris@0 336 }
Chris@0 337 }
Chris@0 338
Chris@0 339 /**
Chris@0 340 * {@inheritdoc}
Chris@0 341 */
Chris@0 342 public function invalidateAll() {
Chris@0 343 try {
Chris@0 344 $this->connection->update($this->bin)
Chris@0 345 ->fields(['expire' => REQUEST_TIME - 1])
Chris@0 346 ->execute();
Chris@0 347 }
Chris@0 348 catch (\Exception $e) {
Chris@0 349 $this->catchException($e);
Chris@0 350 }
Chris@0 351 }
Chris@0 352
Chris@0 353 /**
Chris@0 354 * {@inheritdoc}
Chris@0 355 */
Chris@0 356 public function garbageCollection() {
Chris@0 357 try {
Chris@0 358 // Bounded size cache bin, using FIFO.
Chris@0 359 if ($this->maxRows !== static::MAXIMUM_NONE) {
Chris@0 360 $first_invalid_create_time = $this->connection->select($this->bin)
Chris@0 361 ->fields($this->bin, ['created'])
Chris@0 362 ->orderBy("{$this->bin}.created", 'DESC')
Chris@0 363 ->range($this->maxRows, $this->maxRows + 1)
Chris@0 364 ->execute()
Chris@0 365 ->fetchField();
Chris@0 366
Chris@0 367 if ($first_invalid_create_time) {
Chris@0 368 $this->connection->delete($this->bin)
Chris@0 369 ->condition('created', $first_invalid_create_time, '<=')
Chris@0 370 ->execute();
Chris@0 371 }
Chris@0 372 }
Chris@0 373
Chris@0 374 $this->connection->delete($this->bin)
Chris@0 375 ->condition('expire', Cache::PERMANENT, '<>')
Chris@0 376 ->condition('expire', REQUEST_TIME, '<')
Chris@0 377 ->execute();
Chris@0 378 }
Chris@0 379 catch (\Exception $e) {
Chris@0 380 // If the table does not exist, it surely does not have garbage in it.
Chris@0 381 // If the table exists, the next garbage collection will clean up.
Chris@0 382 // There is nothing to do.
Chris@0 383 }
Chris@0 384 }
Chris@0 385
Chris@0 386 /**
Chris@0 387 * {@inheritdoc}
Chris@0 388 */
Chris@0 389 public function removeBin() {
Chris@0 390 try {
Chris@0 391 $this->connection->schema()->dropTable($this->bin);
Chris@0 392 }
Chris@0 393 catch (\Exception $e) {
Chris@0 394 $this->catchException($e);
Chris@0 395 }
Chris@0 396 }
Chris@0 397
Chris@0 398 /**
Chris@0 399 * Check if the cache bin exists and create it if not.
Chris@0 400 */
Chris@0 401 protected function ensureBinExists() {
Chris@0 402 try {
Chris@0 403 $database_schema = $this->connection->schema();
Chris@0 404 if (!$database_schema->tableExists($this->bin)) {
Chris@0 405 $schema_definition = $this->schemaDefinition();
Chris@0 406 $database_schema->createTable($this->bin, $schema_definition);
Chris@0 407 return TRUE;
Chris@0 408 }
Chris@0 409 }
Chris@0 410 // If another process has already created the cache table, attempting to
Chris@0 411 // recreate it will throw an exception. In this case just catch the
Chris@0 412 // exception and do nothing.
Chris@0 413 catch (SchemaObjectExistsException $e) {
Chris@0 414 return TRUE;
Chris@0 415 }
Chris@0 416 return FALSE;
Chris@0 417 }
Chris@0 418
Chris@0 419 /**
Chris@0 420 * Act on an exception when cache might be stale.
Chris@0 421 *
Chris@0 422 * If the table does not yet exist, that's fine, but if the table exists and
Chris@0 423 * yet the query failed, then the cache is stale and the exception needs to
Chris@0 424 * propagate.
Chris@0 425 *
Chris@0 426 * @param $e
Chris@0 427 * The exception.
Chris@0 428 * @param string|null $table_name
Chris@0 429 * The table name. Defaults to $this->bin.
Chris@0 430 *
Chris@0 431 * @throws \Exception
Chris@0 432 */
Chris@0 433 protected function catchException(\Exception $e, $table_name = NULL) {
Chris@0 434 if ($this->connection->schema()->tableExists($table_name ?: $this->bin)) {
Chris@0 435 throw $e;
Chris@0 436 }
Chris@0 437 }
Chris@0 438
Chris@0 439 /**
Chris@0 440 * Normalizes a cache ID in order to comply with database limitations.
Chris@0 441 *
Chris@0 442 * @param string $cid
Chris@0 443 * The passed in cache ID.
Chris@0 444 *
Chris@0 445 * @return string
Chris@0 446 * An ASCII-encoded cache ID that is at most 255 characters long.
Chris@0 447 */
Chris@0 448 protected function normalizeCid($cid) {
Chris@0 449 // Nothing to do if the ID is a US ASCII string of 255 characters or less.
Chris@0 450 $cid_is_ascii = mb_check_encoding($cid, 'ASCII');
Chris@0 451 if (strlen($cid) <= 255 && $cid_is_ascii) {
Chris@0 452 return $cid;
Chris@0 453 }
Chris@0 454 // Return a string that uses as much as possible of the original cache ID
Chris@0 455 // with the hash appended.
Chris@0 456 $hash = Crypt::hashBase64($cid);
Chris@0 457 if (!$cid_is_ascii) {
Chris@0 458 return $hash;
Chris@0 459 }
Chris@0 460 return substr($cid, 0, 255 - strlen($hash)) . $hash;
Chris@0 461 }
Chris@0 462
Chris@0 463 /**
Chris@0 464 * Defines the schema for the {cache_*} bin tables.
Chris@0 465 *
Chris@0 466 * @internal
Chris@0 467 */
Chris@0 468 public function schemaDefinition() {
Chris@0 469 $schema = [
Chris@0 470 'description' => 'Storage for the cache API.',
Chris@0 471 'fields' => [
Chris@0 472 'cid' => [
Chris@0 473 'description' => 'Primary Key: Unique cache ID.',
Chris@0 474 'type' => 'varchar_ascii',
Chris@0 475 'length' => 255,
Chris@0 476 'not null' => TRUE,
Chris@0 477 'default' => '',
Chris@0 478 'binary' => TRUE,
Chris@0 479 ],
Chris@0 480 'data' => [
Chris@0 481 'description' => 'A collection of data to cache.',
Chris@0 482 'type' => 'blob',
Chris@0 483 'not null' => FALSE,
Chris@0 484 'size' => 'big',
Chris@0 485 ],
Chris@0 486 'expire' => [
Chris@0 487 'description' => 'A Unix timestamp indicating when the cache entry should expire, or ' . Cache::PERMANENT . ' for never.',
Chris@0 488 'type' => 'int',
Chris@0 489 'not null' => TRUE,
Chris@0 490 'default' => 0,
Chris@0 491 ],
Chris@0 492 'created' => [
Chris@0 493 'description' => 'A timestamp with millisecond precision indicating when the cache entry was created.',
Chris@0 494 'type' => 'numeric',
Chris@0 495 'precision' => 14,
Chris@0 496 'scale' => 3,
Chris@0 497 'not null' => TRUE,
Chris@0 498 'default' => 0,
Chris@0 499 ],
Chris@0 500 'serialized' => [
Chris@0 501 'description' => 'A flag to indicate whether content is serialized (1) or not (0).',
Chris@0 502 'type' => 'int',
Chris@0 503 'size' => 'small',
Chris@0 504 'not null' => TRUE,
Chris@0 505 'default' => 0,
Chris@0 506 ],
Chris@0 507 'tags' => [
Chris@0 508 'description' => 'Space-separated list of cache tags for this entry.',
Chris@0 509 'type' => 'text',
Chris@0 510 'size' => 'big',
Chris@0 511 'not null' => FALSE,
Chris@0 512 ],
Chris@0 513 'checksum' => [
Chris@0 514 'description' => 'The tag invalidation checksum when this entry was saved.',
Chris@0 515 'type' => 'varchar_ascii',
Chris@0 516 'length' => 255,
Chris@0 517 'not null' => TRUE,
Chris@0 518 ],
Chris@0 519 ],
Chris@0 520 'indexes' => [
Chris@0 521 'expire' => ['expire'],
Chris@0 522 'created' => ['created'],
Chris@0 523 ],
Chris@0 524 'primary key' => ['cid'],
Chris@0 525 ];
Chris@0 526 return $schema;
Chris@0 527 }
Chris@0 528
Chris@0 529 /**
Chris@0 530 * The maximum number of rows that this cache bin table is allowed to store.
Chris@0 531 *
Chris@0 532 * @return int
Chris@0 533 */
Chris@0 534 public function getMaxRows() {
Chris@0 535 return $this->maxRows;
Chris@0 536 }
Chris@0 537
Chris@0 538 }