| 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 | * Obtain the formatting object. |
| 110 | * |
| 111 | * @return \Civi\Core\Format |
| 112 | */ |
| 113 | public static function format(): Format { |
| 114 | return new Civi\Core\Format(); |
| 115 | } |
| 116 | |
| 117 | /** |
| 118 | * Fetch a service from the container. |
| 119 | * |
| 120 | * @param string $id |
| 121 | * The service ID. |
| 122 | * @return mixed |
| 123 | */ |
| 124 | public static function service($id) { |
| 125 | return \Civi\Core\Container::singleton()->get($id); |
| 126 | } |
| 127 | |
| 128 | /** |
| 129 | * Reset all ephemeral system state, e.g. statics, |
| 130 | * singletons, containers. |
| 131 | */ |
| 132 | public static function reset() { |
| 133 | self::$statics = []; |
| 134 | Civi\Core\Container::singleton(); |
| 135 | } |
| 136 | |
| 137 | /** |
| 138 | * @return CRM_Core_Resources |
| 139 | */ |
| 140 | public static function resources() { |
| 141 | return CRM_Core_Resources::singleton(); |
| 142 | } |
| 143 | |
| 144 | /** |
| 145 | * Obtain the contact's personal settings. |
| 146 | * |
| 147 | * @param NULL|int $contactID |
| 148 | * For the default/active user's contact, leave $domainID as NULL. |
| 149 | * @param NULL|int $domainID |
| 150 | * For the default domain, leave $domainID as NULL. |
| 151 | * @return \Civi\Core\SettingsBag |
| 152 | * @throws CRM_Core_Exception |
| 153 | * If there is no contact, then there's no SettingsBag, and we'll throw |
| 154 | * an exception. |
| 155 | */ |
| 156 | public static function contactSettings($contactID = NULL, $domainID = NULL) { |
| 157 | return \Civi\Core\Container::getBootService('settings_manager')->getBagByContact($domainID, $contactID); |
| 158 | } |
| 159 | |
| 160 | /** |
| 161 | * Obtain the domain settings. |
| 162 | * |
| 163 | * @param int|null $domainID |
| 164 | * For the default domain, leave $domainID as NULL. |
| 165 | * @return \Civi\Core\SettingsBag |
| 166 | */ |
| 167 | public static function settings($domainID = NULL) { |
| 168 | return \Civi\Core\Container::getBootService('settings_manager')->getBagByDomain($domainID); |
| 169 | } |
| 170 | |
| 171 | } |