3 +--------------------------------------------------------------------+
5 +--------------------------------------------------------------------+
6 | Copyright CiviCRM LLC (c) 2004-2019 |
7 +--------------------------------------------------------------------+
8 | This file is a part of CiviCRM. |
10 | CiviCRM is free software; you can copy, modify, and distribute it |
11 | under the terms of the GNU Affero General Public License |
12 | Version 3, 19 November 2007 and the CiviCRM Licensing Exception. |
14 | CiviCRM is distributed in the hope that it will be useful, but |
15 | WITHOUT ANY WARRANTY; without even the implied warranty of |
16 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. |
17 | See the GNU Affero General Public License for more details. |
19 | You should have received a copy of the GNU Affero General Public |
20 | License and the CiviCRM Licensing Exception along |
21 | with this program; if not, contact CiviCRM LLC |
22 | at info[AT]civicrm[DOT]org. If you have questions about the |
23 | GNU Affero General Public License or the licensing of CiviCRM, |
24 | see the CiviCRM license FAQ at http://civicrm.org/licensing |
25 +--------------------------------------------------------------------+
31 * @copyright CiviCRM LLC (c) 2004-2019
33 class CRM_Core_OptionGroup
{
34 public static $_values = [];
35 public static $_cache = [];
38 * $_domainIDGroups array maintains the list of option groups for whom
39 * domainID is to be considered.
42 public static $_domainIDGroups = [
48 * @param CRM_Core_DAO $dao
50 * @param bool $grouping
51 * @param bool $localize
52 * @param string $valueColumnName
56 public static function &valuesCommon(
57 $dao, $flip = FALSE, $grouping = FALSE,
58 $localize = FALSE, $valueColumnName = 'label'
62 while ($dao->fetch()) {
65 self
::$_values[$dao->value
] = $dao->grouping
;
68 self
::$_values[$dao->{$valueColumnName}] = $dao->value
;
73 self
::$_values[$dao->{$valueColumnName}] = $dao->grouping
;
76 self
::$_values[$dao->value
] = $dao->{$valueColumnName};
81 $i18n = CRM_Core_I18n
::singleton();
82 $i18n->localizeArray(self
::$_values);
84 return self
::$_values;
88 * This function retrieves all the values for the specific option group by name
89 * this is primarily used to create various html based form elements
90 * (radio, select, checkbox etc). OptionGroups for most cases have the
91 * 'label' in the label column and the 'id' or 'name' in the value column
94 * name of the option group.
96 * results are return in id => label format if false.
97 * if true, the results are reversed
98 * @param bool $grouping
99 * if true, return the value in 'grouping' column.
100 * @param bool $localize
101 * if true, localize the results before returning.
102 * @param string $condition
103 * add another condition to the sql query.
104 * @param string $labelColumnName
105 * the column to use for 'label'.
106 * @param bool $onlyActive
107 * return only the action option values.
109 * ignore cache entries and go back to DB.
110 * @param string $keyColumnName
111 * the column to use for 'key'.
112 * @param string $orderBy
113 * the column to use for ordering.
116 * The values as specified by the params
118 public static function &values(
119 $name, $flip = FALSE, $grouping = FALSE,
120 $localize = FALSE, $condition = NULL,
121 $labelColumnName = 'label', $onlyActive = TRUE, $fresh = FALSE, $keyColumnName = 'value',
124 $cache = CRM_Utils_Cache
::singleton();
125 $cacheKey = self
::createCacheKey($name, $flip, $grouping, $localize, $condition, $labelColumnName, $onlyActive, $keyColumnName, $orderBy);
128 // Fetch from static var
129 if (array_key_exists($cacheKey, self
::$_cache)) {
130 return self
::$_cache[$cacheKey];
132 // Fetch from main cache
133 self
::$_cache[$cacheKey] = $cache->get($cacheKey);
134 if (self
::$_cache[$cacheKey] !== NULL) {
135 return self
::$_cache[$cacheKey];
140 SELECT v.{$labelColumnName} as {$labelColumnName} ,v.{$keyColumnName} as value, v.grouping as grouping
141 FROM civicrm_option_value v,
142 civicrm_option_group g
143 WHERE v.option_group_id = g.id
145 AND g.is_active = 1 ";
148 $query .= " AND v.is_active = 1 ";
149 // Only show options for enabled components
150 $componentClause = ' v.component_id IS NULL ';
151 $enabledComponents = CRM_Core_Config
::singleton()->enableComponents
;
152 if ($enabledComponents) {
153 $enabledComponents = '"' . implode('","', $enabledComponents) . '"';
154 $componentClause .= " OR v.component_id IN (SELECT id FROM civicrm_component WHERE name IN ($enabledComponents)) ";
156 $query .= " AND ($componentClause) ";
158 if (in_array($name, self
::$_domainIDGroups)) {
159 $query .= " AND v.domain_id = " . CRM_Core_Config
::domainID();
163 $query .= $condition;
166 $query .= " ORDER BY v.{$orderBy}";
168 $p = [1 => [$name, 'String']];
169 $dao = CRM_Core_DAO
::executeQuery($query, $p);
171 $var = self
::valuesCommon($dao, $flip, $grouping, $localize, $labelColumnName);
173 // call option value hook
174 CRM_Utils_Hook
::optionValues($var, $name);
176 self
::$_cache[$cacheKey] = $var;
177 $cache->set($cacheKey, $var);
183 * Counterpart to values() which removes the item from the cache
185 * @param string $name
190 * @param string $labelColumnName
192 * @param string $keyColumnName
194 protected static function flushValues($name, $flip, $grouping, $localize, $condition, $labelColumnName, $onlyActive, $keyColumnName = 'value') {
195 $cacheKey = self
::createCacheKey($name, $flip, $grouping, $localize, $condition, $labelColumnName, $onlyActive, $keyColumnName);
196 $cache = CRM_Utils_Cache
::singleton();
197 $cache->delete($cacheKey);
198 unset(self
::$_cache[$cacheKey]);
204 protected static function createCacheKey($id) {
205 $cacheKey = "CRM_OG_" . preg_replace('/[^a-zA-Z0-9]/', '', $id) . '_' . md5(serialize(func_get_args()));
210 * This function retrieves all the values for the specific option group by id.
211 * this is primarily used to create various html based form elements
212 * (radio, select, checkbox etc). OptionGroups for most cases have the
213 * 'label' in the label column and the 'id' or 'name' in the value column
216 * id of the option group.
218 * results are return in id => label format if false.
219 * if true, the results are reversed
220 * @param bool $grouping
221 * if true, return the value in 'grouping' column.
222 * @param bool $localize
223 * if true, localize the results before returning.
224 * @param string $labelColumnName
225 * the column to use for 'label'.
226 * @param bool $onlyActive
230 * Array of values as specified by the above params
233 public static function &valuesByID($id, $flip = FALSE, $grouping = FALSE, $localize = FALSE, $labelColumnName = 'label', $onlyActive = TRUE, $fresh = FALSE) {
234 $cacheKey = self
::createCacheKey($id, $flip, $grouping, $localize, $labelColumnName, $onlyActive);
236 $cache = CRM_Utils_Cache
::singleton();
238 self
::$_cache[$cacheKey] = $cache->get($cacheKey);
239 if (self
::$_cache[$cacheKey] !== NULL) {
240 return self
::$_cache[$cacheKey];
244 SELECT v.{$labelColumnName} as {$labelColumnName} ,v.value as value, v.grouping as grouping
245 FROM civicrm_option_value v,
246 civicrm_option_group g
247 WHERE v.option_group_id = g.id
252 $query .= " AND v.is_active = 1 ";
254 $query .= " ORDER BY v.weight, v.label";
256 $p = [1 => [$id, 'Integer']];
257 $dao = CRM_Core_DAO
::executeQuery($query, $p);
259 $var = self
::valuesCommon($dao, $flip, $grouping, $localize, $labelColumnName);
260 $cache->set($cacheKey, $var);
266 * Lookup titles OR ids for a set of option_value populated fields. The
267 * retrieved value is assigned a new field name by id or id's by title
268 * (each within a specified option_group).
270 * @param array $params
271 * Reference array of values submitted by the form. Based on.
272 * $flip, creates new elements in $params for each field in
274 * If $flip = false, adds root field name => title
275 * If $flip = true, adds actual field name => id
277 * @param array $names
278 * Array of field names we want transformed.
279 * Array key = 'postName' (field name submitted by form in $params).
280 * Array value = array('newName' => $newName, 'groupName' => $groupName).
284 public static function lookupValues(&$params, $names, $flip = FALSE) {
285 foreach ($names as $postName => $value) {
286 // See if $params field is in $names array (i.e. is a value that we need to lookup)
287 if ($postalName = CRM_Utils_Array
::value($postName, $params)) {
289 // params[$postName] may be a Ctrl+A separated value list
290 if (is_string($postalName) &&
291 strpos($postalName, CRM_Core_DAO
::VALUE_SEPARATOR
) == FALSE
293 // eliminate the ^A frm the beginning and end if present
294 if (substr($postalName, 0, 1) == CRM_Core_DAO
::VALUE_SEPARATOR
) {
295 $params[$postName] = substr($params[$postName], 1, -1);
297 $postValues = explode(CRM_Core_DAO
::VALUE_SEPARATOR
, $params[$postName]);
299 elseif (is_array($postalName)) {
300 $postValues = $postalName;
303 foreach ($postValues as $postValue) {
309 $p = [1 => [$postValue, 'String']];
310 $lookupBy = 'v.label= %1';
314 $p = [1 => [$postValue, 'Integer']];
315 $lookupBy = 'v.value = %1';
319 $p[2] = [$value['groupName'], 'String'];
322 FROM civicrm_option_value v,
323 civicrm_option_group g
324 WHERE v.option_group_id = g.id
328 $newValue[] = CRM_Core_DAO
::singleValueQuery($query, $p);
329 $newValue = str_replace(',', '_', $newValue);
331 $params[$value['newName']] = implode(', ', $newValue);
337 * @deprecated - use CRM_Core_PseudoConstant::getLabel
339 * @param string $groupName
341 * @param bool $onlyActiveValue
345 public static function getLabel($groupName, $value, $onlyActiveValue = TRUE) {
346 CRM_Core_Error
::deprecatedFunctionWarning('CRM_Core_PseudoConstant::getLabel');
347 if (empty($groupName) ||
354 SELECT v.label as label ,v.value as value
355 FROM civicrm_option_value v,
356 civicrm_option_group g
357 WHERE v.option_group_id = g.id
362 if ($onlyActiveValue) {
363 $query .= " AND v.is_active = 1 ";
366 1 => [$groupName, 'String'],
367 2 => [$value, 'Integer'],
369 $dao = CRM_Core_DAO
::executeQuery($query, $p);
379 * This function is not cached.
381 * @param string $groupName
383 * @param string $labelField
384 * @param string $labelType
385 * @param string $valueField
389 public static function getValue(
392 $labelField = 'label',
393 $labelType = 'String',
394 $valueField = 'value'
400 CRM_Core_Error
::deprecatedFunctionWarning('CRM_Core_PseudoConstant::getKey');
403 SELECT v.label as label ,v.{$valueField} as value
404 FROM civicrm_option_value v,
405 civicrm_option_group g
406 WHERE v.option_group_id = g.id
410 AND v.$labelField = %2
414 1 => [$groupName, 'String'],
415 2 => [$label, $labelType],
417 $dao = CRM_Core_DAO
::executeQuery($query, $p);
425 * Get option_value.value from default option_value row for an option group
427 * @param string $groupName
428 * The name of the option group.
432 * the value from the row where is_default = true
434 public static function getDefaultValue($groupName) {
435 if (empty($groupName)) {
440 FROM civicrm_option_value v,
441 civicrm_option_group g
442 WHERE v.option_group_id = g.id
448 if (in_array($groupName, self
::$_domainIDGroups)) {
449 $query .= " AND v.domain_id = " . CRM_Core_Config
::domainID();
452 $p = [1 => [$groupName, 'String']];
453 return CRM_Core_DAO
::singleValueQuery($query, $p);
457 * Creates a new option group with the passed in values.
458 * @TODO: Should update the group if it already exists intelligently, so multi-lingual is
459 * not messed up. Currently deletes the old group
461 * @param string $groupName
462 * The name of the option group - make sure there is no conflict.
463 * @param array $values
464 * The associative array that has information on the option values.
465 * the keys of this array are:
466 * string 'title' (required)
467 * string 'value' (required)
468 * string 'name' (optional)
469 * string 'description' (optional)
470 * int 'weight' (optional) - the order in which the value are displayed
471 * bool 'is_default' (optional) - is this the default one to display when rendered in form
472 * bool 'is_active' (optional) - should this element be rendered
473 * @param int $defaultID
474 * (reference) - the option value ID of the default element (if set) is returned else 'null'.
475 * @param null $groupTitle
476 * The optional label of the option group else set to group name.
480 * the option group ID
482 public static function createAssoc($groupName, &$values, &$defaultID, $groupTitle = NULL) {
483 self
::deleteAssoc($groupName);
484 if (!empty($values)) {
485 $group = new CRM_Core_DAO_OptionGroup();
486 $group->name
= $groupName;
487 $group->title
= empty($groupTitle) ?
$groupName : $groupTitle;
488 $group->is_reserved
= 1;
489 $group->is_active
= 1;
492 foreach ($values as $v) {
493 $value = new CRM_Core_DAO_OptionValue();
494 $value->option_group_id
= $group->id
;
495 $value->label
= $v['label'];
496 $value->value
= $v['value'];
497 $value->name
= CRM_Utils_Array
::value('name', $v);
498 $value->description
= CRM_Utils_Array
::value('description', $v);
499 $value->weight
= CRM_Utils_Array
::value('weight', $v);
500 $value->is_default
= CRM_Utils_Array
::value('is_default', $v);
501 $value->is_active
= CRM_Utils_Array
::value('is_active', $v);
504 if ($value->is_default
) {
505 $defaultID = $value->id
;
510 return $defaultID = 'null';
517 * @param string $groupName
520 * @param string $field
522 public static function getAssoc($groupName, &$values, $flip = FALSE, $field = 'name') {
524 SELECT v.id as amount_id, v.value, v.label, v.name, v.description, v.weight
525 FROM civicrm_option_group g,
526 civicrm_option_value v
527 WHERE g.id = v.option_group_id
531 $params = [1 => [$groupName, 'String']];
532 $dao = CRM_Core_DAO
::executeQuery($query, $params);
534 $fields = ['value', 'label', 'name', 'description', 'amount_id', 'weight'];
539 foreach ($fields as $field) {
540 $values[$field] = [];
545 while ($dao->fetch()) {
548 foreach ($fields as $field) {
549 $value[$field] = $dao->$field;
551 $values[$dao->amount_id
] = $value;
554 foreach ($fields as $field) {
555 $values[$field][$index] = $dao->$field;
563 * @param string $groupName
564 * @param string $operator
566 public static function deleteAssoc($groupName, $operator = "=") {
569 FROM civicrm_option_group g,
570 civicrm_option_value v
571 WHERE g.id = v.option_group_id
572 AND g.name {$operator} %1";
574 $params = [1 => [$groupName, 'String']];
576 $dao = CRM_Core_DAO
::executeQuery($query, $params);
580 * @param string $groupName
582 * @param string $field
583 * @param string $fieldType
584 * @param bool $active
585 * @param bool $localize
586 * if true, localize the results before returning.
590 public static function getRowValues(
591 $groupName, $fieldValue, $field = 'name',
592 $fieldType = 'String', $active = TRUE, $localize = FALSE
595 SELECT v.id, v.label, v.value, v.name, v.weight, v.description
596 FROM civicrm_option_value v,
597 civicrm_option_group g
598 WHERE v.option_group_id = g.id
605 $query .= " AND v.is_active = 1";
609 1 => [$groupName, 'String'],
610 2 => [$fieldValue, $fieldType],
612 $dao = CRM_Core_DAO
::executeQuery($query, $p);
624 $row[$fld] = $dao->$fld;
625 if ($localize && in_array($fld, ['label', 'description'])) {
626 $row[$fld] = ts($row[$fld]);
635 * Wrapper for calling values with fresh set to true to empty the given value.
637 * Since there appears to be some inconsistency
638 * (@todo remove inconsistency) around the pseudoconstant operations
639 * (for example CRM_Contribution_Pseudoconstant::paymentInstrument doesn't specify isActive
640 * which is part of the cache key
641 * will do a couple of variations & aspire to someone cleaning it up later
643 * @param string $name
644 * @param array $params
646 public static function flush($name, $params = []) {
652 'labelColumnName' => 'label',
655 $params = array_merge($defaults, $params);
661 $params['condition'],
662 $params['labelColumnName'],
671 $params['condition'],
672 $params['labelColumnName'],
679 * Flush all the places where option values are cached.
681 * Note that this is called from CRM_Core_PseudoConstant::flush() so we should resist
682 * the intuitive urge to flush that class.
684 public static function flushAll() {
687 CRM_Utils_Cache
::singleton()->flush();