Merge pull request #12342 from totten/master-psr16-min

Caching - Comply with PSR-16 interfaces

CRM/Utils/Cache/APCcache.php

@@ -31,6 +31,10 @@
  * @copyright CiviCRM LLC (c) 2004-2018
  */
 class CRM_Utils_Cache_APCcache implements CRM_Utils_Cache_Interface {
+
+  use CRM_Utils_Cache_NaiveMultipleTrait; // TODO Consider native implementation.
+  use CRM_Utils_Cache_NaiveHasTrait; // TODO Native implementation
+
   const DEFAULT_TIMEOUT = 3600;
   const DEFAULT_PREFIX = '';
 
@@ -72,10 +76,14 @@ public function __construct(&$config) {
   /**
    * @param $key
    * @param $value
+   * @param null|int|\DateInterval $ttl
    *
    * @return bool
    */
-  public function set($key, &$value) {
+  public function set($key, $value, $ttl = NULL) {
+    if ($ttl !== NULL) {
+      throw new \RuntimeException("FIXME: " . __CLASS__ . "::set() should support non-NULL TTL");
+    }
     if (!apc_store($this->_prefix . $key, $value, $this->_timeout)) {
       return FALSE;
     }
@@ -84,10 +92,14 @@ public function set($key, &$value) {
 
   /**
    * @param $key
+   * @param mixed $default
    *
    * @return mixed
    */
-  public function get($key) {
+  public function get($key, $default = NULL) {
+    if ($default !== NULL) {
+      throw new \RuntimeException("FIXME: " . __CLASS__ . "::get() only supports NULL default");
+    }
     return apc_fetch($this->_prefix . $key);
   }
 
@@ -113,6 +125,11 @@ public function flush() {
         apc_delete($this->_prefix . $name);
       }
     }
+    return TRUE;
+  }
+
+  public function clear() {
+    return $this->flush();
   }
 
 }

CRM/Utils/Cache/ArrayCache.php

@@ -36,6 +36,9 @@
  */
 class CRM_Utils_Cache_Arraycache implements CRM_Utils_Cache_Interface {
 
+  use CRM_Utils_Cache_NaiveMultipleTrait;
+  use CRM_Utils_Cache_NaiveHasTrait; // TODO Native implementation
+
   /**
    * The cache storage container, an in memory array by default
    */
@@ -56,30 +59,44 @@ public function __construct($config) {
   /**
    * @param string $key
    * @param mixed $value
+   * @param null|int|\DateInterval $ttl
+   * @return bool
    */
-  public function set($key, &$value) {
+  public function set($key, $value, $ttl = NULL) {
+    if ($ttl !== NULL) {
+      throw new \RuntimeException("FIXME: " . __CLASS__ . "::set() should support non-NULL TTL");
+    }
     $this->_cache[$key] = $value;
+    return TRUE;
   }
 
   /**
    * @param string $key
+   * @param mixed $default
    *
    * @return mixed
    */
-  public function get($key) {
-    return CRM_Utils_Array::value($key, $this->_cache);
+  public function get($key, $default = NULL) {
+    return CRM_Utils_Array::value($key, $this->_cache, $default);
   }
 
   /**
    * @param string $key
+   * @return bool
    */
   public function delete($key) {
     unset($this->_cache[$key]);
+    return TRUE;
   }
 
   public function flush() {
     unset($this->_cache);
     $this->_cache = array();
+    return TRUE;
+  }
+
+  public function clear() {
+    return $this->flush();
   }
 
 }

CRM/Utils/Cache/Interface.php

@@ -30,60 +30,78 @@
  * @package CRM
  * @copyright CiviCRM LLC (c) 2004-2018
  *
- * CRM_Utils_Cache_Interface
+ * CRM_Utils_Cache_Interface is a long-standing interface used within CiviCRM
+ * for interacting with a cache service. In style and substance, it is extremely
+ * similar to PHP-FIG's SimpleCache interface (PSR-16). Consequently, beginning
+ * with CiviCRM v5.4, this extends \Psr\SimpleCache\CacheInterface.
  *
- * PHP-FIG has been developing a draft standard for caching,
- * PSR-6. The standard has not been ratified yet. When
- * making changes to this interface, please take care to
- * avoid *conflicst* with PSR-6's CacheItemPoolInterface. At
- * time of writing, they do not conflict. Avoiding conflicts
- * will enable more transition paths where Civi
- * simultaneously supports both interfaces in the same
- * implementation.
- *
- * For example, the current interface defines:
- *
- *   function get($key) => mixed $value
- *
- * and PSR-6 defines:
- *
- *   function getItem($key) => ItemInterface $item
- *
- * These are different styles (e.g. "weak item" vs "strong item"),
- * but the two methods do not *conflict*. They can coexist,
- * and you can trivially write adapters between the two.
- *
- * @see https://github.com/php-fig/fig-standards/blob/master/proposed/cache.md
+ * @see https://www.php-fig.org/psr/psr-16/
  */
-interface CRM_Utils_Cache_Interface {
+interface CRM_Utils_Cache_Interface extends \Psr\SimpleCache\CacheInterface {
 
   /**
    * Set the value in the cache.
    *
    * @param string $key
    * @param mixed $value
+   * @param null|int|\DateInterval $ttl
+   * @return bool
    */
-  public function set($key, &$value);
+  public function set($key, $value, $ttl = NULL);
 
   /**
    * Get a value from the cache.
    *
    * @param string $key
+   * @param mixed $default
    * @return mixed
-   *   NULL if $key has not been previously set
+   *   The previously set value value, or $default (NULL).
    */
-  public function get($key);
+  public function get($key, $default = NULL);
 
   /**
    * Delete a value from the cache.
    *
    * @param string $key
+   * @return bool
    */
   public function delete($key);
 
   /**
    * Delete all values from the cache.
+   *
+   * NOTE: flush() and clear() should be aliases. flush() is specified by
+   * Civi's traditional interface, and clear() is specified by PSR-16.
+   *
+   * @return bool
+   * @see clear
+   * @deprecated
    */
   public function flush();
 
+  /**
+   * Delete all values from the cache.
+   *
+   * NOTE: flush() and clear() should be aliases. flush() is specified by
+   * Civi's traditional interface, and clear() is specified by PSR-16.
+   *
+   * @return bool
+   * @see flush
+   */
+  public function clear();
+
+  /**
+   * Determines whether an item is present in the cache.
+   *
+   * NOTE: It is recommended that has() is only to be used for cache warming type purposes
+   * and not to be used within your live applications operations for get/set, as this method
+   * is subject to a race condition where your has() will return true and immediately after,
+   * another script can remove it making the state of your app out of date.
+   *
+   * @param string $key The cache item key.
+   *
+   * @return bool
+   */
+  public function has($key);
+
 }

CRM/Utils/Cache/Memcache.php

@@ -31,6 +31,10 @@
  * @copyright CiviCRM LLC (c) 2004-2018
  */
 class CRM_Utils_Cache_Memcache implements CRM_Utils_Cache_Interface {
+
+  use CRM_Utils_Cache_NaiveMultipleTrait; // TODO Consider native implementation.
+  use CRM_Utils_Cache_NaiveHasTrait; // TODO Native implementation
+
   const DEFAULT_HOST = 'localhost';
   const DEFAULT_PORT = 11211;
   const DEFAULT_TIMEOUT = 3600;
@@ -109,10 +113,14 @@ public function __construct($config) {
   /**
    * @param $key
    * @param $value
+   * @param null|int|\DateInterval $ttl
    *
    * @return bool
    */
-  public function set($key, &$value) {
+  public function set($key, $value, $ttl = NULL) {
+    if ($ttl !== NULL) {
+      throw new \RuntimeException("FIXME: " . __CLASS__ . "::set() should support non-NULL TTL");
+    }
     if (!$this->_cache->set($this->_prefix . $key, $value, FALSE, $this->_timeout)) {
       return FALSE;
     }
@@ -121,29 +129,37 @@ public function set($key, &$value) {
 
   /**
    * @param $key
+   * @param mixed $default
    *
    * @return mixed
    */
-  public function &get($key) {
+  public function get($key, $default = NULL) {
+    if ($default !== NULL) {
+      throw new \RuntimeException("FIXME: " . __CLASS__ . "::get() only supports NULL default");
+    }
     $result = $this->_cache->get($this->_prefix . $key);
     return $result;
   }
 
   /**
    * @param $key
    *
-   * @return mixed
+   * @return bool
    */
   public function delete($key) {
     return $this->_cache->delete($this->_prefix . $key);
   }
 
   /**
-   * @return mixed
+   * @return bool
    */
   public function flush() {
     // FIXME: Only delete items matching `$this->_prefix`.
     return $this->_cache->flush();
   }
 
+  public function clear() {
+    return $this->flush();
+  }
+
 }

CRM/Utils/Cache/Memcached.php

@@ -31,6 +31,10 @@
  * @copyright CiviCRM LLC (c) 2004-2018
  */
 class CRM_Utils_Cache_Memcached implements CRM_Utils_Cache_Interface {
+
+  use CRM_Utils_Cache_NaiveMultipleTrait; // TODO Consider native implementation.
+  use CRM_Utils_Cache_NaiveHasTrait; // TODO Native implementation
+
   const DEFAULT_HOST = 'localhost';
   const DEFAULT_PORT = 11211;
   const DEFAULT_TIMEOUT = 3600;
@@ -110,11 +114,15 @@ public function __construct($config) {
   /**
    * @param $key
    * @param $value
+   * @param null|int|\DateInterval $ttl
    *
    * @return bool
    * @throws Exception
    */
-  public function set($key, &$value) {
+  public function set($key, $value, $ttl = NULL) {
+    if ($ttl !== NULL) {
+      throw new \RuntimeException("FIXME: " . __CLASS__ . "::set() should support non-NULL TTL");
+    }
     $key = $this->cleanKey($key);
     if (!$this->_cache->set($key, $value, $this->_timeout)) {
       CRM_Core_Error::debug('Result Code: ', $this->_cache->getResultMessage());
@@ -126,10 +134,14 @@ public function set($key, &$value) {
 
   /**
    * @param $key
+   * @param mixed $default
    *
    * @return mixed
    */
-  public function &get($key) {
+  public function get($key, $default = NULL) {
+    if ($default !== NULL) {
+      throw new \RuntimeException("FIXME: " . __CLASS__ . "::get() only supports NULL default");
+    }
     $key = $this->cleanKey($key);
     $result = $this->_cache->get($key);
     return $result;
@@ -161,11 +173,15 @@ public function cleanKey($key) {
   }
 
   /**
-   * @return mixed
+   * @return bool
    */
   public function flush() {
     // FIXME: Only delete items matching `$this->_prefix`.
     return $this->_cache->flush();
   }
 
+  public function clear() {
+    return $this->flush();
+  }
+
 }

CRM/Utils/Cache/NaiveHasTrait.php

@@ -0,0 +1,49 @@
+<?php
+/*
+ +--------------------------------------------------------------------+
+ | CiviCRM version 5                                                  |
+ +--------------------------------------------------------------------+
+ | Copyright CiviCRM LLC (c) 2004-2018                                |
+ +--------------------------------------------------------------------+
+ | This file is a part of CiviCRM.                                    |
+ |                                                                    |
+ | CiviCRM is free software; you can copy, modify, and distribute it  |
+ | under the terms of the GNU Affero General Public License           |
+ | Version 3, 19 November 2007 and the CiviCRM Licensing Exception.   |
+ |                                                                    |
+ | CiviCRM is distributed in the hope that it will be useful, but     |
+ | WITHOUT ANY WARRANTY; without even the implied warranty of         |
+ | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.               |
+ | See the GNU Affero General Public License for more details.        |
+ |                                                                    |
+ | You should have received a copy of the GNU Affero General Public   |
+ | License and the CiviCRM Licensing Exception along                  |
+ | with this program; if not, contact CiviCRM LLC                     |
+ | at info[AT]civicrm[DOT]org. If you have questions about the        |
+ | GNU Affero General Public License or the licensing of CiviCRM,     |
+ | see the CiviCRM license FAQ at http://civicrm.org/licensing        |
+ +--------------------------------------------------------------------+
+ */
+
+/**
+ *
+ * @package CRM
+ * @copyright CiviCRM LLC (c) 2004-2018
+ *
+ * The traditional CRM_Utils_Cache_Interface did not support has().
+ * To get drop-in compliance with PSR-16, we use a naive adapter.
+ *
+ * Ideally, these should be replaced with more performant/native versions.
+ */
+trait CRM_Utils_Cache_NaiveHasTrait {
+
+  public function has($key) {
+    // This is crazy-talk. If you've got an environment setup where you might
+    // be investigating this, fix your preferred cache driver by
+    // replacing `NaiveHasTrait` with a decent function.
+    $hasDefaultA = ($this->get($key, NULL) === NULL);
+    $hasDefaultB = ($this->get($key, 123) === 123);
+    return !($hasDefaultA && $hasDefaultB);
+  }
+
+}