Merge pull request #9598 from JMAConsulting/CRM-19585-7

[civicrm-core.git] / CRM / Utils / Cache / Interface.php

diff --git a/CRM/Utils/Cache/Interface.php b/CRM/Utils/Cache/Interface.php
index 00449c71f853b3c35edbfc3e11805bd52749b44b..ce015522cb32828c43169a7e3746ade8d47edce3 100644 (file)
--- a/CRM/Utils/Cache/Interface.php
+++ b/CRM/Utils/Cache/Interface.php
@@ -3,7 +3,7 @@
  +--------------------------------------------------------------------+
  | CiviCRM version 4.7                                                |
  +--------------------------------------------------------------------+
- | Copyright CiviCRM LLC (c) 2004-2015                                |
+ | Copyright CiviCRM LLC (c) 2004-2017                                |
  +--------------------------------------------------------------------+
  | This file is a part of CiviCRM.                                    |
  |                                                                    |
@@ -28,9 +28,32 @@
 /**
  *
  * @package CRM
- * @copyright CiviCRM LLC (c) 2004-2015
- * $Id$
+ * @copyright CiviCRM LLC (c) 2004-2017
  *
+ * CRM_Utils_Cache_Interface
+ *
+ * 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
  */
 interface CRM_Utils_Cache_Interface {
 
@@ -39,7 +62,6 @@ interface CRM_Utils_Cache_Interface {
    *
    * @param string $key
    * @param mixed $value
-   * @return void
    */
   public function set($key, &$value);
 
@@ -56,14 +78,11 @@ interface CRM_Utils_Cache_Interface {
    * Delete a value from the cache.
    *
    * @param string $key
-   * @return void
    */
   public function delete($key);
 
   /**
    * Delete all values from the cache.
-   *
-   * @return void
    */
   public function flush();