/drupal7/includes/cache.inc - Annoter - Club Drupal - Forge Centrale Marseille

root / drupal7 / includes / cache.inc @ 52534e1f

-ad3d82
+<?php
 /**
  * @file
  * Functions and interfaces for cache handling.
  */
 /**
  * Gets the cache object for a cache bin.
+ *
  * By default, this returns an instance of the DrupalDatabaseCache class.
  * Classes implementing DrupalCacheInterface can register themselves both as a
  * default implementation and for specific bins.
+ *
  * @param $bin
  *   The cache bin for which the cache object should be returned.
-db59d
+            Assos Assos
-ad3d82
+ * @return DrupalCacheInterface
  *   The cache object associated with the specified bin.
+ *
  * @see DrupalCacheInterface
  */
 function _cache_get_object($bin) {
   // We do not use drupal_static() here because we do not want to change the
   // storage of a cache bin mid-request.
   static $cache_objects;
   if (!isset($cache_objects[$bin])) {
     $class = variable_get('cache_class_' . $bin);
     if (!isset($class)) {
       $class = variable_get('cache_default_class', 'DrupalDatabaseCache');
+    }
     $cache_objects[$bin] = new $class($bin);
+  }
   return $cache_objects[$bin];
+}
 /**
  * Returns data from the persistent cache.
+ *
  * Data may be stored as either plain text or as serialized data. cache_get
  * will automatically return unserialized objects and arrays.
+ *
  * @param $cid
  *   The cache ID of the data to retrieve.
  * @param $bin
  *   The cache bin to store the data in. Valid core values are 'cache_block',
  *   'cache_bootstrap', 'cache_field', 'cache_filter', 'cache_form',
  *   'cache_menu', 'cache_page', 'cache_path', 'cache_update' or 'cache' for
  *   the default cache.
+ *
  * @return
  *   The cache or FALSE on failure.
+ *
  * @see cache_set()
  */
 function cache_get($cid, $bin = 'cache') {
   return _cache_get_object($bin)->get($cid);
+}
 /**
  * Returns data from the persistent cache when given an array of cache IDs.
+ *
  * @param $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.
  * @param $bin
  *   The cache bin where the data is stored.
+ *
  * @return
  *   An array of the items successfully returned from cache indexed by cid.
  */
 function cache_get_multiple(array &$cids, $bin = 'cache') {
   return _cache_get_object($bin)->getMultiple($cids);
+}
 /**
  * Stores data in the persistent cache.
+ *
  * The persistent cache is split up into several cache bins. In the default
  * cache implementation, each cache bin corresponds to a database table by the
  * same name. Other implementations might want to store several bins in data
  * structures that get flushed together. While it is not a problem for most
  * cache bins if the entries in them are flushed before their expire time, some
  * might break functionality or are extremely expensive to recalculate. The
  * other bins are expired automatically by core. Contributed modules can add
  * additional bins and get them expired automatically by implementing
  * hook_flush_caches().
+ *
  * The reasons for having several bins are as follows:
  * - Smaller bins mean smaller database tables and allow for faster selects and
  *   inserts.
  * - We try to put fast changing cache items and rather static ones into
  *   different bins. The effect is that only the fast changing bins will need a
  *   lot of writes to disk. The more static bins will also be better cacheable
  *   with MySQL's query cache.
+ *
  * @param $cid
  *   The cache ID of the data to store.
  * @param $data
  *   The data to store in the cache. Complex data types will be automatically
  *   serialized before insertion. Strings will be stored as plain text and are
-            b4adf10d
+ *   not serialized. 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.
-ad3d82
+ * @param $bin
-            b4adf10d
+ *   (optional) The cache bin to store the data in. Valid core values are:
-ad3d82
+ *   - cache: (default) Generic cache storage bin (used for theme registry,
  *     locale date, list of simpletest tests, etc.).
  *   - cache_block: Stores the content of various blocks.
  *   - cache_bootstrap: Stores the class registry, the system list of modules,
  *     the list of which modules implement which hooks, and the Drupal variable
  *     list.
  *   - cache_field: Stores the field data belonging to a given object.
  *   - cache_filter: Stores filtered pieces of content.
  *   - cache_form: Stores multistep forms. Flushing this bin means that some
  *     forms displayed to users lose their state and the data already submitted
  *     to them. This bin should not be flushed before its expired time.
  *   - cache_menu: Stores the structure of visible navigation menus per page.
  *   - cache_page: Stores generated pages for anonymous users. It is flushed
  *     very often, whenever a page changes, at least for every node and comment
  *     submission. This is the only bin affected by the page cache setting on
  *     the administrator panel.
  *   - cache_path: Stores the system paths that have an alias.
  * @param $expire
-            c9e51f47
+ *   (optional) Controls the maximum lifetime of this cache entry. Note that
  *   caches might be subject to clearing at any time, so this setting does not
  *   guarantee a minimum lifetime. With this in mind, the cache should not be
  *   used for data that must be kept during a cache clear, like sessions.
+ *
  *   Use one of the following values:
-ad3d82
+ *   - CACHE_PERMANENT: Indicates that the item should never be removed unless
  *     explicitly told to using cache_clear_all() with a cache ID.
  *   - CACHE_TEMPORARY: Indicates that the item should be removed at the next
  *     general cache wipe.
  *   - A Unix timestamp: Indicates that the item should be kept at least until
  *     the given time, after which it behaves like CACHE_TEMPORARY.
+ *
  * @see _update_cache_set()
  * @see cache_get()
  */
 function cache_set($cid, $data, $bin = 'cache', $expire = CACHE_PERMANENT) {
   return _cache_get_object($bin)->set($cid, $data, $expire);
+}
 /**
  * Expires data from the cache.
+ *
  * If called with the arguments $cid and $bin set to NULL or omitted, then
  * expirable entries will be cleared from the cache_page and cache_block bins,
  * and the $wildcard argument is ignored.
+ *
  * @param $cid
  *   If set, the cache ID or an array of cache IDs. Otherwise, all cache entries
  *   that can expire are deleted. The $wildcard argument will be ignored if set
  *   to NULL.
  * @param $bin
  *   If set, the cache bin to delete from. Mandatory argument if $cid is set.
  * @param $wildcard
  *   If TRUE, the $cid argument must contain a string value and cache IDs
  *   starting with $cid are deleted in addition to the exact cache ID specified
  *   by $cid. If $wildcard is TRUE and $cid is '*', the entire cache is emptied.
  */
 function cache_clear_all($cid = NULL, $bin = NULL, $wildcard = FALSE) {
   if (!isset($cid) && !isset($bin)) {
     // Clear the block cache first, so stale data will
     // not end up in the page cache.
     if (module_exists('block')) {
       cache_clear_all(NULL, 'cache_block');
+    }
     cache_clear_all(NULL, 'cache_page');
     return;
+  }
   return _cache_get_object($bin)->clear($cid, $wildcard);
+}
 /**
  * Checks if a cache bin is empty.
+ *
  * A cache bin is considered empty if it does not contain any valid data for any
  * cache ID.
+ *
  * @param $bin
  *   The cache bin to check.
+ *
  * @return
  *   TRUE if the cache bin specified is empty.
  */
 function cache_is_empty($bin) {
   return _cache_get_object($bin)->isEmpty();
+}
 /**
  * Defines an interface for cache implementations.
+ *
  * All cache implementations have to implement this interface.
  * DrupalDatabaseCache provides the default implementation, which can be
  * consulted as an example.
+ *
  * To make Drupal use your implementation for a certain cache bin, you have to
  * set a variable with the name of the cache bin as its key and the name of
  * your class as its value. For example, if your implementation of
  * DrupalCacheInterface was called MyCustomCache, the following line would make
  * Drupal use it for the 'cache_page' bin:
  * @code
  *  variable_set('cache_class_cache_page', 'MyCustomCache');
  * @endcode
+ *
  * Additionally, you can register your cache implementation to be used by
  * default for all cache bins by setting the variable 'cache_default_class' to
  * the name of your implementation of the DrupalCacheInterface, e.g.
  * @code
  *  variable_set('cache_default_class', 'MyCustomCache');
  * @endcode
+ *
  * To implement a completely custom cache bin, use the same variable format:
  * @code
  *  variable_set('cache_class_custom_bin', 'MyCustomCache');
  * @endcode
  * To access your custom cache bin, specify the name of the bin when storing
  * or retrieving cached data:
  * @code
  *  cache_set($cid, $data, 'custom_bin', $expire);
  *  cache_get($cid, 'custom_bin');
  * @endcode
+ *
  * @see _cache_get_object()
  * @see DrupalDatabaseCache
  */
 interface DrupalCacheInterface {
   /**
    * Returns data from the persistent cache.
+   *
    * Data may be stored as either plain text or as serialized data. cache_get()
    * will automatically return unserialized objects and arrays.
+   *
    * @param $cid
    *   The cache ID of the data to retrieve.
+   *
    * @return
    *   The cache or FALSE on failure.
    */
   function get($cid);
   /**
    * Returns data from the persistent cache when given an array of cache IDs.
+   *
    * @param $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.
+   *
    * @return
    *   An array of the items successfully returned from cache indexed by cid.
    */
    function getMultiple(&$cids);
   /**
    * Stores data in the persistent cache.
+   *
    * @param $cid
    *   The cache ID of the data to store.
    * @param $data
    *   The data to store in the cache. Complex data types will be automatically
-            b4adf10d
+   *   serialized before insertion. Strings will be stored as plain text and not
    *   serialized. 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.
-ad3d82
+   * @param $expire
-            c9e51f47
+   *   (optional) Controls the maximum lifetime of this cache entry. Note that
    *   caches might be subject to clearing at any time, so this setting does not
    *   guarantee a minimum lifetime. With this in mind, the cache should not be
    *   used for data that must be kept during a cache clear, like sessions.
+   *
    *   Use one of the following values:
-ad3d82
+   *   - CACHE_PERMANENT: Indicates that the item should never be removed unless
    *     explicitly told to using cache_clear_all() with a cache ID.
    *   - CACHE_TEMPORARY: Indicates that the item should be removed at the next
    *     general cache wipe.
    *   - A Unix timestamp: Indicates that the item should be kept at least until
    *     the given time, after which it behaves like CACHE_TEMPORARY.
    */
   function set($cid, $data, $expire = CACHE_PERMANENT);
   /**
    * Expires data from the cache.
+   *
    * If called without arguments, expirable entries will be cleared from the
    * cache_page and cache_block bins.
+   *
    * @param $cid
    *   If set, the cache ID or an array of cache IDs. Otherwise, all cache
    *   entries that can expire are deleted. The $wildcard argument will be
    *   ignored if set to NULL.
    * @param $wildcard
    *   If TRUE, the $cid argument must contain a string value and cache IDs
    *   starting with $cid are deleted in addition to the exact cache ID
    *   specified by $cid. If $wildcard is TRUE and $cid is '*', the entire
    *   cache is emptied.
    */
   function clear($cid = NULL, $wildcard = FALSE);
   /**
    * Checks if a cache bin is empty.
+   *
    * A cache bin is considered empty if it does not contain any valid data for
    * any cache ID.
+   *
    * @return
    *   TRUE if the cache bin specified is empty.
    */
   function isEmpty();
+}
 /**
  * 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.
  */
 class DrupalDatabaseCache implements DrupalCacheInterface {
   protected $bin;
   /**
    * Constructs a DrupalDatabaseCache object.
+   *
    * @param $bin
    *   The cache bin for which the object is created.
    */
   function __construct($bin) {
     $this->bin = $bin;
+  }
   /**
    * Implements DrupalCacheInterface::get().
    */
   function get($cid) {
     $cids = array($cid);
     $cache = $this->getMultiple($cids);
     return reset($cache);
+  }
   /**
    * Implements DrupalCacheInterface::getMultiple().
    */
   function getMultiple(&$cids) {
     try {
       // Garbage collection necessary when enforcing a minimum cache lifetime.
       $this->garbageCollection($this->bin);
       // When serving cached pages, the overhead of using db_select() was found
       // to add around 30% overhead to the request. Since $this->bin is a
       // variable, this means the call to db_query() here uses a concatenated
       // string. This is highly discouraged under any other circumstances, and
       // is used here only due to the performance overhead we would incur
       // otherwise. When serving an uncached page, the overhead of using
       // db_select() is a much smaller proportion of the request.
       $result = db_query('SELECT cid, data, created, expire, serialized FROM {' . db_escape_table($this->bin) . '} WHERE cid IN (:cids)', array(':cids' => $cids));
       $cache = array();
       foreach ($result as $item) {
         $item = $this->prepareItem($item);
         if ($item) {
           $cache[$item->cid] = $item;
+        }
+      }
       $cids = array_diff($cids, array_keys($cache));
       return $cache;
+    }
     catch (Exception $e) {
       // If the database is never going to be available, cache requests should
       // return FALSE in order to allow exception handling to occur.
       return array();
+    }
+  }
   /**
    * Garbage collection for get() and getMultiple().
+   *
    * @param $bin
    *   The bin being requested.
    */
   protected function garbageCollection() {
     $cache_lifetime = variable_get('cache_lifetime', 0);
     // Clean-up the per-user cache expiration session data, so that the session
     // handler can properly clean-up the session data for anonymous users.
     if (isset($_SESSION['cache_expiration'])) {
       $expire = REQUEST_TIME - $cache_lifetime;
       foreach ($_SESSION['cache_expiration'] as $bin => $timestamp) {
         if ($timestamp < $expire) {
           unset($_SESSION['cache_expiration'][$bin]);
+        }
+      }
       if (!$_SESSION['cache_expiration']) {
         unset($_SESSION['cache_expiration']);
+      }
+    }
     // Garbage collection of temporary items is only necessary when enforcing
     // a minimum cache lifetime.
     if (!$cache_lifetime) {
       return;
+    }
     // When cache lifetime is in force, avoid running garbage collection too
     // often since this will remove temporary cache items indiscriminately.
     $cache_flush = variable_get('cache_flush_' . $this->bin, 0);
     if ($cache_flush && ($cache_flush + $cache_lifetime <= REQUEST_TIME)) {
       // Reset the variable immediately to prevent a meltdown in heavy load situations.
       variable_set('cache_flush_' . $this->bin, 0);
       // Time to flush old cache data
       db_delete($this->bin)
         ->condition('expire', CACHE_PERMANENT, '<>')
         ->condition('expire', $cache_flush, '<=')
         ->execute();
+    }
+  }
   /**
    * Prepares a cached item.
+   *
    * Checks that items are either permanent or did not expire, and unserializes
    * data as appropriate.
+   *
    * @param $cache
    *   An item loaded from cache_get() or cache_get_multiple().
+   *
    * @return
    *   The item with data unserialized as appropriate or FALSE if there is no
    *   valid item to load.
    */
   protected function prepareItem($cache) {
     global $user;
     if (!isset($cache->data)) {
       return FALSE;
+    }
     // If the cached data is temporary and subject to a per-user minimum
     // lifetime, compare the cache entry timestamp with the user session
     // cache_expiration timestamp. If the cache entry is too old, ignore it.
     if ($cache->expire != CACHE_PERMANENT && variable_get('cache_lifetime', 0) && isset($_SESSION['cache_expiration'][$this->bin]) && $_SESSION['cache_expiration'][$this->bin] > $cache->created) {
       // Ignore cache data that is too old and thus not valid for this user.
       return FALSE;
+    }
     // If the data is permanent or not subject to a minimum cache lifetime,
     // unserialize and return the cached data.
     if ($cache->serialized) {
       $cache->data = unserialize($cache->data);
+    }
     return $cache;
+  }
   /**
    * Implements DrupalCacheInterface::set().
    */
   function set($cid, $data, $expire = CACHE_PERMANENT) {
     $fields = array(
       'serialized' => 0,
       'created' => REQUEST_TIME,
       'expire' => $expire,
     );
     if (!is_string($data)) {
       $fields['data'] = serialize($data);
       $fields['serialized'] = 1;
+    }
     else {
       $fields['data'] = $data;
       $fields['serialized'] = 0;
+    }
     try {
       db_merge($this->bin)
         ->key(array('cid' => $cid))
         ->fields($fields)
         ->execute();
+    }
     catch (Exception $e) {
       // The database may not be available, so we'll ignore cache_set requests.
+    }
+  }
   /**
    * Implements DrupalCacheInterface::clear().
    */
   function clear($cid = NULL, $wildcard = FALSE) {
     global $user;
     if (empty($cid)) {
       if (variable_get('cache_lifetime', 0)) {
         // We store the time in the current user's session. We then simulate
         // that the cache was flushed for this user by not returning cached
         // data that was cached before the timestamp.
         $_SESSION['cache_expiration'][$this->bin] = REQUEST_TIME;
         $cache_flush = variable_get('cache_flush_' . $this->bin, 0);
         if ($cache_flush == 0) {
           // This is the first request to clear the cache, start a timer.
           variable_set('cache_flush_' . $this->bin, REQUEST_TIME);
+        }
         elseif (REQUEST_TIME > ($cache_flush + variable_get('cache_lifetime', 0))) {
           // Clear the cache for everyone, cache_lifetime seconds have
           // passed since the first request to clear the cache.
           db_delete($this->bin)
             ->condition('expire', CACHE_PERMANENT, '<>')
             ->condition('expire', REQUEST_TIME, '<')
             ->execute();
           variable_set('cache_flush_' . $this->bin, 0);
+        }
+      }
       else {
         // No minimum cache lifetime, flush all temporary cache entries now.
         db_delete($this->bin)
           ->condition('expire', CACHE_PERMANENT, '<>')
           ->condition('expire', REQUEST_TIME, '<')
           ->execute();
+      }
+    }
     else {
       if ($wildcard) {
         if ($cid == '*') {
           // Check if $this->bin is a cache table before truncating. Other
           // cache_clear_all() operations throw a PDO error in this situation,
           // so we don't need to verify them first. This ensures that non-cache
           // tables cannot be truncated accidentally.
           if ($this->isValidBin()) {
             db_truncate($this->bin)->execute();
+          }
           else {
             throw new Exception(t('Invalid or missing cache bin specified: %bin', array('%bin' => $this->bin)));
+          }
+        }
         else {
           db_delete($this->bin)
             ->condition('cid', db_like($cid) . '%', 'LIKE')
             ->execute();
+        }
+      }
       elseif (is_array($cid)) {
         // Delete in chunks when a large array is passed.
         do {
           db_delete($this->bin)
             ->condition('cid', array_splice($cid, 0, 1000), 'IN')
             ->execute();
+        }
         while (count($cid));
+      }
       else {
         db_delete($this->bin)
           ->condition('cid', $cid)
           ->execute();
+      }
+    }
+  }
   /**
    * Implements DrupalCacheInterface::isEmpty().
    */
   function isEmpty() {
     $this->garbageCollection();
     $query = db_select($this->bin);
     $query->addExpression('1');
     $result = $query->range(0, 1)
       ->execute()
       ->fetchField();
     return empty($result);
+  }
   /**
    * Checks if $this->bin represents a valid cache table.
+   *
    * This check is required to ensure that non-cache tables are not truncated
    * accidentally when calling cache_clear_all().
+   *
    * @return boolean
    */
   function isValidBin() {
     if ($this->bin == 'cache' || substr($this->bin, 0, 6) == 'cache_') {
       // Skip schema check for bins with standard table names.
       return TRUE;
+    }
     // These fields are required for any cache table.
     $fields = array('cid', 'data', 'expire', 'created', 'serialized');
     // Load the table schema.
     $schema = drupal_get_schema($this->bin);
     // Confirm that all fields are present.
     return isset($schema['fields']) && !array_diff($fields, array_keys($schema['fields']));
+  }
+}

Projet

Général

Profil

Club Drupal

root / drupal7 / includes / cache.inc @ 52534e1f