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 +--------------------------------------------------------------------+
18 * Read and write settings for a given domain (or contact).
20 * If the target entity does not already have a value for the setting, then
21 * the defaults will be used. If mandatory values are provided, they will
22 * override any defaults or custom settings.
24 * It's expected that the SettingsBag will have O(50-250) settings -- and that
25 * we'll load the full bag on many page requests. Consequently, we don't
26 * want the full metadata (help text and version history and HTML widgets)
27 * for all 250 settings, but we do need the default values.
29 * This class is not usually instantiated directly. Instead, use SettingsManager
30 * or Civi::settings().
32 * @see \Civi::settings()
33 * @see SettingsManagerTest
43 * Array(string $settingName => mixed $value).
49 * Array(string $settingName => mixed $value).
54 * The result of combining default values, mandatory
55 * values, and user values.
58 * Array(string $settingName => mixed $value).
68 * @param int $domainId
69 * The domain for which we want settings.
70 * @param int|null $contactId
71 * The contact for which we want settings. Use NULL for domain settings.
73 public function __construct($domainId, $contactId) {
74 $this->domainId
= $domainId;
75 $this->contactId
= $contactId;
77 $this->combined
= NULL;
81 * Set/replace the default values.
83 * @param array $defaults
84 * Array(string $settingName => mixed $value).
87 public function loadDefaults($defaults) {
88 $this->defaults
= $defaults;
89 $this->combined
= NULL;
94 * Set/replace the mandatory values.
96 * @param array $mandatory
97 * Array(string $settingName => mixed $value).
100 public function loadMandatory($mandatory) {
101 $this->mandatory
= $mandatory;
102 $this->combined
= NULL;
107 * Load all explicit settings that apply to this domain or contact.
109 * @return SettingsBag
111 public function loadValues() {
112 // Note: Don't use DAO child classes. They require fields() which require
113 // translations -- which are keyed off settings!
116 $this->combined
= NULL;
118 // Ordinarily, we just load values from `civicrm_setting`. But upgrades require care.
119 // In v4.0 and earlier, all values were stored in `civicrm_domain.config_backend`.
120 // In v4.1-v4.6, values were split between `civicrm_domain` and `civicrm_setting`.
121 // In v4.7+, all values are stored in `civicrm_setting`.
122 // Whenever a value is available in civicrm_setting, it will take precedence.
124 $isUpgradeMode = \CRM_Core_Config
::isUpgradeMode();
126 if ($isUpgradeMode && empty($this->contactId
) && \CRM_Core_BAO_SchemaHandler
::checkIfFieldExists('civicrm_domain', 'config_backend', FALSE)) {
127 $config_backend = \CRM_Core_DAO
::singleValueQuery('SELECT config_backend FROM civicrm_domain WHERE id = %1',
128 [1 => [$this->domainId
, 'Positive']]);
129 $oldSettings = \CRM_Upgrade_Incremental_php_FourSeven
::convertBackendToSettings($this->domainId
, $config_backend);
130 \CRM_Utils_Array
::extend($this->values
, $oldSettings);
133 // Normal case. Aside: Short-circuit prevents unnecessary query.
134 if (!$isUpgradeMode || \CRM_Core_DAO
::checkTableExists('civicrm_setting')) {
135 $dao = \CRM_Core_DAO
::executeQuery($this->createQuery()->toSQL());
136 while ($dao->fetch()) {
137 $this->values
[$dao->name
] = ($dao->value
!== NULL) ? \CRM_Utils_String
::unserialize($dao->value
) : NULL;
145 * Add a batch of settings. Save them.
147 * @param array $settings
148 * Array(string $settingName => mixed $settingValue).
149 * @return SettingsBag
151 public function add(array $settings) {
152 foreach ($settings as $key => $value) {
153 $this->set($key, $value);
159 * Get a list of all effective settings.
162 * Array(string $settingName => mixed $settingValue).
164 public function all() {
165 if ($this->combined
=== NULL) {
166 $this->combined
= $this->combine(
167 [$this->defaults
, $this->values
, $this->mandatory
]
169 // computeVirtual() depends on completion of preceding pass.
170 $this->combined
= $this->combine(
171 [$this->combined
, $this->computeVirtual()]
174 return $this->combined
;
178 * Determine the effective value.
183 public function get($key) {
185 return $all[$key] ??
NULL;
189 * Determine the default value of a setting.
192 * The simple name of the setting.
195 public function getDefault($key) {
196 return $this->defaults
[$key] ??
NULL;
200 * Determine the explicitly designated value, regardless of
201 * any default or mandatory values.
204 * The simple name of the setting.
207 public function getExplicit($key) {
208 return ($this->values
[$key] ??
NULL);
212 * Determine the mandatory value of a setting.
215 * The simple name of the setting.
218 public function getMandatory($key) {
219 return $this->mandatory
[$key] ??
NULL;
223 * Determine if the entity has explicitly designated a value.
225 * Note that get() may still return other values based on
226 * mandatory values or defaults.
229 * The simple name of the setting.
232 public function hasExplict($key) {
233 // NULL means no designated value.
234 return isset($this->values
[$key]);
238 * Removes any explicit settings. This restores the default.
241 * The simple name of the setting.
242 * @return SettingsBag
244 public function revert($key) {
245 // It might be better to DELETE (to avoid long-term leaks),
246 // but setting NULL is simpler for now.
247 return $this->set($key, NULL);
251 * Add a single setting. Save it.
254 * The simple name of the setting.
255 * @param mixed $value
256 * The new, explicit value of the setting.
257 * @return SettingsBag
259 public function set($key, $value) {
260 if ($this->updateVirtual($key, $value)) {
263 $this->setDb($key, $value);
264 $this->values
[$key] = $value;
265 $this->combined
= NULL;
270 * Update a virtualized/deprecated setting.
272 * Temporary handling for phasing out contribution_invoice_settings.
274 * Until we have transitioned we need to handle setting & retrieving
275 * contribution_invoice_settings.
277 * Once removed from core we will add deprecation notices & then remove this.
279 * https://lab.civicrm.org/dev/core/issues/1558
282 * @param array $value
284 * TRUE if $key is a virtualized setting. FALSE if it is a normal setting.
286 public function updateVirtual($key, $value) {
287 if ($key === 'contribution_invoice_settings') {
288 foreach (SettingsBag
::getContributionInvoiceSettingKeys() as $possibleKeyName => $settingName) {
289 $keyValue = $value[$possibleKeyName] ??
'';
290 if ($possibleKeyName === 'invoicing' && is_array($keyValue)) {
291 $keyValue = $keyValue['invoicing'];
293 $this->set($settingName, $keyValue);
301 * Determine the values of any virtual/computed settings.
305 public function computeVirtual() {
306 $contributionSettings = [];
307 foreach (SettingsBag
::getContributionInvoiceSettingKeys() as $keyName => $settingName) {
310 $contributionSettings[$keyName] = $this->get($settingName) ?
[$keyName => 1] : 0;
314 $contributionSettings[$keyName] = $this->get($settingName);
318 return ['contribution_invoice_settings' => $contributionSettings];
322 * @return \CRM_Utils_SQL_Select
324 protected function createQuery() {
325 $select = \CRM_Utils_SQL_Select
::from('civicrm_setting')
326 ->select('id, name, value, domain_id, contact_id, is_domain, component_id, created_date, created_id')
327 ->where('domain_id = #id', [
328 'id' => $this->domainId
,
330 if ($this->contactId
=== NULL) {
331 $select->where('is_domain = 1');
334 $select->where('contact_id = #id', [
335 'id' => $this->contactId
,
337 $select->where('is_domain = 0');
343 * Combine a series of arrays, excluding any
344 * null values. Later values override earlier
347 * @param array $arrays
348 * List of arrays to combine.
351 protected function combine($arrays) {
353 foreach ($arrays as $array) {
354 foreach ($array as $k => $v) {
364 * Update the DB record for this setting.
366 * @param string $name
367 * The simple name of the setting.
368 * @param mixed $value
369 * The new value of the setting.
371 protected function setDb($name, $value) {
373 $fieldsToSet = \CRM_Core_BAO_Setting
::validateSettingsInput([$name => $value], $fields);
374 //We haven't traditionally validated inputs to setItem, so this breaks things.
375 //foreach ($fieldsToSet as $settingField => &$settingValue) {
376 // self::validateSetting($settingValue, $fields['values'][$settingField]);
379 $metadata = $fields['values'][$name];
381 $dao = new \
CRM_Core_DAO_Setting();
383 $dao->domain_id
= $this->domainId
;
384 if ($this->contactId
) {
385 $dao->contact_id
= $this->contactId
;
393 // Call 'on_change' listeners. It would be nice to only fire when there's
394 // a genuine change in the data. However, PHP developers have mixed
395 // expectations about whether 0, '0', '', NULL, and FALSE represent the same
396 // value, so there's no universal way to determine if a change is genuine.
397 if (isset($metadata['on_change'])) {
398 foreach ($metadata['on_change'] as $callback) {
400 \Civi\Core\Resolver
::singleton()->get($callback),
401 \CRM_Utils_String
::unserialize($dao->value
),
409 if (!is_array($value) && \CRM_Utils_System
::isNull($value)) {
410 $dao->value
= 'null';
413 $dao->value
= serialize($value);
416 if (!isset(\Civi
::$statics[__CLASS__
]['upgradeMode'])) {
417 \Civi
::$statics[__CLASS__
]['upgradeMode'] = \CRM_Core_Config
::isUpgradeMode();
419 if (\Civi
::$statics[__CLASS__
]['upgradeMode'] && \CRM_Core_BAO_SchemaHandler
::checkIfFieldExists('civicrm_setting', 'group_name')) {
420 $dao->group_name
= 'placeholder';
423 $dao->created_date
= \CRM_Utils_Time
::getTime('YmdHis');
425 $session = \CRM_Core_Session
::singleton();
426 if (\CRM_Contact_BAO_Contact_Utils
::isContactId($session->get('userID'))) {
427 $dao->created_id
= $session->get('userID');
434 // Cannot use $dao->save(); in upgrade mode (eg WP + Civi 4.4=>4.7), the DAO will refuse
435 // to save the field `group_name`, which is required in older schema.
436 \CRM_Core_DAO
::executeQuery(\CRM_Utils_SQL_Insert
::dao($dao)->toSQL());
443 public static function getContributionInvoiceSettingKeys(): array {
445 'credit_notes_prefix' => 'credit_notes_prefix',
446 'invoice_prefix' => 'invoice_prefix',
447 'due_date' => 'invoice_due_date',
448 'due_date_period' => 'invoice_due_date_period',
449 'notes' => 'invoice_notes',
450 'is_email_pdf' => 'invoice_is_email_pdf',
451 'tax_term' => 'tax_term',
452 'tax_display_settings' => 'tax_display_settings',
453 'invoicing' => 'invoicing',
455 return $convertedKeys;