3 +--------------------------------------------------------------------+
4 | CiviCRM version 4.7 |
5 +--------------------------------------------------------------------+
6 | Copyright CiviCRM LLC (c) 2004-2015 |
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-2015
33 class CRM_Core_OptionGroup
{
34 static $_values = array();
35 static $_cache = array();
38 * $_domainIDGroups array maintains the list of option groups for whom
39 * domainID is to be considered.
41 static $_domainIDGroups = array(
47 * @param CRM_Core_DAO $dao
49 * @param bool $grouping
50 * @param bool $localize
51 * @param string $valueColumnName
55 public static function &valuesCommon(
56 $dao, $flip = FALSE, $grouping = FALSE,
57 $localize = FALSE, $valueColumnName = 'label'
59 self
::$_values = array();
61 while ($dao->fetch()) {
64 self
::$_values[$dao->value
] = $dao->grouping
;
67 self
::$_values[$dao->{$valueColumnName}] = $dao->value
;
72 self
::$_values[$dao->{$valueColumnName}] = $dao->grouping
;
75 self
::$_values[$dao->value
] = $dao->{$valueColumnName};
80 $i18n = CRM_Core_I18n
::singleton();
81 $i18n->localizeArray(self
::$_values);
83 return self
::$_values;
87 * This function retrieves all the values for the specific option group by name
88 * this is primarily used to create various html based form elements
89 * (radio, select, checkbox etc). OptionGroups for most cases have the
90 * 'label' in the label column and the 'id' or 'name' in the value column
93 * name of the option group.
95 * results are return in id => label format if false.
96 * if true, the results are reversed
97 * @param bool $grouping
98 * if true, return the value in 'grouping' column.
99 * @param bool $localize
100 * if true, localize the results before returning.
101 * @param string $condition
102 * add another condition to the sql query.
103 * @param string $labelColumnName
104 * the column to use for 'label'.
105 * @param bool $onlyActive
106 * return only the action option values.
108 * ignore cache entries and go back to DB.
109 * @param string $keyColumnName
110 * the column to use for 'key'.
113 * the values as specified by the above params
116 public static function &values(
117 $name, $flip = FALSE, $grouping = FALSE,
118 $localize = FALSE, $condition = NULL,
119 $labelColumnName = 'label', $onlyActive = TRUE, $fresh = FALSE, $keyColumnName = 'value'
121 $cache = CRM_Utils_Cache
::singleton();
122 $cacheKey = self
::createCacheKey($name, $flip, $grouping, $localize, $condition, $labelColumnName, $onlyActive, $keyColumnName);
125 // Fetch from static var
126 if (array_key_exists($cacheKey, self
::$_cache)) {
127 return self
::$_cache[$cacheKey];
129 // Fetch from main cache
130 $var = $cache->get($cacheKey);
137 SELECT v.{$labelColumnName} as {$labelColumnName} ,v.{$keyColumnName} as value, v.grouping as grouping
138 FROM civicrm_option_value v,
139 civicrm_option_group g
140 WHERE v.option_group_id = g.id
142 AND g.is_active = 1 ";
145 $query .= " AND v.is_active = 1 ";
147 if (in_array($name, self
::$_domainIDGroups)) {
148 $query .= " AND v.domain_id = " . CRM_Core_Config
::domainID();
152 $query .= $condition;
155 $query .= " ORDER BY v.weight";
157 $p = array(1 => array($name, 'String'));
158 $dao = CRM_Core_DAO
::executeQuery($query, $p);
160 $var = self
::valuesCommon($dao, $flip, $grouping, $localize, $labelColumnName);
162 // call option value hook
163 CRM_Utils_Hook
::optionValues($var, $name);
165 self
::$_cache[$cacheKey] = $var;
166 $cache->set($cacheKey, $var);
172 * Counterpart to values() which removes the item from the cache
174 * @param string $name
179 * @param string $labelColumnName
181 * @param string $keyColumnName
183 protected static function flushValues($name, $flip, $grouping, $localize, $condition, $labelColumnName, $onlyActive, $keyColumnName = 'value') {
184 $cacheKey = self
::createCacheKey($name, $flip, $grouping, $localize, $condition, $labelColumnName, $onlyActive, $keyColumnName);
185 $cache = CRM_Utils_Cache
::singleton();
186 $cache->delete($cacheKey);
187 unset(self
::$_cache[$cacheKey]);
193 protected static function createCacheKey() {
194 $cacheKey = "CRM_OG_" . serialize(func_get_args());
199 * This function retrieves all the values for the specific option group by id.
200 * this is primarily used to create various html based form elements
201 * (radio, select, checkbox etc). OptionGroups for most cases have the
202 * 'label' in the label column and the 'id' or 'name' in the value column
205 * id of the option group.
207 * results are return in id => label format if false.
208 * if true, the results are reversed
209 * @param bool $grouping
210 * if true, return the value in 'grouping' column.
211 * @param bool $localize
212 * if true, localize the results before returning.
213 * @param string $labelColumnName
214 * the column to use for 'label'.
215 * @param bool $onlyActive
219 * Array of values as specified by the above params
222 public static function &valuesByID($id, $flip = FALSE, $grouping = FALSE, $localize = FALSE, $labelColumnName = 'label', $onlyActive = TRUE, $fresh = FALSE) {
223 $cacheKey = self
::createCacheKey($id, $flip, $grouping, $localize, $labelColumnName, $onlyActive);
225 $cache = CRM_Utils_Cache
::singleton();
227 $var = $cache->get($cacheKey);
233 SELECT v.{$labelColumnName} as {$labelColumnName} ,v.value as value, v.grouping as grouping
234 FROM civicrm_option_value v,
235 civicrm_option_group g
236 WHERE v.option_group_id = g.id
241 $query .= " AND v.is_active = 1 ";
243 $query .= " ORDER BY v.weight, v.label";
245 $p = array(1 => array($id, 'Integer'));
246 $dao = CRM_Core_DAO
::executeQuery($query, $p);
248 $var = self
::valuesCommon($dao, $flip, $grouping, $localize, $labelColumnName);
249 $cache->set($cacheKey, $var);
255 * Lookup titles OR ids for a set of option_value populated fields. The retrieved value
256 * is assigned a new fieldname by id or id's by title
257 * (each within a specificied option_group)
259 * @param array $params
260 * Reference array of values submitted by the form. Based on.
261 * $flip, creates new elements in $params for each field in
263 * If $flip = false, adds root field name => title
264 * If $flip = true, adds actual field name => id
266 * @param array $names
267 * Reference array of fieldnames we want transformed.
268 * Array key = 'postName' (field name submitted by form in $params).
269 * Array value = array('newName' => $newName, 'groupName' => $groupName).
274 public static function lookupValues(&$params, &$names, $flip = FALSE) {
275 foreach ($names as $postName => $value) {
276 // See if $params field is in $names array (i.e. is a value that we need to lookup)
277 if ($postalName = CRM_Utils_Array
::value($postName, $params)) {
278 $postValues = array();
279 // params[$postName] may be a Ctrl+A separated value list
280 if (is_string($postalName) &&
281 strpos($postalName, CRM_Core_DAO
::VALUE_SEPARATOR
) == FALSE
283 // eliminate the ^A frm the beginning and end if present
284 if (substr($postalName, 0, 1) == CRM_Core_DAO
::VALUE_SEPARATOR
) {
285 $params[$postName] = substr($params[$postName], 1, -1);
287 $postValues = explode(CRM_Core_DAO
::VALUE_SEPARATOR
, $params[$postName]);
289 elseif (is_array($postalName)) {
290 $postValues = $postalName;
293 foreach ($postValues as $postValue) {
299 $p = array(1 => array($postValue, 'String'));
300 $lookupBy = 'v.label= %1';
304 $p = array(1 => array($postValue, 'Integer'));
305 $lookupBy = 'v.value = %1';
309 $p[2] = array($value['groupName'], 'String');
312 FROM civicrm_option_value v,
313 civicrm_option_group g
314 WHERE v.option_group_id = g.id
318 $newValue[] = CRM_Core_DAO
::singleValueQuery($query, $p);
319 $newValue = str_replace(',', '_', $newValue);
321 $params[$value['newName']] = implode(', ', $newValue);
327 * @deprecated - use CRM_Core_Pseudoconstant::getLabel
329 * @param string $groupName
331 * @param bool $onlyActiveValue
335 public static function getLabel($groupName, $value, $onlyActiveValue = TRUE) {
336 if (empty($groupName) ||
343 SELECT v.label as label ,v.value as value
344 FROM civicrm_option_value v,
345 civicrm_option_group g
346 WHERE v.option_group_id = g.id
351 if ($onlyActiveValue) {
352 $query .= " AND v.is_active = 1 ";
355 1 => array($groupName, 'String'),
356 2 => array($value, 'Integer'),
358 $dao = CRM_Core_DAO
::executeQuery($query, $p);
366 * @param string $groupName
368 * @param string $labelField
369 * @param string $labelType
370 * @param string $valueField
374 public static function getValue(
377 $labelField = 'label',
378 $labelType = 'String',
379 $valueField = 'value'
386 SELECT v.label as label ,v.{$valueField} as value
387 FROM civicrm_option_value v,
388 civicrm_option_group g
389 WHERE v.option_group_id = g.id
393 AND v.$labelField = %2
397 1 => array($groupName, 'String'),
398 2 => array($label, $labelType),
400 $dao = CRM_Core_DAO
::executeQuery($query, $p);
410 * Get option_value.value from default option_value row for an option group
412 * @param string $groupName
413 * The name of the option group.
417 * the value from the row where is_default = true
419 public static function getDefaultValue($groupName) {
420 if (empty($groupName)) {
425 FROM civicrm_option_value v,
426 civicrm_option_group g
427 WHERE v.option_group_id = g.id
433 if (in_array($groupName, self
::$_domainIDGroups)) {
434 $query .= " AND v.domain_id = " . CRM_Core_Config
::domainID();
437 $p = array(1 => array($groupName, 'String'));
438 return CRM_Core_DAO
::singleValueQuery($query, $p);
442 * Creates a new option group with the passed in values.
443 * @TODO: Should update the group if it already exists intelligently, so multi-lingual is
444 * not messed up. Currently deletes the old group
446 * @param string $groupName
447 * The name of the option group - make sure there is no conflict.
448 * @param array $values
449 * The associative array that has information on the option values.
450 * the keys of this array are:
451 * string 'title' (required)
452 * string 'value' (required)
453 * string 'name' (optional)
454 * string 'description' (optional)
455 * int 'weight' (optional) - the order in which the value are displayed
456 * bool 'is_default' (optional) - is this the default one to display when rendered in form
457 * bool 'is_active' (optional) - should this element be rendered
458 * @param int $defaultID
459 * (reference) - the option value ID of the default element (if set) is returned else 'null'.
460 * @param null $groupTitle
461 * The optional label of the option group else set to group name.
465 * the option group ID
467 public static function createAssoc($groupName, &$values, &$defaultID, $groupTitle = NULL) {
468 self
::deleteAssoc($groupName);
469 if (!empty($values)) {
470 $group = new CRM_Core_DAO_OptionGroup();
471 $group->name
= $groupName;
472 $group->title
= empty($groupTitle) ?
$groupName : $groupTitle;
473 $group->is_reserved
= 1;
474 $group->is_active
= 1;
477 foreach ($values as $v) {
478 $value = new CRM_Core_DAO_OptionValue();
479 $value->option_group_id
= $group->id
;
480 $value->label
= $v['label'];
481 $value->value
= $v['value'];
482 $value->name
= CRM_Utils_Array
::value('name', $v);
483 $value->description
= CRM_Utils_Array
::value('description', $v);
484 $value->weight
= CRM_Utils_Array
::value('weight', $v);
485 $value->is_default
= CRM_Utils_Array
::value('is_default', $v);
486 $value->is_active
= CRM_Utils_Array
::value('is_active', $v);
489 if ($value->is_default
) {
490 $defaultID = $value->id
;
495 return $defaultID = 'null';
502 * @param string $groupName
505 * @param string $field
507 public static function getAssoc($groupName, &$values, $flip = FALSE, $field = 'name') {
509 SELECT v.id as amount_id, v.value, v.label, v.name, v.description, v.weight
510 FROM civicrm_option_group g,
511 civicrm_option_value v
512 WHERE g.id = v.option_group_id
516 $params = array(1 => array($groupName, 'String'));
517 $dao = CRM_Core_DAO
::executeQuery($query, $params);
519 $fields = array('value', 'label', 'name', 'description', 'amount_id', 'weight');
524 foreach ($fields as $field) {
525 $values[$field] = array();
530 while ($dao->fetch()) {
533 foreach ($fields as $field) {
534 $value[$field] = $dao->$field;
536 $values[$dao->amount_id
] = $value;
539 foreach ($fields as $field) {
540 $values[$field][$index] = $dao->$field;
548 * @param string $groupName
549 * @param string $operator
551 public static function deleteAssoc($groupName, $operator = "=") {
554 FROM civicrm_option_group g,
555 civicrm_option_value v
556 WHERE g.id = v.option_group_id
557 AND g.name {$operator} %1";
559 $params = array(1 => array($groupName, 'String'));
561 $dao = CRM_Core_DAO
::executeQuery($query, $params);
565 * @param string $groupName
567 * @param string $field
568 * @param string $fieldType
569 * @param bool $active
570 * @param bool $localize
571 * if true, localize the results before returning.
575 public static function getRowValues(
576 $groupName, $fieldValue, $field = 'name',
577 $fieldType = 'String', $active = TRUE, $localize = FALSE
580 SELECT v.id, v.label, v.value, v.name, v.weight, v.description
581 FROM civicrm_option_value v,
582 civicrm_option_group g
583 WHERE v.option_group_id = g.id
590 $query .= " AND v.is_active = 1";
594 1 => array($groupName, 'String'),
595 2 => array($fieldValue, $fieldType),
597 $dao = CRM_Core_DAO
::executeQuery($query, $p);
609 $row[$fld] = $dao->$fld;
610 if ($localize && in_array($fld, array('label', 'description'))) {
611 $row[$fld] = ts($row[$fld]);
620 * Wrapper for calling values with fresh set to true to empty the given value.
622 * Since there appears to be some inconsistency
623 * (@todo remove inconsistency) around the pseudoconstant operations
624 * (for example CRM_Contribution_Pseudoconstant::paymentInstrument doesn't specify isActive
625 * which is part of the cache key
626 * will do a couple of variations & aspire to someone cleaning it up later
628 * @param string $name
629 * @param array $params
631 public static function flush($name, $params = array()) {
637 'labelColumnName' => 'label',
640 $params = array_merge($defaults, $params);
646 $params['condition'],
647 $params['labelColumnName'],
656 $params['condition'],
657 $params['labelColumnName'],
663 public static function flushAll() {
664 self
::$_values = array();
665 self
::$_cache = array();
666 CRM_Utils_Cache
::singleton()->flush();