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' => 'Sql', 'error' => 'abort']
 121    *   Example: ['type' => 'SqlParallel', 'error' => 'delete']
 122    *   Defaults: ['reset'=>FALSE, 'is_persistent'=>TRUE, 'is_autorun'=>FALSE]
 123    * @return \CRM_Queue_Queue
 124    * @see \CRM_Queue_Service
 125    */
 126   public static function queue(string $name, array $params = []): CRM_Queue_Queue {
 127     $defaults = ['reset' => FALSE, 'is_persistent' => TRUE, 'status' => 'active'];
 128     $params = array_merge($defaults, $params, ['name' => $name]);
 129     return CRM_Queue_Service::singleton()->create($params);
 130   }
 131
 132   /**
 133    * Obtain the formatting object.
 134    *
 135    * @return \Civi\Core\Format
 136    */
 137   public static function format(): Format {
 138     return new Civi\Core\Format();
 139   }
 140
 141   /**
 142    * Initiate a bidirectional pipe for exchanging a series of multiple API requests.
 143    *
 144    * @param string $negotiationFlags
 145    *   List of pipe initialization flags. Some combination of the following:
 146    *    - 'v': Report version in connection header.
 147    *    - 'j': Report JSON-RPC flavors in connection header.
 148    *    - 'l': Report on login support in connection header.
 149    *    - 't': Trusted session. Logins do not require credentials. API calls may execute with or without permission-checks.
 150    *    - 'u': Untrusted session. Logins require credentials. API calls may only execute with permission-checks.
 151    *
 152    *   The `Civi::pipe()` entry-point is designed to be amenable to shell orchestration (SSH/cv/drush/wp-cli/etc).
 153    *   The negotiation flags are therefore condensed to individual characters.
 154    *
 155    *   It is possible to preserve compatibility while adding new default-flags. However, removing default-flags
 156    *   is more likely to be a breaking-change.
 157    *
 158    *   When adding a new flag, consider whether mutable `option()`s may be more appropriate.
 159    * @see \Civi\Pipe\PipeSession
 160    */
 161   public static function pipe(string $negotiationFlags = 'vtl'): void {
 162     Civi::service('civi.pipe')
 163       ->setIO(STDIN, STDOUT)
 164       ->run($negotiationFlags);
 165   }
 166
 167   /**
 168    * Fetch a service from the container.
 169    *
 170    * @param string $id
 171    *   The service ID.
 172    * @return mixed
 173    */
 174   public static function service($id) {
 175     return \Civi\Core\Container::singleton()->get($id);
 176   }
 177
 178   /**
 179    * Reset all ephemeral system state, e.g. statics,
 180    * singletons, containers.
 181    */
 182   public static function reset() {
 183     self::$statics = [];
 184     Civi\Core\Container::singleton();
 185   }
 186
 187   /**
 188    * @return CRM_Core_Resources
 189    */
 190   public static function resources() {
 191     return CRM_Core_Resources::singleton();
 192   }
 193
 194   /**
 195    * Obtain the contact's personal settings.
 196    *
 197    * @param NULL|int $contactID
 198    *   For the default/active user's contact, leave $domainID as NULL.
 199    * @param NULL|int $domainID
 200    *   For the default domain, leave $domainID as NULL.
 201    * @return \Civi\Core\SettingsBag
 202    * @throws CRM_Core_Exception
 203    *   If there is no contact, then there's no SettingsBag, and we'll throw
 204    *   an exception.
 205    */
 206   public static function contactSettings($contactID = NULL, $domainID = NULL) {
 207     return \Civi\Core\Container::getBootService('settings_manager')->getBagByContact($domainID, $contactID);
 208   }
 209
 210   /**
 211    * Obtain the domain settings.
 212    *
 213    * @param int|null $domainID
 214    *   For the default domain, leave $domainID as NULL.
 215    * @return \Civi\Core\SettingsBag
 216    */
 217   public static function settings($domainID = NULL) {
 218     return \Civi\Core\Container::getBootService('settings_manager')->getBagByDomain($domainID);
 219   }
 220
 221 }