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.
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).
22 * A central location for static variable storage.
25 * `Civi::$statics[__CLASS__]['foo'] = 'bar';
28 public static $statics = [];
31 * Retrieve a named cache instance.
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.
46 * @return CRM_Utils_Cache_Interface
47 * NOTE: Beginning in CiviCRM v5.4, the cache instance complies with
48 * PSR-16 (\Psr\SimpleCache\CacheInterface).
50 public static function cache($name = 'default') {
51 return \Civi\Core\Container
::singleton()->get('cache.' . $name);
55 * Get the service container.
57 * @return \Symfony\Component\DependencyInjection\ContainerInterface
59 public static function container() {
60 return Civi\Core\Container
::singleton();
64 * Get the event dispatcher.
66 * @return \Symfony\Component\EventDispatcher\EventDispatcherInterface
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.
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');
80 * @return \Civi\Core\Lock\LockManager
82 public static function lockManager() {
83 return \Civi\Core\Container
::getBootService('lockManager');
87 * Find or create a logger.
89 * @param string $channel
90 * Symbolic name (or channel) of the intended log.
91 * This should correlate to a service "log.{NAME}".
93 * @return \Psr\Log\LoggerInterface
95 public static function log($channel = 'default') {
96 return \Civi\Core\Container
::singleton()->get('psr_log_manager')->getLog($channel);
100 * Obtain the core file/path mapper.
102 * @return \Civi\Core\Paths
104 public static function paths() {
105 return \Civi\Core\Container
::getBootService('paths');
109 * Obtain the formatting object.
111 * @return \Civi\Core\Format
113 public static function format(): Format
{
114 return new Civi\Core\
Format();
118 * Initiate a bidirectional pipe for exchanging a series of multiple API requests.
120 * @param string $negotiationFlags
121 * List of pipe initialization flags. Some combination of the following:
122 * - 'v': Report version in connection header.
123 * - 'j': Report JSON-RPC flavors in connection header.
124 * - 'l': Report on login support in connection header.
125 * - 't': Trusted session. Logins do not require credentials. API calls may execute with or without permission-checks.
126 * - 'u': Untrusted session. Logins require credentials. API calls may only execute with permission-checks.
128 * The `Civi::pipe()` entry-point is designed to be amenable to shell orchestration (SSH/cv/drush/wp-cli/etc).
129 * The negotiation flags are therefore condensed to individual characters.
131 * It is possible to preserve compatibility while adding new default-flags. However, removing default-flags
132 * is more likely to be a breaking-change.
134 * When adding a new flag, consider whether mutable `option()`s may be more appropriate.
135 * @see \Civi\Pipe\PipeSession
137 public static function pipe(string $negotiationFlags = 'vtl'): void
{
138 Civi
::service('civi.pipe')
139 ->setIO(STDIN
, STDOUT
)
140 ->run($negotiationFlags);
144 * Fetch a service from the container.
150 public static function service($id) {
151 return \Civi\Core\Container
::singleton()->get($id);
155 * Reset all ephemeral system state, e.g. statics,
156 * singletons, containers.
158 public static function reset() {
160 Civi\Core\Container
::singleton();
164 * @return CRM_Core_Resources
166 public static function resources() {
167 return CRM_Core_Resources
::singleton();
171 * Obtain the contact's personal settings.
173 * @param NULL|int $contactID
174 * For the default/active user's contact, leave $domainID as NULL.
175 * @param NULL|int $domainID
176 * For the default domain, leave $domainID as NULL.
177 * @return \Civi\Core\SettingsBag
178 * @throws CRM_Core_Exception
179 * If there is no contact, then there's no SettingsBag, and we'll throw
182 public static function contactSettings($contactID = NULL, $domainID = NULL) {
183 return \Civi\Core\Container
::getBootService('settings_manager')->getBagByContact($domainID, $contactID);
187 * Obtain the domain settings.
189 * @param int|null $domainID
190 * For the default domain, leave $domainID as NULL.
191 * @return \Civi\Core\SettingsBag
193 public static function settings($domainID = NULL) {
194 return \Civi\Core\Container
::getBootService('settings_manager')->getBagByDomain($domainID);