From 90cdaa0e0f6a93d54d9c2743bacd521b995c3f58 Mon Sep 17 00:00:00 2001
From: Tim Otten <totten@civicrm.org>
Date: Wed, 26 Sep 2018 19:19:45 -0400
Subject: [PATCH] Register "short" and "long" cache services

Overview
--------

This is an improvement for developer-experience when working with caches.
It reduces the amount of boilerplate required for core-code or
extension-code in a typical caching use-case.

Before
------

* To use a short-lived/latency-optimized cache (e.g. Redis or PHP array),
  you can work with the default cache instance (`Civi::cache('default')`.
* To use a long-lived/durability-optimized cache (e.g. Redis or SQL), there is no
  simple way or code. You must [register a custom cache service](https://docs.civicrm.org/dev/en/latest/framework/cache/#example-named-service).

After
-----

* All the above remains true. Additionally, you can request the `short` or `long` cache service.
* To use a short-lived/latency-optimized cache, you can use `Civi::cache('short')`. (`short` and `default` are synonmyms.)
* To use a long-lived/durability-optimized cache, you can use use `Civi::cache('long')`.

Comments
--------

* After this is approved, we should update the [dev docs for caching](https://docs.civicrm.org/dev/en/latest/framework/cache/).
* There's a bike-sheddy argument about the naming. I'd be willing to rename if there was a strong reason, but I don't really think
  there is a strong reason. This naming convention provides a simple dichotomy of `short` vs `long`.
---
 CRM/Utils/System.php    | 1 +
 Civi.php                | 9 +++++++++
 Civi/Core/Container.php | 2 ++
 3 files changed, 12 insertions(+)

diff --git a/CRM/Utils/System.php b/CRM/Utils/System.php
index fb5bb879ea..ad54675ab7 100644
--- a/CRM/Utils/System.php
+++ b/CRM/Utils/System.php
@@ -1425,6 +1425,7 @@ class CRM_Utils_System {
     $localDrivers = ['CRM_Utils_Cache_Arraycache', 'CRM_Utils_Cache_NoCache'];
     if (Civi\Core\Container::isContainerBooted()
       && !in_array(get_class(CRM_Utils_Cache::singleton()), $localDrivers)) {
+      Civi::cache('long')->flush();
       Civi::cache('settings')->flush();
       Civi::cache('js_strings')->flush();
       Civi::cache('community_messages')->flush();
diff --git a/Civi.php b/Civi.php
index 8acfdba768..d535e1afbd 100644
--- a/Civi.php
+++ b/Civi.php
@@ -32,6 +32,15 @@ class Civi {
    *   The name of the cache. The 'default' cache is biased toward
    *   high-performance caches (eg memcache/redis/apc) when
    *   available and falls back to single-request (static) caching.
+   *   Ex: 'short' or 'default' is useful for high-speed, short-lived cache data.
+   *       This is appropriate if you believe that latency (millisecond-level
+   *       read time) is the main factor. For example: caching data from
+   *       a couple SQL queries.
+   *   Ex: 'long' can be useful for longer-lived cache data. It's appropriate if
+   *       you believe that longevity (e.g. surviving for several hours or a day)
+   *       is more important than  millisecond-level access time. For example:
+   *       caching the result of a simple metadata-query.
+   *
    * @return CRM_Utils_Cache_Interface
    *   NOTE: Beginning in CiviCRM v5.4, the cache instance complies with
    *   PSR-16 (\Psr\SimpleCache\CacheInterface).
diff --git a/Civi/Core/Container.php b/Civi/Core/Container.php
index 6eb4a4d66a..cdaabecc91 100644
--- a/Civi/Core/Container.php
+++ b/Civi/Core/Container.php
@@ -165,6 +165,7 @@ class Container {
       'community_messages' => 'community_messages',
       'checks' => 'checks',
       'session' => 'CiviCRM Session',
+      'long' => 'long',
     );
     foreach ($basicCaches as $cacheSvc => $cacheGrp) {
       $container->setDefinition("cache.{$cacheSvc}", new Definition(
@@ -213,6 +214,7 @@ class Container {
       ))
         ->setFactory(array($class, 'singleton'));
     }
+    $container->setAlias('cache.short', 'cache.default');
 
     $container->setDefinition('prevnext', new Definition(
       'CRM_Core_PrevNextCache_Interface',
-- 
2.25.1