| 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 | * @return \CRM_Core_Error_Log |
| 86 | */ |
| 87 | public static function log() { |
| 88 | return Civi\Core\Container::singleton()->get('psr_log'); |
| 89 | } |
| 90 | |
| 91 | /** |
| 92 | * Obtain the core file/path mapper. |
| 93 | * |
| 94 | * @return \Civi\Core\Paths |
| 95 | */ |
| 96 | public static function paths() { |
| 97 | return \Civi\Core\Container::getBootService('paths'); |
| 98 | } |
| 99 | |
| 100 | /** |
| 101 | * Fetch a service from the container. |
| 102 | * |
| 103 | * @param string $id |
| 104 | * The service ID. |
| 105 | * @return mixed |
| 106 | */ |
| 107 | public static function service($id) { |
| 108 | return \Civi\Core\Container::singleton()->get($id); |
| 109 | } |
| 110 | |
| 111 | /** |
| 112 | * Reset all ephemeral system state, e.g. statics, |
| 113 | * singletons, containers. |
| 114 | */ |
| 115 | public static function reset() { |
| 116 | self::$statics = []; |
| 117 | Civi\Core\Container::singleton(); |
| 118 | } |
| 119 | |
| 120 | /** |
| 121 | * @return CRM_Core_Resources |
| 122 | */ |
| 123 | public static function resources() { |
| 124 | return CRM_Core_Resources::singleton(); |
| 125 | } |
| 126 | |
| 127 | /** |
| 128 | * Obtain the contact's personal settings. |
| 129 | * |
| 130 | * @param NULL|int $contactID |
| 131 | * For the default/active user's contact, leave $domainID as NULL. |
| 132 | * @param NULL|int $domainID |
| 133 | * For the default domain, leave $domainID as NULL. |
| 134 | * @return \Civi\Core\SettingsBag |
| 135 | * @throws CRM_Core_Exception |
| 136 | * If there is no contact, then there's no SettingsBag, and we'll throw |
| 137 | * an exception. |
| 138 | */ |
| 139 | public static function contactSettings($contactID = NULL, $domainID = NULL) { |
| 140 | return \Civi\Core\Container::getBootService('settings_manager')->getBagByContact($domainID, $contactID); |
| 141 | } |
| 142 | |
| 143 | /** |
| 144 | * Obtain the domain settings. |
| 145 | * |
| 146 | * @param int|null $domainID |
| 147 | * For the default domain, leave $domainID as NULL. |
| 148 | * @return \Civi\Core\SettingsBag |
| 149 | */ |
| 150 | public static function settings($domainID = NULL) { |
| 151 | return \Civi\Core\Container::getBootService('settings_manager')->getBagByDomain($domainID); |
| 152 | } |
| 153 | |
| 154 | } |