forked from civicrm/civicrm-core
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Civi.php
331 lines (310 loc) · 12.3 KB
/
Civi.php
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
<?php
use Civi\Core\Format;
/**
* Class Civi
*
* The "Civi" class provides a facade for accessing major subsystems,
* such as the service-container and settings manager. It serves as a
* bridge which allows procedural code to access important objects.
*
* General principles:
* - Each function provides access to a major subsystem.
* - Each function performs a simple lookup.
* - Each function returns an interface.
* - Whenever possible, interfaces should be well-known (e.g. based
* on a standard or well-regarded provider).
*/
class Civi {
/**
* A central location for static variable storage.
* @var array
* ```
* `Civi::$statics[__CLASS__]['foo'] = 'bar';
* ```
*/
public static $statics = [];
/**
* Retrieve a named cache instance.
*
* @param string $name
* The name of the cache. The 'default' cache is biased toward
* high-performance caches (eg memcache/redis/apc) when
* available and falls back to single-request (static) caching.
* Ex: 'short' or 'default' is useful for high-speed, short-lived cache data.
* This is appropriate if you believe that latency (millisecond-level
* read time) is the main factor. For example: caching data from
* a couple SQL queries.
* Ex: 'long' can be useful for longer-lived cache data. It's appropriate if
* you believe that longevity (e.g. surviving for several hours or a day)
* is more important than millisecond-level access time. For example:
* caching the result of a simple metadata-query.
*
* @return CRM_Utils_Cache_Interface
* NOTE: Beginning in CiviCRM v5.4, the cache instance complies with
* PSR-16 (\Psr\SimpleCache\CacheInterface).
*/
public static function cache($name = 'default') {
return \Civi\Core\Container::singleton()->get('cache.' . $name);
}
/**
* Get the service container.
*
* @return \Symfony\Component\DependencyInjection\ContainerInterface
*/
public static function container() {
return Civi\Core\Container::singleton();
}
/**
* Get the event dispatcher.
*
* @return \Civi\Core\CiviEventDispatcherInterface
*/
public static function dispatcher() {
// NOTE: The dispatcher object is initially created as a boot service
// (ie `dispatcher.boot`). For compatibility with the container (eg
// `RegisterListenersPass` and `createEventDispatcher` addons),
// it is also available as the `dispatcher` service.
//
// The 'dispatcher.boot' and 'dispatcher' services are the same object,
// but 'dispatcher.boot' is resolvable earlier during bootstrap.
return Civi\Core\Container::getBootService('dispatcher.boot');
}
/**
* @return \Civi\Core\Lock\LockManager
*/
public static function lockManager() {
return \Civi\Core\Container::getBootService('lockManager');
}
/**
* Find or create a logger.
*
* @param string $channel
* Symbolic name (or channel) of the intended log.
* This should correlate to a service "log.{NAME}".
*
* @return \Psr\Log\LoggerInterface
*/
public static function log($channel = 'default') {
return \Civi\Core\Container::singleton()->get('psr_log_manager')->getLog($channel);
}
/**
* Obtain the core file/path mapper.
*
* @return \Civi\Core\Paths
*/
public static function paths() {
return \Civi\Core\Container::getBootService('paths');
}
/**
* Fetch a queue object.
*
* Note: Historically, `CRM_Queue_Queue` objects were not persistently-registered. Persistence
* is now encouraged. This facade has a bias towards persistently-registered queues.
*
* @param string $name
* The name of a persistent/registered queue (stored in `civicrm_queue`)
* @param array{type: string, is_autorun: bool, reset: bool, is_persistent: bool} $params
* Specification for a queue.
* This is not required for accessing an existing queue.
* Specify this if you wish to auto-create the queue or to include advanced options (eg `reset`).
* Example: ['type' => 'Sql', 'error' => 'abort']
* Example: ['type' => 'SqlParallel', 'error' => 'delete']
* Defaults: ['reset'=>FALSE, 'is_persistent'=>TRUE, 'is_autorun'=>FALSE]
* @return \CRM_Queue_Queue
* @see \CRM_Queue_Service
*/
public static function queue(string $name, array $params = []): CRM_Queue_Queue {
$defaults = ['reset' => FALSE, 'is_persistent' => TRUE, 'status' => 'active'];
$params = array_merge($defaults, $params, ['name' => $name]);
return CRM_Queue_Service::singleton()->create($params);
}
/**
* Obtain the formatting object.
*
* @return \Civi\Core\Format
*/
public static function format(): Format {
return new Civi\Core\Format();
}
/**
* Initiate a bidirectional pipe for exchanging a series of multiple API requests.
*
* @param string $negotiationFlags
* List of pipe initialization flags. Some combination of the following:
* - 'v': Report version in connection header.
* - 'j': Report JSON-RPC flavors in connection header.
* - 'l': Report on login support in connection header.
* - 't': Trusted session. Logins do not require credentials. API calls may execute with or without permission-checks.
* - 'u': Untrusted session. Logins require credentials. API calls may only execute with permission-checks.
*
* The `Civi::pipe()` entry-point is designed to be amenable to shell orchestration (SSH/cv/drush/wp-cli/etc).
* The negotiation flags are therefore condensed to individual characters.
*
* It is possible to preserve compatibility while adding new default-flags. However, removing default-flags
* is more likely to be a breaking-change.
*
* When adding a new flag, consider whether mutable `option()`s may be more appropriate.
* @see \Civi\Pipe\PipeSession
*/
public static function pipe(string $negotiationFlags = 'vtl'): void {
Civi::service('civi.pipe')
->setIO(STDIN, STDOUT)
->run($negotiationFlags);
}
/**
* Fetch a service from the container.
*
* @param string $id
* The service ID.
* @return mixed
*/
public static function service($id) {
return \Civi\Core\Container::singleton()->get($id);
}
/**
* Reset all ephemeral system state, e.g. statics,
* singletons, containers.
*/
public static function reset() {
self::$statics = [];
Civi\Core\Container::singleton();
}
/**
* @return CRM_Core_Resources
*/
public static function resources() {
return CRM_Core_Resources::singleton();
}
/**
* Obtain the contact's personal settings.
*
* @param NULL|int $contactID
* For the default/active user's contact, leave $domainID as NULL.
* @param NULL|int $domainID
* For the default domain, leave $domainID as NULL.
* @return \Civi\Core\SettingsBag
* @throws CRM_Core_Exception
* If there is no contact, then there's no SettingsBag, and we'll throw
* an exception.
*/
public static function contactSettings($contactID = NULL, $domainID = NULL) {
return \Civi\Core\Container::getBootService('settings_manager')->getBagByContact($domainID, $contactID);
}
/**
* Obtain the domain settings.
*
* @param int|null $domainID
* For the default domain, leave $domainID as NULL.
* @return \Civi\Core\SettingsBag
*/
public static function settings($domainID = NULL) {
return \Civi\Core\Container::getBootService('settings_manager')->getBagByDomain($domainID);
}
/**
* Construct a URL based on a logical service address. For example:
*
* Civi::url('frontend://civicrm/user?reset=1');
*
* Civi::url()
* ->setScheme('frontend')
* ->setPath(['civicrm', 'user'])
* ->setQuery(['reset' => 1])
*
* URL building follows a few rules:
*
* 1. You may initialize with a baseline URL.
* 2. The scheme indicates the general type of URL ('frontend://', 'backend://', 'asset://', 'assetBuilder://').
* 3. The result object provides getters, setters, and adders (e.g. `getScheme()`, `setPath(...)`, `addQuery(...)`)
* 4. Strings are raw. Arrays are auto-encoded. (`addQuery('name=John+Doughnut')` or `addQuery(['name' => 'John Doughnut'])`)
* 5. You may use variable expressions (`id=[contact]&gid=[profile]`).
* 6. The URL can be cast to string (aka `__toString()`).
*
* If you are converting from `CRM_Utils_System::url()` to `Civi::url()`, then be sure to:
*
* - Pay attention to the scheme (eg 'current://' vs 'frontend://')
* - Pay attention to HTML escaping, as the behavior changed:
* - Civi::url() returns plain URLs (eg "id=100&gid=200") by default
* - CRM_Utils_System::url() returns HTML-escaped URLs (eg "id=100&gid=200") by default
*
* Here are several examples:
*
* Ex: Link to constituent's dashboard (on frontend UI or backend UI -- based on the active scheme of current page-view)
* $url = Civi::url('current://civicrm/user?reset=1');
* $url = Civi::url('//civicrm/user?reset=1');
*
* Ex: Link to constituent's dashboard (with method calls - good for dynamic options)
* $url = Civi::url('frontend:')
* ->setPath('civicrm/user')
* ->addQuery(['reset' => 1]);
*
* Ex: Link to constituent's dashboard (with quick flags: absolute URL, SSL required, HTML escaping)
* $url = Civi::url('frontend://civicrm/user?reset=1', 'ash');
*
* Ex: Link to constituent's dashboard (with method flags - good for dynamic options)
* $url = Civi::url('frontend://civicrm/user?reset=1')
* ->setPreferFormat('absolute')
* ->setSsl(TRUE)
* ->setHtmlEscape(TRUE);
*
* Ex: Link to a dynamically generated asset-file.
* $url = Civi::url('assetBuilder://crm-l10n.js?locale=en_US');
*
* Ex: Link to a static asset (resource-file) in one of core's configurable paths.
* $url = Civi::url('[civicrm.root]/js/Common.js');
*
* Ex: Link to a static asset (resource-file) in an extension.
* $url = Civi::url('ext://org.civicrm.search_kit/css/crmSearchTasks.css');
*
* Ex: Link with variable substitution
* $url = Civi::url('frontend://civicrm/ajax/api4/[entity]/[action]')
* ->addVars(['entity' => 'Foo', 'action' => 'bar']);
*
* @param string|null $logicalUri
* Logical URI. The scheme of the URI may be one of:
* - 'frontend://' (Front-end page-route for constituents)
* - 'backend://' (Back-end page-route for staff)
* - 'service://' (Web-service page-route for automated integrations; aka webhooks and IPNs)
* - 'current://' (Whichever UI is currently active)
* - 'default://' (Whichever UI is recorded in the metadata)
* - 'asset://' (Static asset-file; see \Civi::paths())
* - 'assetBuilder://' (Dynamically-generated asset-file; see \Civi\Core\AssetBuilder)
* - 'ext://' (Static asset-file provided by an extension)
* An empty scheme (`//hello.txt`) is equivalent to `current://hello.txt`.
* @param string|null $flags
* List of flags. Some combination of the following:
* - 'a': absolute (aka `setPreferFormat('absolute')`)
* - 'r': relative (aka `setPreferFormat('relative')`)
* - 'h': html (aka `setHtmlEscape(TRUE)`)
* - 't': text (aka `setHtmlEscape(FALSE)`)
* - 's': ssl (aka `setSsl(TRUE)`)
* - 'c': cache code for resources (aka Civi::resources()->addCacheCode())
* @return \Civi\Core\Url
* URL object which may be modified or rendered as text.
*/
public static function url(?string $logicalUri = NULL, ?string $flags = NULL): \Civi\Core\Url {
return new \Civi\Core\Url($logicalUri, $flags);
}
/**
* Get the canonical entityProvider for a given entity type.
*
* @param string $entityName
* @return \Civi\Schema\EntityProvider
*/
public static function entity(string $entityName): \Civi\Schema\EntityProvider {
return new \Civi\Schema\EntityProvider($entityName);
}
/**
* Get the schema-helper for CiviCRM (core-core).
*
* @param string $key
* Ex: 'civicrm' or 'org.example.myextension'
* @return \CiviMix\Schema\SchemaHelperInterface
*/
public static function schemaHelper(string $key = 'civicrm'): \CiviMix\Schema\SchemaHelperInterface {
if (!isset(Civi::$statics['schemaHelper'])) {
pathload()->loadPackage('civimix-schema@5');
Civi::$statics['schemaHelper'] = TRUE;
}
return $GLOBALS['CiviMixSchema']->getHelper($key);
}
}