3 +--------------------------------------------------------------------+
4 | Copyright CiviCRM LLC. All rights reserved. |
6 | This work is published under the GNU AGPLv3 license with some |
7 | permitted exceptions and without any warranty. For full license |
8 | and copyright information, see https://civicrm.org/licensing |
9 +--------------------------------------------------------------------+
15 * Class SettingsManager
18 * The SettingsManager is responsible for tracking settings across various
21 * Generally, for any given setting, there are three levels where values
24 * - Mandatory values (which come from a global $civicrm_setting).
25 * - Explicit values (which are chosen by the user and stored in the DB).
26 * - Default values (which come from the settings metadata).
28 * Note: During the early stages of bootstrap, default values are not be available.
29 * Loading the defaults requires loading metadata from various sources. However,
30 * near the end of bootstrap, one calls SettingsManager::useDefaults() to fetch
31 * and merge the defaults.
33 * Note: In a typical usage, there will only be one active domain and one
34 * active contact (each having its own bag) within a given request. However,
35 * in some edge-cases, you may need to work with multiple domains/contacts
38 * Note: The global $civicrm_setting is meant to provide sysadmins with a way
39 * to override settings in `civicrm.settings.php`, but it has traditionally been
40 * possible for extensions to manipulate $civicrm_setting in a hook. If you do
41 * this, please call `useMandatory()` to tell SettingsManager to re-scan
44 * @see SettingsManagerTest
46 class SettingsManager
{
49 * @var \CRM_Utils_Cache_Interface
55 * Array (int $id => SettingsBag $bag).
57 protected $bagsByDomain = [];
62 * Array (int $id => SettingsBag $bag).
64 protected $bagsByContact = [];
68 * Array(string $entity => array(string $settingName => mixed $value)).
69 * Ex: $mandatory['domain']['uploadDir'].
70 * NULL means "autoload from $civicrm_setting".
72 protected $mandatory = NULL;
75 * Whether to use defaults.
79 protected $useDefaults = FALSE;
82 * @param \CRM_Utils_Cache_Interface $cache
83 * A semi-durable location to store metadata.
85 public function __construct($cache) {
86 $this->cache
= $cache;
90 * Ensure that all defaults values are included with
91 * all current and future bags.
93 * @return SettingsManager
95 public function useDefaults() {
96 if (!$this->useDefaults
) {
97 $this->useDefaults
= TRUE;
99 if (!empty($this->bagsByDomain
)) {
100 foreach ($this->bagsByDomain
as $bag) {
101 /** @var SettingsBag $bag */
102 $bag->loadDefaults($this->getDefaults('domain'));
106 if (!empty($this->bagsByContact
)) {
107 foreach ($this->bagsByContact
as $bag) {
108 /** @var SettingsBag $bag */
109 $bag->loadDefaults($this->getDefaults('contact'));
118 * Ensure that mandatory values are included with
119 * all current and future bags.
121 * If you call useMandatory multiple times, it will
122 * re-scan the global $civicrm_setting.
124 * @return SettingsManager
126 public function useMandatory() {
127 $this->mandatory
= NULL;
129 foreach ($this->bagsByDomain
as $bag) {
130 /** @var SettingsBag $bag */
131 $bag->loadMandatory($this->getMandatory('domain'));
134 foreach ($this->bagsByContact
as $bag) {
135 /** @var SettingsBag $bag */
136 $bag->loadMandatory($this->getMandatory('contact'));
143 * Get Settings by domain.
145 * @param int|null $domainId
147 * @return SettingsBag
149 public function getBagByDomain($domainId) {
150 if ($domainId === NULL) {
151 $domainId = \CRM_Core_Config
::domainID();
154 if (!isset($this->bagsByDomain
[$domainId])) {
155 $this->bagsByDomain
[$domainId] = new SettingsBag($domainId, NULL);
156 if (\CRM_Core_Config
::singleton()->dsn
) {
157 $this->bagsByDomain
[$domainId]->loadValues();
159 $this->bagsByDomain
[$domainId]
160 ->loadMandatory($this->getMandatory('domain'))
161 ->loadDefaults($this->getDefaults('domain'));
163 return $this->bagsByDomain
[$domainId];
167 * Get Settings by contact.
169 * @param int|null $domainId
170 * For the default domain, leave $domainID as NULL.
171 * @param int|null $contactId
172 * For the default/active user's contact, leave $domainID as NULL.
174 * @return SettingsBag
175 * @throws \CRM_Core_Exception
176 * If there is no contact, then there's no SettingsBag, and we'll throw
179 public function getBagByContact($domainId, $contactId) {
180 if ($domainId === NULL) {
181 $domainId = \CRM_Core_Config
::domainID();
183 if ($contactId === NULL) {
184 $contactId = \CRM_Core_Session
::getLoggedInContactID();
186 throw new \
CRM_Core_Exception("Cannot access settings subsystem - user or domain is unavailable");
190 $key = "$domainId:$contactId";
191 if (!isset($this->bagsByContact
[$key])) {
192 $this->bagsByContact
[$key] = new SettingsBag($domainId, $contactId);
193 if (\CRM_Core_Config
::singleton()->dsn
) {
194 $this->bagsByContact
[$key]->loadValues();
196 $this->bagsByContact
[$key]
197 ->loadDefaults($this->getDefaults('contact'))
198 ->loadMandatory($this->getMandatory('contact'));
200 return $this->bagsByContact
[$key];
204 * Determine the default settings.
206 * @param string $entity
207 * Ex: 'domain' or 'contact'.
209 * Array(string $settingName => mixed $value).
211 protected function getDefaults($entity) {
212 if (!$this->useDefaults
) {
213 return self
::getSystemDefaults($entity);
216 $cacheKey = 'defaults_' . $entity;
217 $defaults = $this->cache
->get($cacheKey);
218 if (!is_array($defaults)) {
219 $specs = SettingsMetadata
::getMetadata([
220 'is_contact' => ($entity === 'contact' ?
1 : 0),
223 foreach ($specs as $key => $spec) {
224 $defaults[$key] = $spec['default'] ??
NULL;
226 \CRM_Utils_Array
::extend($defaults, self
::getSystemDefaults($entity));
227 $this->cache
->set($cacheKey, $defaults);
233 * Get a list of mandatory/overriden settings.
235 * @param string $entity
236 * Ex: 'domain' or 'contact'.
238 * Array(string $settingName => mixed $value).
240 protected function getMandatory($entity) {
241 if ($this->mandatory
=== NULL) {
242 $this->mandatory
= self
::parseMandatorySettings(\CRM_Utils_Array
::value('civicrm_setting', $GLOBALS));
244 return $this->mandatory
[$entity];
248 * Parse mandatory settings.
250 * In previous versions, settings were broken down into verbose+dynamic group names, e.g.
252 * $civicrm_settings['Foo Bar Preferences']['foo'] = 'bar';
254 * We now simplify to two simple groups, 'domain' and 'contact'.
256 * $civicrm_settings['domain']['foo'] = 'bar';
258 * However, the old groups are grand-fathered in as aliases.
260 * @param array $civicrm_setting
261 * Ex: $civicrm_setting['Group Name']['field'] = 'value'.
262 * Group names are an historical quirk; ignore them.
265 public static function parseMandatorySettings($civicrm_setting) {
272 //\CRM_Core_BAO_Setting::ADDRESS_STANDARDIZATION_PREFERENCES_NAME => 'domain',
273 //\CRM_Core_BAO_Setting::CAMPAIGN_PREFERENCES_NAME => 'domain',
274 //\CRM_Core_BAO_Setting::CONTRIBUTE_PREFERENCES_NAME => 'domain',
275 //\CRM_Core_BAO_Setting::DEVELOPER_PREFERENCES_NAME => 'domain',
276 //\CRM_Core_BAO_Setting::DIRECTORY_PREFERENCES_NAME => 'domain',
277 //\CRM_Core_BAO_Setting::EVENT_PREFERENCES_NAME => 'domain',
278 //\CRM_Core_BAO_Setting::LOCALIZATION_PREFERENCES_NAME => 'domain',
279 //\CRM_Core_BAO_Setting::MAILING_PREFERENCES_NAME => 'domain',
280 //\CRM_Core_BAO_Setting::MAP_PREFERENCES_NAME => 'domain',
281 //\CRM_Core_BAO_Setting::MEMBER_PREFERENCES_NAME => 'domain',
282 //\CRM_Core_BAO_Setting::MULTISITE_PREFERENCES_NAME => 'domain',
283 //\CRM_Core_BAO_Setting::PERSONAL_PREFERENCES_NAME => 'contact',
284 'Personal Preferences' => 'contact',
285 //\CRM_Core_BAO_Setting::SEARCH_PREFERENCES_NAME => 'domain',
286 //\CRM_Core_BAO_Setting::SYSTEM_PREFERENCES_NAME => 'domain',
287 //\CRM_Core_BAO_Setting::URL_PREFERENCES_NAME => 'domain',
288 'domain' => 'domain',
289 'contact' => 'contact',
292 if (is_array($civicrm_setting)) {
293 foreach ($civicrm_setting as $oldGroup => $values) {
294 $newGroup = $rewriteGroups[$oldGroup] ??
'domain';
295 $result[$newGroup] = array_merge($result[$newGroup], $values);
302 * Flush all in-memory and persistent caches related to settings.
304 * @return SettingsManager
306 public function flush() {
307 $this->mandatory
= NULL;
309 $this->cache
->flush();
310 // SettingsMetadata; not guaranteed to use same cache.
311 \Civi
::cache('settings')->flush();
313 foreach ($this->bagsByDomain
as $bag) {
314 /** @var SettingsBag $bag */
316 $bag->loadDefaults($this->getDefaults('domain'));
317 $bag->loadMandatory($this->getMandatory('domain'));
320 foreach ($this->bagsByContact
as $bag) {
321 /** @var SettingsBag $bag */
323 $bag->loadDefaults($this->getDefaults('contact'));
324 $bag->loadMandatory($this->getMandatory('contact'));
331 * Get a list of critical system defaults.
333 * The setting system can be modified by extensions, which means that it's not fully available
334 * during bootstrap -- in particular, defaults cannot be loaded. For a very small number of settings,
335 * we must define defaults before the system bootstraps.
337 * @param string $entity
341 private static function getSystemDefaults($entity) {
346 'installed' => FALSE,
347 'enable_components' => ['CiviEvent', 'CiviContribute', 'CiviMember', 'CiviMail', 'CiviReport', 'CiviPledge'],
348 'customFileUploadDir' => '[civicrm.files]/custom/',
349 'imageUploadDir' => '[civicrm.files]/persist/contribute/',
350 'uploadDir' => '[civicrm.files]/upload/',
351 'imageUploadURL' => '[civicrm.files]/persist/contribute/',
352 'extensionsDir' => '[civicrm.files]/ext/',
353 'extensionsURL' => '[civicrm.files]/ext/',
354 'resourceBase' => '[civicrm.root]/',
355 'userFrameworkResourceURL' => '[civicrm.root]/',