3 +--------------------------------------------------------------------+
5 +--------------------------------------------------------------------+
6 | Copyright CiviCRM LLC (c) 2004-2019 |
7 +--------------------------------------------------------------------+
8 | This file is a part of CiviCRM. |
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. |
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. |
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 +--------------------------------------------------------------------+
31 * @copyright CiviCRM LLC (c) 2004-2019
35 * Cache is an empty base object, we'll modify the scheme when we have different caching schemes
37 class CRM_Utils_Cache
{
39 const DELIMITER
= '/';
42 * (Quasi-Private) Treat this as private. It is marked public to facilitate testing.
44 * We only need one instance of this object. So we use the singleton
45 * pattern and cache the instance in this variable
49 public static $_singleton = NULL;
54 * @param array $config
55 * An array of configuration params.
57 * @return \CRM_Utils_Cache
59 public function __construct(&$config) {
60 CRM_Core_Error
::fatal(ts('this is just an interface and should not be called directly'));
64 * Singleton function used to manage this object.
66 * @return CRM_Utils_Cache_Interface
68 public static function &singleton() {
69 if (self
::$_singleton === NULL) {
70 $className = self
::getCacheDriver();
71 // a generic method for utilizing any of the available db caches.
72 $dbCacheClass = 'CRM_Utils_Cache_' . $className;
73 $settings = self
::getCacheSettings($className);
74 $settings['prefix'] = CRM_Utils_Array
::value('prefix', $settings, '') . self
::DELIMITER
. 'default' . self
::DELIMITER
;
75 self
::$_singleton = new $dbCacheClass($settings);
77 return self
::$_singleton;
81 * Get cache relevant settings.
86 * associative array of settings for the cache
88 public static function getCacheSettings($cachePlugin) {
89 switch ($cachePlugin) {
99 'host' => 'localhost',
105 // Use old constants if needed to ensure backward compatibility
106 if (defined('CIVICRM_MEMCACHE_HOST')) {
107 $defaults['host'] = CIVICRM_MEMCACHE_HOST
;
110 if (defined('CIVICRM_MEMCACHE_PORT')) {
111 $defaults['port'] = CIVICRM_MEMCACHE_PORT
;
114 if (defined('CIVICRM_MEMCACHE_TIMEOUT')) {
115 $defaults['timeout'] = CIVICRM_MEMCACHE_TIMEOUT
;
118 if (defined('CIVICRM_MEMCACHE_PREFIX')) {
119 $defaults['prefix'] = CIVICRM_MEMCACHE_PREFIX
;
122 // Use new constants if possible
123 if (defined('CIVICRM_DB_CACHE_HOST')) {
124 $defaults['host'] = CIVICRM_DB_CACHE_HOST
;
127 if (defined('CIVICRM_DB_CACHE_PORT')) {
128 $defaults['port'] = CIVICRM_DB_CACHE_PORT
;
131 if (defined('CIVICRM_DB_CACHE_TIMEOUT')) {
132 $defaults['timeout'] = CIVICRM_DB_CACHE_TIMEOUT
;
135 if (defined('CIVICRM_DB_CACHE_PREFIX')) {
136 $defaults['prefix'] = CIVICRM_DB_CACHE_PREFIX
;
143 if (defined('CIVICRM_DB_CACHE_TIMEOUT')) {
144 $defaults['timeout'] = CIVICRM_DB_CACHE_TIMEOUT
;
146 if (defined('CIVICRM_DB_CACHE_PREFIX')) {
147 $defaults['prefix'] = CIVICRM_DB_CACHE_PREFIX
;
155 * Create a new, named, limited-use cache.
157 * This is a factory function. Generally, you should use Civi::cache($name)
158 * to locate managed cached instance.
160 * @param array $params
162 * - name: string, unique symbolic name.
163 * For a naming convention, use `snake_case` or `CamelCase` to maximize
164 * portability/cleanliness. Any other punctuation or whitespace
165 * should function correctly, but it can be harder to inspect/debug.
166 * - type: array|string, list of acceptable cache types, in order of preference.
167 * - prefetch: bool, whether to prefetch all data in cache (if possible).
168 * - withArray: bool|null|'fast', whether to setup a thread-local array-cache in front of the cache driver.
169 * Note that cache-values may be passed to the underlying driver with extra metadata,
170 * so this will slightly change/enlarge the on-disk format.
171 * Support varies by driver:
172 * - For most memory backed caches, this option is meaningful.
173 * - For SqlGroup, this option is ignored. SqlGroup has equivalent behavior built-in.
174 * - For ArrayCache, this option is ignored. It's redundant.
175 * If this is a short-lived process in which TTL's don't matter, you might
176 * use 'fast' mode. It sacrifices some PSR-16 compliance and cache-coherency
177 * protections to improve performance.
178 * @return CRM_Utils_Cache_Interface
179 * @throws CRM_Core_Exception
182 public static function create($params = []) {
183 $types = (array) $params['type'];
185 if (!empty($params['name'])) {
186 $params['name'] = CRM_Core_BAO_Cache
::cleanKey($params['name']);
189 foreach ($types as $type) {
192 if (defined('CIVICRM_DB_CACHE_CLASS') && in_array(CIVICRM_DB_CACHE_CLASS
, ['Memcache', 'Memcached', 'Redis'])) {
193 $dbCacheClass = 'CRM_Utils_Cache_' . CIVICRM_DB_CACHE_CLASS
;
194 $settings = self
::getCacheSettings(CIVICRM_DB_CACHE_CLASS
);
195 $settings['prefix'] = CRM_Utils_Array
::value('prefix', $settings, '') . self
::DELIMITER
. $params['name'] . self
::DELIMITER
;
196 $cache = new $dbCacheClass($settings);
197 if (!empty($params['withArray'])) {
198 $cache = $params['withArray'] === 'fast' ?
new CRM_Utils_Cache_FastArrayDecorator($cache) : new CRM_Utils_Cache_ArrayDecorator($cache);
205 if (defined('CIVICRM_DSN') && CIVICRM_DSN
) {
206 return new CRM_Utils_Cache_SqlGroup([
207 'group' => $params['name'],
208 'prefetch' => CRM_Utils_Array
::value('prefetch', $params, FALSE),
215 return new CRM_Utils_Cache_ArrayCache([]);
220 throw new CRM_Core_Exception("Failed to instantiate cache. No supported cache type found. " . print_r($params, 1));
224 * Assert that a key is well-formed.
228 * Same $key, if it's valid.
229 * @throws \CRM_Utils_Cache_InvalidArgumentException
231 public static function assertValidKey($key) {
232 $strict = CRM_Utils_Constant
::value('CIVICRM_PSR16_STRICT', FALSE) ||
defined('CIVICRM_TEST');
234 if (!is_string($key)) {
235 throw new CRM_Utils_Cache_InvalidArgumentException("Invalid cache key: Not a string");
238 if ($strict && !preg_match(';^[A-Za-z0-9_\-\. ]+$;', $key)) {
239 throw new CRM_Utils_Cache_InvalidArgumentException("Invalid cache key: Illegal characters");
242 if ($strict && strlen($key) > 255) {
243 throw new CRM_Utils_Cache_InvalidArgumentException("Invalid cache key: Too long");
251 * Ex: 'ArrayCache', 'Memcache', 'Redis'.
253 public static function getCacheDriver() {
254 // default to ArrayCache for now
255 $className = 'ArrayCache';
257 // Maintain backward compatibility for now.
258 // Setting CIVICRM_USE_MEMCACHE or CIVICRM_USE_ARRAYCACHE will
259 // override the CIVICRM_DB_CACHE_CLASS setting.
260 // Going forward, CIVICRM_USE_xxxCACHE should be deprecated.
261 if (defined('CIVICRM_USE_MEMCACHE') && CIVICRM_USE_MEMCACHE
) {
262 $className = 'Memcache';
265 elseif (defined('CIVICRM_USE_ARRAYCACHE') && CIVICRM_USE_ARRAYCACHE
) {
266 $className = 'ArrayCache';
269 elseif (defined('CIVICRM_DB_CACHE_CLASS') && CIVICRM_DB_CACHE_CLASS
) {
270 $className = CIVICRM_DB_CACHE_CLASS
;
277 * Generate a unique negative-acknowledgement token (NACK).
279 * When using PSR-16 to read a value, the `$cahce->get()` will a return a default
280 * value on cache-miss, so it's hard to know if you've gotten a geniune value
281 * from the cache or just a default. If you're in an edge-case where it matters
282 * (and you want to do has()+get() in a single roundtrip), use the nack() as
285 * $nack = CRM_Utils_Cache::nack();
286 * $value = $cache->get('foo', $nack);
287 * echo ($value === $nack) ? "Cache has a value, and we got it" : "Cache has no value".
289 * The value should be unique to avoid accidental matches.
292 * Unique nonce value indicating a "negative acknowledgement" (failed read).
293 * If we need to accurately perform has($key)+get($key), we can
294 * use `get($key,$nack)`.
296 public static function nack() {
297 $st =& Civi
::$statics[__CLASS__
];
298 if (!isset($st['nack-c'])) {
299 $st['nack-c'] = md5(CRM_Utils_Request
::id() . CIVICRM_SITE_KEY
. CIVICRM_DSN
. mt_rand(0, 10000));
302 return 'NACK:' . $st['nack-c'] . $st['nack-i']++
;