3 +--------------------------------------------------------------------+
4 | CiviCRM version 4.4 |
5 +--------------------------------------------------------------------+
6 | Copyright CiviCRM LLC (c) 2004-2013 |
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-2013
35 class CRM_Core_OptionGroup
{
36 static $_values = array();
37 static $_cache = array();
40 * $_domainIDGroups array maintains the list of option groups for whom
41 * domainID is to be considered.
44 static $_domainIDGroups = array(
49 static function &valuesCommon(
50 $dao, $flip = FALSE, $grouping = FALSE,
51 $localize = FALSE, $valueColumnName = 'label'
53 self
::$_values = array();
55 while ($dao->fetch()) {
58 self
::$_values[$dao->value
] = $dao->grouping
;
61 self
::$_values[$dao->{$valueColumnName}] = $dao->value
;
66 self
::$_values[$dao->{$valueColumnName}] = $dao->grouping
;
69 self
::$_values[$dao->value
] = $dao->{$valueColumnName};
74 $i18n = CRM_Core_I18n
::singleton();
75 $i18n->localizeArray(self
::$_values);
77 return self
::$_values;
81 * This function retrieves all the values for the specific option group by name
82 * this is primarily used to create various html based form elements
83 * (radio, select, checkbox etc). OptionGroups for most cases have the
84 * 'label' in the label colum and the 'id' or 'name' in the value column
86 * @param $name string name of the option group
87 * @param $flip boolean results are return in id => label format if false
88 * if true, the results are reversed
89 * @param $grouping boolean if true, return the value in 'grouping' column
90 * @param $localize boolean if true, localize the results before returning
91 * @param $condition string add another condition to the sql query
92 * @param $labelColumnName string the column to use for 'label'
93 * @param $onlyActive boolean return only the action option values
94 * @param $fresh boolean ignore cache entries and go back to DB
95 * @param $keyColumnName string the column to use for 'key'
97 * @return array the values as specified by the above params
101 static function &values(
102 $name, $flip = FALSE, $grouping = FALSE,
103 $localize = FALSE, $condition = NULL,
104 $labelColumnName = 'label', $onlyActive = TRUE, $fresh = FALSE, $keyColumnName = 'value'
106 $cache = CRM_Utils_Cache
::singleton();
107 $cacheKey = self
::createCacheKey($name, $flip, $grouping, $localize, $condition, $labelColumnName, $onlyActive, $keyColumnName);
110 // Fetch from static var
111 if (array_key_exists($cacheKey, self
::$_cache)) {
112 return self
::$_cache[$cacheKey];
114 // Fetch from main cache
115 $var = $cache->get($cacheKey);
122 SELECT v.{$labelColumnName} as {$labelColumnName} ,v.{$keyColumnName} as value, v.grouping as grouping
123 FROM civicrm_option_value v,
124 civicrm_option_group g
125 WHERE v.option_group_id = g.id
127 AND g.is_active = 1 ";
130 $query .= " AND v.is_active = 1 ";
132 if (in_array($name, self
::$_domainIDGroups)) {
133 $query .= " AND v.domain_id = " . CRM_Core_Config
::domainID();
137 $query .= $condition;
140 $query .= " ORDER BY v.weight";
142 $p = array(1 => array($name, 'String'));
143 $dao = CRM_Core_DAO
::executeQuery($query, $p);
145 $var = self
::valuesCommon($dao, $flip, $grouping, $localize, $labelColumnName);
147 // call option value hook
148 CRM_Utils_Hook
::optionValues($var, $name);
150 self
::$_cache[$cacheKey] = $var;
151 $cache->set($cacheKey, $var);
157 * Counterpart to values() which removes the item from the cache
164 * @param $labelColumnName
167 protected static function flushValues($name, $flip, $grouping, $localize, $condition, $labelColumnName, $onlyActive, $keyColumnName = 'value') {
168 $cacheKey = self
::createCacheKey($name, $flip, $grouping, $localize, $condition, $labelColumnName, $onlyActive, $keyColumnName);
169 $cache = CRM_Utils_Cache
::singleton();
170 $cache->delete($cacheKey);
171 unset(self
::$_cache[$cacheKey]);
174 protected static function createCacheKey() {
175 $cacheKey = "CRM_OG_" . serialize(func_get_args());
180 * This function retrieves all the values for the specific option group by id
181 * this is primarily used to create various html based form elements
182 * (radio, select, checkbox etc). OptionGroups for most cases have the
183 * 'label' in the label colum and the 'id' or 'name' in the value column
185 * @param $id integer id of the option group
186 * @param $flip boolean results are return in id => label format if false
187 * if true, the results are reversed
188 * @param $grouping boolean if true, return the value in 'grouping' column
189 * @param $localize boolean if true, localize the results before returning
190 * @param $labelColumnName string the column to use for 'label'
192 * @return array the values as specified by the above params
196 static function &valuesByID($id, $flip = FALSE, $grouping = FALSE, $localize = FALSE, $labelColumnName = 'label', $onlyActive = TRUE, $fresh = FALSE) {
197 $cacheKey = self
::createCacheKey($id, $flip, $grouping, $localize, $labelColumnName, $onlyActive);
199 $cache = CRM_Utils_Cache
::singleton();
201 $var = $cache->get($cacheKey);
207 SELECT v.{$labelColumnName} as {$labelColumnName} ,v.value as value, v.grouping as grouping
208 FROM civicrm_option_value v,
209 civicrm_option_group g
210 WHERE v.option_group_id = g.id
215 $query .= " AND v.is_active = 1 ";
217 $query .= " ORDER BY v.weight, v.label";
219 $p = array(1 => array($id, 'Integer'));
220 $dao = CRM_Core_DAO
::executeQuery($query, $p);
222 $var = self
::valuesCommon($dao, $flip, $grouping, $localize, $labelColumnName);
223 $cache->set($cacheKey, $var);
229 * Function to lookup titles OR ids for a set of option_value populated fields. The retrieved value
230 * is assigned a new fieldname by id or id's by title
231 * (each within a specificied option_group)
233 * @param array $params Reference array of values submitted by the form. Based on
234 * $flip, creates new elements in $params for each field in
236 * If $flip = false, adds root field name => title
237 * If $flip = true, adds actual field name => id
239 * @param array $names Reference array of fieldnames we want transformed.
240 * Array key = 'postName' (field name submitted by form in $params).
241 * Array value = array(
242 'newName' => $newName, 'groupName' => $groupName).
245 * @param boolean $flip
252 static function lookupValues(&$params, &$names, $flip = FALSE) {
253 foreach ($names as $postName => $value) {
254 // See if $params field is in $names array (i.e. is a value that we need to lookup)
255 if ($postalName = CRM_Utils_Array
::value($postName, $params)) {
256 $postValues = array();
257 // params[$postName] may be a Ctrl+A separated value list
258 if (is_string($postalName) &&
259 strpos($postalName, CRM_Core_DAO
::VALUE_SEPARATOR
) == FALSE
261 // eliminate the ^A frm the beginning and end if present
262 if (substr($postalName, 0, 1) == CRM_Core_DAO
::VALUE_SEPARATOR
) {
263 $params[$postName] = substr($params[$postName], 1, -1);
265 $postValues = explode(CRM_Core_DAO
::VALUE_SEPARATOR
, $params[$postName]);
267 elseif (is_array($postalName)) {
268 $postValues = $postalName;
271 foreach ($postValues as $postValue) {
277 $p = array(1 => array($postValue, 'String'));
278 $lookupBy = 'v.label= %1';
282 $p = array(1 => array($postValue, 'Integer'));
283 $lookupBy = 'v.value = %1';
287 $p[2] = array($value['groupName'], 'String');
290 FROM civicrm_option_value v,
291 civicrm_option_group g
292 WHERE v.option_group_id = g.id
296 $newValue[] = CRM_Core_DAO
::singleValueQuery($query, $p);
297 $newValue = str_replace(',', '_', $newValue);
299 $params[$value['newName']] = implode(', ', $newValue);
304 static function getLabel($groupName, $value, $onlyActiveValue = TRUE) {
305 if (empty($groupName) ||
312 SELECT v.label as label ,v.value as value
313 FROM civicrm_option_value v,
314 civicrm_option_group g
315 WHERE v.option_group_id = g.id
320 if ($onlyActiveValue) {
321 $query .= " AND v.is_active = 1 ";
323 $p = array(1 => array($groupName, 'String'),
324 2 => array($value, 'Integer'),
326 $dao = CRM_Core_DAO
::executeQuery($query, $p);
333 static function getValue($groupName,
335 $labelField = 'label',
336 $labelType = 'String',
337 $valueField = 'value'
344 SELECT v.label as label ,v.{$valueField} as value
345 FROM civicrm_option_value v,
346 civicrm_option_group g
347 WHERE v.option_group_id = g.id
351 AND v.$labelField = %2
354 $p = array(1 => array($groupName, 'String'),
355 2 => array($label, $labelType),
357 $dao = CRM_Core_DAO
::executeQuery($query, $p);
367 * Get option_value.value from default option_value row for an option group
369 * @param string $groupName the name of the option group
374 * @return string the value from the row where is_default = true
376 static function getDefaultValue($groupName) {
377 if (empty($groupName)) {
382 FROM civicrm_option_value v,
383 civicrm_option_group g
384 WHERE v.option_group_id = g.id
390 if (in_array($groupName, self
::$_domainIDGroups)) {
391 $query .= " AND v.domain_id = " . CRM_Core_Config
::domainID();
394 $p = array(1 => array($groupName, 'String'));
395 return CRM_Core_DAO
::singleValueQuery($query, $p);
399 * Creates a new option group with the passed in values
400 * @TODO: Should update the group if it already exists intelligently, so multi-lingual is
401 * not messed up. Currently deletes the old group
403 * @param string $groupName the name of the option group - make sure there is no conflict
404 * @param array $values the associative array that has information on the option values
405 * the keys of this array are:
406 * string 'title' (required)
407 * string 'value' (required)
408 * string 'name' (optional)
409 * string 'description' (optional)
410 * int 'weight' (optional) - the order in which the value are displayed
411 * bool 'is_default' (optional) - is this the default one to display when rendered in form
412 * bool 'is_active' (optional) - should this element be rendered
413 * @param int $defaultID (reference) - the option value ID of the default element (if set) is returned else 'null'
414 * @param string $groupLabel - the optional label of the option group else set to group name
419 * @return int the option group ID
422 static function createAssoc($groupName, &$values, &$defaultID, $groupTitle = NULL) {
423 self
::deleteAssoc($groupName);
424 if (!empty($values)) {
425 $group = new CRM_Core_DAO_OptionGroup();
426 $group->name
= $groupName;
427 $group->title
= empty($groupTitle) ?
$groupName : $groupTitle;
428 $group->is_reserved
= 1;
429 $group->is_active
= 1;
432 foreach ($values as $v) {
433 $value = new CRM_Core_DAO_OptionValue();
434 $value->option_group_id
= $group->id
;
435 $value->label
= $v['label'];
436 $value->value
= $v['value'];
437 $value->name
= CRM_Utils_Array
::value('name', $v);
438 $value->description
= CRM_Utils_Array
::value('description', $v);
439 $value->weight
= CRM_Utils_Array
::value('weight', $v);
440 $value->is_default
= CRM_Utils_Array
::value('is_default', $v);
441 $value->is_active
= CRM_Utils_Array
::value('is_active', $v);
444 if ($value->is_default
) {
445 $defaultID = $value->id
;
450 return $defaultID = 'null';
456 static function getAssoc($groupName, &$values, $flip = FALSE, $field = 'name') {
458 SELECT v.id as amount_id, v.value, v.label, v.name, v.description, v.weight
459 FROM civicrm_option_group g,
460 civicrm_option_value v
461 WHERE g.id = v.option_group_id
465 $params = array(1 => array($groupName, 'String'));
466 $dao = CRM_Core_DAO
::executeQuery($query, $params);
468 $fields = array('value', 'label', 'name', 'description', 'amount_id', 'weight');
473 foreach ($fields as $field) {
474 $values[$field] = array();
479 while ($dao->fetch()) {
482 foreach ($fields as $field) {
483 $value[$field] = $dao->$field;
485 $values[$dao->amount_id
] = $value;
488 foreach ($fields as $field) {
489 $values[$field][$index] = $dao->$field;
496 static function deleteAssoc($groupName, $operator = "=") {
499 FROM civicrm_option_group g,
500 civicrm_option_value v
501 WHERE g.id = v.option_group_id
502 AND g.name {$operator} %1";
504 $params = array(1 => array($groupName, 'String'));
506 $dao = CRM_Core_DAO
::executeQuery($query, $params);
509 static function optionLabel($groupName, $value) {
512 FROM civicrm_option_group g,
513 civicrm_option_value v
514 WHERE g.id = v.option_group_id
517 $params = array(1 => array($groupName, 'String'),
518 2 => array($value, 'String'),
520 return CRM_Core_DAO
::singleValueQuery($query, $params);
523 static function getRowValues($groupName, $fieldValue, $field = 'name',
524 $fieldType = 'String', $active = TRUE
527 SELECT v.id, v.label, v.value, v.name, v.weight, v.description
528 FROM civicrm_option_value v,
529 civicrm_option_group g
530 WHERE v.option_group_id = g.id
537 $query .= " AND v.is_active = 1";
540 $p = array(1 => array($groupName, 'String'),
541 2 => array($fieldValue, $fieldType),
543 $dao = CRM_Core_DAO
::executeQuery($query, $p);
548 'id', 'name', 'value', 'label', 'weight', 'description') as $fld) {
549 $row[$fld] = $dao->$fld;
556 * Wrapper for calling values with fresh set to true to empty the given value
558 * Since there appears to be some inconsistency
559 * (@todo remove inconsistency) around the pseudoconstant operations
560 * (for example CRM_Contribution_Pseudoconstant::paymentInstrument doesn't specify isActive
561 * which is part of the cache key
562 * will do a couple of variations & aspire to someone cleaning it up later
564 static function flush($name, $params = array()){
570 'labelColumnName' => 'label',
573 $params = array_merge($defaults, $params);
579 $params['condition'],
580 $params['labelColumnName'],
589 $params['condition'],
590 $params['labelColumnName'],
596 static function flushAll() {
597 self
::$_values = array();
598 self
::$_cache = array();
599 CRM_Utils_Cache
::singleton()->flush();