Commit | Line | Data |
---|---|---|
711aa5d7 TO |
1 | <?php |
2 | ||
386fe6c2 EM |
3 | use Civi\Core\Format; |
4 | ||
711aa5d7 TO |
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. | |
683bf891 | 23 | * @var array |
0b882a86 | 24 | * ``` |
711aa5d7 | 25 | * `Civi::$statics[__CLASS__]['foo'] = 'bar'; |
0b882a86 | 26 | * ``` |
711aa5d7 | 27 | */ |
affcc9d2 | 28 | public static $statics = []; |
711aa5d7 | 29 | |
7b5937fe | 30 | /** |
ebf0eb53 | 31 | * Retrieve a named cache instance. |
7b5937fe TO |
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. | |
90cdaa0e TO |
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 | * | |
7b5937fe | 46 | * @return CRM_Utils_Cache_Interface |
ebf0eb53 TO |
47 | * NOTE: Beginning in CiviCRM v5.4, the cache instance complies with |
48 | * PSR-16 (\Psr\SimpleCache\CacheInterface). | |
7b5937fe TO |
49 | */ |
50 | public static function cache($name = 'default') { | |
51 | return \Civi\Core\Container::singleton()->get('cache.' . $name); | |
52 | } | |
53 | ||
711aa5d7 TO |
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 | ||
9897fb1e TO |
63 | /** |
64 | * Get the event dispatcher. | |
65 | * | |
66 | * @return \Symfony\Component\EventDispatcher\EventDispatcherInterface | |
67 | */ | |
68 | public static function dispatcher() { | |
42ccedc7 TO |
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'); | |
9897fb1e TO |
77 | } |
78 | ||
83617886 TO |
79 | /** |
80 | * @return \Civi\Core\Lock\LockManager | |
81 | */ | |
82 | public static function lockManager() { | |
83 | return \Civi\Core\Container::getBootService('lockManager'); | |
84 | } | |
85 | ||
6e5ad5ee | 86 | /** |
c213eb51 TO |
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 | |
6e5ad5ee | 94 | */ |
c213eb51 TO |
95 | public static function log($channel = 'default') { |
96 | return \Civi\Core\Container::singleton()->get('psr_log_manager')->getLog($channel); | |
6e5ad5ee TO |
97 | } |
98 | ||
e3d28c74 TO |
99 | /** |
100 | * Obtain the core file/path mapper. | |
101 | * | |
102 | * @return \Civi\Core\Paths | |
103 | */ | |
104 | public static function paths() { | |
d4330c62 | 105 | return \Civi\Core\Container::getBootService('paths'); |
e3d28c74 TO |
106 | } |
107 | ||
8b5f2c50 TO |
108 | /** |
109 | * Fetch a queue object. | |
110 | * | |
688e3d8b TO |
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 | * | |
8b5f2c50 | 114 | * @param string $name |
688e3d8b TO |
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] | |
8b5f2c50 TO |
122 | * @return \CRM_Queue_Queue |
123 | * @see \CRM_Queue_Service | |
124 | */ | |
688e3d8b TO |
125 | public static function queue(string $name, array $params = []): CRM_Queue_Queue { |
126 | $defaults = ['reset' => FALSE, 'is_persistent' => TRUE]; | |
27bd58ef | 127 | $params = array_merge($defaults, $params, ['name' => $name]); |
688e3d8b | 128 | return CRM_Queue_Service::singleton()->create($params); |
8b5f2c50 TO |
129 | } |
130 | ||
386fe6c2 EM |
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 | ||
1e88220a TO |
140 | /** |
141 | * Initiate a bidirectional pipe for exchanging a series of multiple API requests. | |
142 | * | |
88d93265 TO |
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. | |
e98a5c1f TO |
150 | * |
151 | * The `Civi::pipe()` entry-point is designed to be amenable to shell orchestration (SSH/cv/drush/wp-cli/etc). | |
88d93265 | 152 | * The negotiation flags are therefore condensed to individual characters. |
e98a5c1f TO |
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. | |
88d93265 | 158 | * @see \Civi\Pipe\PipeSession |
1e88220a | 159 | */ |
88d93265 TO |
160 | public static function pipe(string $negotiationFlags = 'vtl'): void { |
161 | Civi::service('civi.pipe') | |
5e13f388 | 162 | ->setIO(STDIN, STDOUT) |
88d93265 | 163 | ->run($negotiationFlags); |
1e88220a TO |
164 | } |
165 | ||
711aa5d7 TO |
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() { | |
affcc9d2 | 182 | self::$statics = []; |
7f835399 | 183 | Civi\Core\Container::singleton(); |
711aa5d7 TO |
184 | } |
185 | ||
e3d28c74 TO |
186 | /** |
187 | * @return CRM_Core_Resources | |
188 | */ | |
189 | public static function resources() { | |
190 | return CRM_Core_Resources::singleton(); | |
191 | } | |
192 | ||
01d70c56 TO |
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 | ||
3a84c0ab TO |
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) { | |
83617886 | 217 | return \Civi\Core\Container::getBootService('settings_manager')->getBagByDomain($domainID); |
3a84c0ab TO |
218 | } |
219 | ||
711aa5d7 | 220 | } |