CRM/Utils/Cache.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | CiviCRM version 5                                                  |
   5  +--------------------------------------------------------------------+
   6  | Copyright CiviCRM LLC (c) 2004-2018                                |
   7  +--------------------------------------------------------------------+
   8  | This file is a part of CiviCRM.                                    |
   9  |                                                                    |
  10  | CiviCRM is free software; you can copy, modify, and distribute it  |
  11  | under the terms of the GNU Affero General Public License           |
  12  | Version 3, 19 November 2007 and the CiviCRM Licensing Exception.   |
  13  |                                                                    |
  14  | CiviCRM is distributed in the hope that it will be useful, but     |
  15  | WITHOUT ANY WARRANTY; without even the implied warranty of         |
  16  | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.               |
  17  | See the GNU Affero General Public License for more details.        |
  18  |                                                                    |
  19  | You should have received a copy of the GNU Affero General Public   |
  20  | License and the CiviCRM Licensing Exception along                  |
  21  | with this program; if not, contact CiviCRM LLC                     |
  22  | at info[AT]civicrm[DOT]org. If you have questions about the        |
  23  | GNU Affero General Public License or the licensing of CiviCRM,     |
  24  | see the CiviCRM license FAQ at http://civicrm.org/licensing        |
  25  +--------------------------------------------------------------------+
  26  */
  27
  28 /**
  29  *
  30  * @package CRM
  31  * @copyright CiviCRM LLC (c) 2004-2018
  32  */
  33
  34 /**
  35  * Cache is an empty base object, we'll modify the scheme when we have different caching schemes
  36  */
  37 class CRM_Utils_Cache {
  38
  39   const DELIMITER = '/';
  40
  41   /**
  42    * (Quasi-Private) Treat this as private. It is marked public to facilitate testing.
  43    *
  44    * We only need one instance of this object. So we use the singleton
  45    * pattern and cache the instance in this variable
  46    *
  47    * @var object
  48    */
  49   public static $_singleton = NULL;
  50
  51   /**
  52    * Constructor.
  53    *
  54    * @param array $config
  55    *   An array of configuration params.
  56    *
  57    * @return \CRM_Utils_Cache
  58    */
  59   public function __construct(&$config) {
  60     CRM_Core_Error::fatal(ts('this is just an interface and should not be called directly'));
  61   }
  62
  63   /**
  64    * Singleton function used to manage this object.
  65    *
  66    * @return CRM_Utils_Cache_Interface
  67    */
  68   public static function &singleton() {
  69     if (self::$_singleton === NULL) {
  70       $className = 'ArrayCache';   // default to ArrayCache for now
  71
  72       // Maintain backward compatibility for now.
  73       // Setting CIVICRM_USE_MEMCACHE or CIVICRM_USE_ARRAYCACHE will
  74       // override the CIVICRM_DB_CACHE_CLASS setting.
  75       // Going forward, CIVICRM_USE_xxxCACHE should be deprecated.
  76       if (defined('CIVICRM_USE_MEMCACHE') && CIVICRM_USE_MEMCACHE) {
  77         $className = 'Memcache';
  78       }
  79       elseif (defined('CIVICRM_USE_ARRAYCACHE') && CIVICRM_USE_ARRAYCACHE) {
  80         $className = 'ArrayCache';
  81       }
  82       elseif (defined('CIVICRM_DB_CACHE_CLASS') && CIVICRM_DB_CACHE_CLASS) {
  83         $className = CIVICRM_DB_CACHE_CLASS;
  84       }
  85
  86       // a generic method for utilizing any of the available db caches.
  87       $dbCacheClass = 'CRM_Utils_Cache_' . $className;
  88       $settings = self::getCacheSettings($className);
  89       $settings['prefix'] = CRM_Utils_Array::value('prefix', $settings, '') . self::DELIMITER . 'default' . self::DELIMITER;
  90       self::$_singleton = new $dbCacheClass($settings);
  91     }
  92     return self::$_singleton;
  93   }
  94
  95   /**
  96    * Get cache relevant settings.
  97    *
  98    * @param $cachePlugin
  99    *
 100    * @return array
 101    *   associative array of settings for the cache
 102    */
 103   public static function getCacheSettings($cachePlugin) {
 104     switch ($cachePlugin) {
 105       case 'ArrayCache':
 106       case 'NoCache':
 107         $defaults = array();
 108         break;
 109
 110       case 'Redis':
 111       case 'Memcache':
 112       case 'Memcached':
 113         $defaults = array(
 114           'host' => 'localhost',
 115           'port' => 11211,
 116           'timeout' => 3600,
 117           'prefix' => '',
 118         );
 119
 120         // Use old constants if needed to ensure backward compatibility
 121         if (defined('CIVICRM_MEMCACHE_HOST')) {
 122           $defaults['host'] = CIVICRM_MEMCACHE_HOST;
 123         }
 124
 125         if (defined('CIVICRM_MEMCACHE_PORT')) {
 126           $defaults['port'] = CIVICRM_MEMCACHE_PORT;
 127         }
 128
 129         if (defined('CIVICRM_MEMCACHE_TIMEOUT')) {
 130           $defaults['timeout'] = CIVICRM_MEMCACHE_TIMEOUT;
 131         }
 132
 133         if (defined('CIVICRM_MEMCACHE_PREFIX')) {
 134           $defaults['prefix'] = CIVICRM_MEMCACHE_PREFIX;
 135         }
 136
 137         // Use new constants if possible
 138         if (defined('CIVICRM_DB_CACHE_HOST')) {
 139           $defaults['host'] = CIVICRM_DB_CACHE_HOST;
 140         }
 141
 142         if (defined('CIVICRM_DB_CACHE_PORT')) {
 143           $defaults['port'] = CIVICRM_DB_CACHE_PORT;
 144         }
 145
 146         if (defined('CIVICRM_DB_CACHE_TIMEOUT')) {
 147           $defaults['timeout'] = CIVICRM_DB_CACHE_TIMEOUT;
 148         }
 149
 150         if (defined('CIVICRM_DB_CACHE_PREFIX')) {
 151           $defaults['prefix'] = CIVICRM_DB_CACHE_PREFIX;
 152         }
 153
 154         break;
 155
 156       case 'APCcache':
 157         $defaults = array();
 158         if (defined('CIVICRM_DB_CACHE_TIMEOUT')) {
 159           $defaults['timeout'] = CIVICRM_DB_CACHE_TIMEOUT;
 160         }
 161         if (defined('CIVICRM_DB_CACHE_PREFIX')) {
 162           $defaults['prefix'] = CIVICRM_DB_CACHE_PREFIX;
 163         }
 164         break;
 165     }
 166     return $defaults;
 167   }
 168
 169   /**
 170    * Create a new, named, limited-use cache.
 171    *
 172    * This is a factory function. Generally, you should use Civi::cache($name)
 173    * to locate managed cached instance.
 174    *
 175    * @param array $params
 176    *   Array with keys:
 177    *   - name: string, unique symbolic name.
 178    *   - type: array|string, list of acceptable cache types, in order of preference.
 179    *   - prefetch: bool, whether to prefetch all data in cache (if possible).
 180    * @return CRM_Utils_Cache_Interface
 181    * @throws CRM_Core_Exception
 182    * @see Civi::cache()
 183    */
 184   public static function create($params = array()) {
 185     $types = (array) $params['type'];
 186
 187     foreach ($types as $type) {
 188       switch ($type) {
 189         case '*memory*':
 190           if (defined('CIVICRM_DB_CACHE_CLASS') && in_array(CIVICRM_DB_CACHE_CLASS, array('Memcache', 'Memcached', 'Redis'))) {
 191             $dbCacheClass = 'CRM_Utils_Cache_' . CIVICRM_DB_CACHE_CLASS;
 192             $settings = self::getCacheSettings(CIVICRM_DB_CACHE_CLASS);
 193             $settings['prefix'] = CRM_Utils_Array::value('prefix', $settings, '') . self::DELIMITER . $params['name'] . self::DELIMITER;
 194             return new $dbCacheClass($settings);
 195           }
 196           break;
 197
 198         case 'SqlGroup':
 199           if (defined('CIVICRM_DSN') && CIVICRM_DSN) {
 200             return new CRM_Utils_Cache_SqlGroup(array(
 201               'group' => $params['name'],
 202               'prefetch' => CRM_Utils_Array::value('prefetch', $params, FALSE),
 203             ));
 204           }
 205           break;
 206
 207         case 'Arraycache':
 208         case 'ArrayCache':
 209           return new CRM_Utils_Cache_ArrayCache(array());
 210
 211       }
 212     }
 213
 214     throw new CRM_Core_Exception("Failed to instantiate cache. No supported cache type found. " . print_r($params, 1));
 215   }
 216
 217   /**
 218    * Assert that a key is well-formed.
 219    *
 220    * @param string $key
 221    * @return string
 222    *   Same $key, if it's valid.
 223    * @throws \CRM_Utils_Cache_InvalidArgumentException
 224    */
 225   public static function assertValidKey($key) {
 226     $strict = CRM_Utils_Constant::value('CIVICRM_PSR16_STRICT', FALSE) || defined('CIVICRM_TEST');
 227
 228     if (!is_string($key)) {
 229       throw new CRM_Utils_Cache_InvalidArgumentException("Invalid cache key: Not a string");
 230     }
 231
 232     if ($strict && !preg_match(';^[A-Za-z0-9_\-\. ]+$;', $key)) {
 233       throw new CRM_Utils_Cache_InvalidArgumentException("Invalid cache key: Illegal characters");
 234     }
 235
 236     if ($strict && strlen($key) > 255) {
 237       throw new CRM_Utils_Cache_InvalidArgumentException("Invalid cache key: Too long");
 238     }
 239
 240     return $key;
 241   }
 242
 243 }