Civi.php

   1 <?php
   2
   3 /**
   4  * Class Civi
   5  *
   6  * The "Civi" class provides a facade for accessing major subsystems,
   7  * such as the service-container and settings manager. It serves as a
   8  * bridge which allows procedural code to access important objects.
   9  *
  10  * General principles:
  11  *  - Each function provides access to a major subsystem.
  12  *  - Each function performs a simple lookup.
  13  *  - Each function returns an interface.
  14  *  - Whenever possible, interfaces should be well-known (e.g. based
  15  *    on a standard or well-regarded provider).
  16  */
  17 class Civi {
  18
  19   /**
  20    * A central location for static variable storage.
  21    * @var array
  22    * ```
  23    * `Civi::$statics[__CLASS__]['foo'] = 'bar';
  24    * ```
  25    */
  26   public static $statics = [];
  27
  28   /**
  29    * Retrieve a named cache instance.
  30    *
  31    * @param string $name
  32    *   The name of the cache. The 'default' cache is biased toward
  33    *   high-performance caches (eg memcache/redis/apc) when
  34    *   available and falls back to single-request (static) caching.
  35    *   Ex: 'short' or 'default' is useful for high-speed, short-lived cache data.
  36    *       This is appropriate if you believe that latency (millisecond-level
  37    *       read time) is the main factor. For example: caching data from
  38    *       a couple SQL queries.
  39    *   Ex: 'long' can be useful for longer-lived cache data. It's appropriate if
  40    *       you believe that longevity (e.g. surviving for several hours or a day)
  41    *       is more important than  millisecond-level access time. For example:
  42    *       caching the result of a simple metadata-query.
  43    *
  44    * @return CRM_Utils_Cache_Interface
  45    *   NOTE: Beginning in CiviCRM v5.4, the cache instance complies with
  46    *   PSR-16 (\Psr\SimpleCache\CacheInterface).
  47    */
  48   public static function cache($name = 'default') {
  49     return \Civi\Core\Container::singleton()->get('cache.' . $name);
  50   }
  51
  52   /**
  53    * Get the service container.
  54    *
  55    * @return \Symfony\Component\DependencyInjection\ContainerInterface
  56    */
  57   public static function container() {
  58     return Civi\Core\Container::singleton();
  59   }
  60
  61   /**
  62    * Get the event dispatcher.
  63    *
  64    * @return \Symfony\Component\EventDispatcher\EventDispatcherInterface
  65    */
  66   public static function dispatcher() {
  67     // NOTE: The dispatcher object is initially created as a boot service
  68     // (ie `dispatcher.boot`). For compatibility with the container (eg
  69     // `RegisterListenersPass` and `createEventDispatcher` addons),
  70     // it is also available as the `dispatcher` service.
  71     //
  72     // The 'dispatcher.boot' and 'dispatcher' services are the same object,
  73     // but 'dispatcher.boot' is resolvable earlier during bootstrap.
  74     return Civi\Core\Container::getBootService('dispatcher.boot');
  75   }
  76
  77   /**
  78    * @return \Civi\Core\Lock\LockManager
  79    */
  80   public static function lockManager() {
  81     return \Civi\Core\Container::getBootService('lockManager');
  82   }
  83
  84   /**
  85    * Find or create a logger.
  86    *
  87    * @param string $channel
  88    *   Symbolic name (or channel) of the intended log.
  89    *   This should correlate to a service "log.{NAME}".
  90    *
  91    * @return \Psr\Log\LoggerInterface
  92    */
  93   public static function log($channel = 'default') {
  94     return \Civi\Core\Container::singleton()->get('psr_log_manager')->getLog($channel);
  95   }
  96
  97   /**
  98    * Obtain the core file/path mapper.
  99    *
 100    * @return \Civi\Core\Paths
 101    */
 102   public static function paths() {
 103     return \Civi\Core\Container::getBootService('paths');
 104   }
 105
 106   /**
 107    * Fetch a service from the container.
 108    *
 109    * @param string $id
 110    *   The service ID.
 111    * @return mixed
 112    */
 113   public static function service($id) {
 114     return \Civi\Core\Container::singleton()->get($id);
 115   }
 116
 117   /**
 118    * Reset all ephemeral system state, e.g. statics,
 119    * singletons, containers.
 120    */
 121   public static function reset() {
 122     self::$statics = [];
 123     Civi\Core\Container::singleton();
 124   }
 125
 126   /**
 127    * @return CRM_Core_Resources
 128    */
 129   public static function resources() {
 130     return CRM_Core_Resources::singleton();
 131   }
 132
 133   /**
 134    * Obtain the contact's personal settings.
 135    *
 136    * @param NULL|int $contactID
 137    *   For the default/active user's contact, leave $domainID as NULL.
 138    * @param NULL|int $domainID
 139    *   For the default domain, leave $domainID as NULL.
 140    * @return \Civi\Core\SettingsBag
 141    * @throws CRM_Core_Exception
 142    *   If there is no contact, then there's no SettingsBag, and we'll throw
 143    *   an exception.
 144    */
 145   public static function contactSettings($contactID = NULL, $domainID = NULL) {
 146     return \Civi\Core\Container::getBootService('settings_manager')->getBagByContact($domainID, $contactID);
 147   }
 148
 149   /**
 150    * Obtain the domain settings.
 151    *
 152    * @param int|null $domainID
 153    *   For the default domain, leave $domainID as NULL.
 154    * @return \Civi\Core\SettingsBag
 155    */
 156   public static function settings($domainID = NULL) {
 157     return \Civi\Core\Container::getBootService('settings_manager')->getBagByDomain($domainID);
 158   }
 159
 160 }