Civi.php

   1 <?php
   2
   3 use Civi\Core\Format;
   4
   5 /**
   6  * Class Civi
   7  *
   8  * The "Civi" class provides a facade for accessing major subsystems,
   9  * such as the service-container and settings manager. It serves as a
  10  * bridge which allows procedural code to access important objects.
  11  *
  12  * General principles:
  13  *  - Each function provides access to a major subsystem.
  14  *  - Each function performs a simple lookup.
  15  *  - Each function returns an interface.
  16  *  - Whenever possible, interfaces should be well-known (e.g. based
  17  *    on a standard or well-regarded provider).
  18  */
  19 class Civi {
  20
  21   /**
  22    * A central location for static variable storage.
  23    * @var array
  24    * ```
  25    * `Civi::$statics[__CLASS__]['foo'] = 'bar';
  26    * ```
  27    */
  28   public static $statics = [];
  29
  30   /**
  31    * Retrieve a named cache instance.
  32    *
  33    * @param string $name
  34    *   The name of the cache. The 'default' cache is biased toward
  35    *   high-performance caches (eg memcache/redis/apc) when
  36    *   available and falls back to single-request (static) caching.
  37    *   Ex: 'short' or 'default' is useful for high-speed, short-lived cache data.
  38    *       This is appropriate if you believe that latency (millisecond-level
  39    *       read time) is the main factor. For example: caching data from
  40    *       a couple SQL queries.
  41    *   Ex: 'long' can be useful for longer-lived cache data. It's appropriate if
  42    *       you believe that longevity (e.g. surviving for several hours or a day)
  43    *       is more important than  millisecond-level access time. For example:
  44    *       caching the result of a simple metadata-query.
  45    *
  46    * @return CRM_Utils_Cache_Interface
  47    *   NOTE: Beginning in CiviCRM v5.4, the cache instance complies with
  48    *   PSR-16 (\Psr\SimpleCache\CacheInterface).
  49    */
  50   public static function cache($name = 'default') {
  51     return \Civi\Core\Container::singleton()->get('cache.' . $name);
  52   }
  53
  54   /**
  55    * Get the service container.
  56    *
  57    * @return \Symfony\Component\DependencyInjection\ContainerInterface
  58    */
  59   public static function container() {
  60     return Civi\Core\Container::singleton();
  61   }
  62
  63   /**
  64    * Get the event dispatcher.
  65    *
  66    * @return \Symfony\Component\EventDispatcher\EventDispatcherInterface
  67    */
  68   public static function dispatcher() {
  69     // NOTE: The dispatcher object is initially created as a boot service
  70     // (ie `dispatcher.boot`). For compatibility with the container (eg
  71     // `RegisterListenersPass` and `createEventDispatcher` addons),
  72     // it is also available as the `dispatcher` service.
  73     //
  74     // The 'dispatcher.boot' and 'dispatcher' services are the same object,
  75     // but 'dispatcher.boot' is resolvable earlier during bootstrap.
  76     return Civi\Core\Container::getBootService('dispatcher.boot');
  77   }
  78
  79   /**
  80    * @return \Civi\Core\Lock\LockManager
  81    */
  82   public static function lockManager() {
  83     return \Civi\Core\Container::getBootService('lockManager');
  84   }
  85
  86   /**
  87    * Find or create a logger.
  88    *
  89    * @param string $channel
  90    *   Symbolic name (or channel) of the intended log.
  91    *   This should correlate to a service "log.{NAME}".
  92    *
  93    * @return \Psr\Log\LoggerInterface
  94    */
  95   public static function log($channel = 'default') {
  96     return \Civi\Core\Container::singleton()->get('psr_log_manager')->getLog($channel);
  97   }
  98
  99   /**
 100    * Obtain the core file/path mapper.
 101    *
 102    * @return \Civi\Core\Paths
 103    */
 104   public static function paths() {
 105     return \Civi\Core\Container::getBootService('paths');
 106   }
 107
 108   /**
 109    * Fetch a queue object.
 110    *
 111    * Note: Historically, `CRM_Queue_Queue` objects were not persistently-registered. Persistence
 112    * is now encouraged. This facade has a bias towards persistently-registered queues.
 113    *
 114    * @param string $name
 115    *   The name of a persistent/registered queue (stored in `civicrm_queue`)
 116    * @param array{type: string, is_autorun: bool, reset: bool, is_persistent: bool} $params
 117    *   Specification for a queue.
 118    *   This is not required for accessing an existing queue.
 119    *   Specify this if you wish to auto-create the queue or to include advanced options (eg `reset`).
 120    *   Example: ['type' => 'SqlParallel']
 121    *   Defaults: ['reset'=>FALSE, 'is_persistent'=>TRUE, 'is_autorun'=>FALSE]
 122    * @return \CRM_Queue_Queue
 123    * @see \CRM_Queue_Service
 124    */
 125   public static function queue(string $name, array $params = []): CRM_Queue_Queue {
 126     $defaults = ['reset' => FALSE, 'is_persistent' => TRUE];
 127     $params = array_merge($defaults, $params, ['name' => $name]);
 128     return CRM_Queue_Service::singleton()->create($params);
 129   }
 130
 131   /**
 132    * Obtain the formatting object.
 133    *
 134    * @return \Civi\Core\Format
 135    */
 136   public static function format(): Format {
 137     return new Civi\Core\Format();
 138   }
 139
 140   /**
 141    * Initiate a bidirectional pipe for exchanging a series of multiple API requests.
 142    *
 143    * @param string $negotiationFlags
 144    *   List of pipe initialization flags. Some combination of the following:
 145    *    - 'v': Report version in connection header.
 146    *    - 'j': Report JSON-RPC flavors in connection header.
 147    *    - 'l': Report on login support in connection header.
 148    *    - 't': Trusted session. Logins do not require credentials. API calls may execute with or without permission-checks.
 149    *    - 'u': Untrusted session. Logins require credentials. API calls may only execute with permission-checks.
 150    *
 151    *   The `Civi::pipe()` entry-point is designed to be amenable to shell orchestration (SSH/cv/drush/wp-cli/etc).
 152    *   The negotiation flags are therefore condensed to individual characters.
 153    *
 154    *   It is possible to preserve compatibility while adding new default-flags. However, removing default-flags
 155    *   is more likely to be a breaking-change.
 156    *
 157    *   When adding a new flag, consider whether mutable `option()`s may be more appropriate.
 158    * @see \Civi\Pipe\PipeSession
 159    */
 160   public static function pipe(string $negotiationFlags = 'vtl'): void {
 161     Civi::service('civi.pipe')
 162       ->setIO(STDIN, STDOUT)
 163       ->run($negotiationFlags);
 164   }
 165
 166   /**
 167    * Fetch a service from the container.
 168    *
 169    * @param string $id
 170    *   The service ID.
 171    * @return mixed
 172    */
 173   public static function service($id) {
 174     return \Civi\Core\Container::singleton()->get($id);
 175   }
 176
 177   /**
 178    * Reset all ephemeral system state, e.g. statics,
 179    * singletons, containers.
 180    */
 181   public static function reset() {
 182     self::$statics = [];
 183     Civi\Core\Container::singleton();
 184   }
 185
 186   /**
 187    * @return CRM_Core_Resources
 188    */
 189   public static function resources() {
 190     return CRM_Core_Resources::singleton();
 191   }
 192
 193   /**
 194    * Obtain the contact's personal settings.
 195    *
 196    * @param NULL|int $contactID
 197    *   For the default/active user's contact, leave $domainID as NULL.
 198    * @param NULL|int $domainID
 199    *   For the default domain, leave $domainID as NULL.
 200    * @return \Civi\Core\SettingsBag
 201    * @throws CRM_Core_Exception
 202    *   If there is no contact, then there's no SettingsBag, and we'll throw
 203    *   an exception.
 204    */
 205   public static function contactSettings($contactID = NULL, $domainID = NULL) {
 206     return \Civi\Core\Container::getBootService('settings_manager')->getBagByContact($domainID, $contactID);
 207   }
 208
 209   /**
 210    * Obtain the domain settings.
 211    *
 212    * @param int|null $domainID
 213    *   For the default domain, leave $domainID as NULL.
 214    * @return \Civi\Core\SettingsBag
 215    */
 216   public static function settings($domainID = NULL) {
 217     return \Civi\Core\Container::getBootService('settings_manager')->getBagByDomain($domainID);
 218   }
 219
 220 }