CRM/Core/OptionGroup.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | CiviCRM version 4.5                                                |
   5  +--------------------------------------------------------------------+
   6  | Copyright CiviCRM LLC (c) 2004-2014                                |
   7  +--------------------------------------------------------------------+
   8  | This file is a part of CiviCRM.                                    |
   9  |                                                                    |
  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.   |
  13  |                                                                    |
  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.        |
  18  |                                                                    |
  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  +--------------------------------------------------------------------+
  26 */
  27
  28 /**
  29  *
  30  * @package CRM
  31  * @copyright CiviCRM LLC (c) 2004-2014
  32  * $Id$
  33  *
  34  */
  35 class CRM_Core_OptionGroup {
  36   static $_values = array();
  37   static $_cache = array();
  38
  39   /*
  40    * $_domainIDGroups array maintains the list of option groups for whom
  41    * domainID is to be considered.
  42    *
  43    */
  44   static $_domainIDGroups = array(
  45     'from_email_address',
  46     'grant_type',
  47   );
  48
  49   static function &valuesCommon(
  50     $dao, $flip = FALSE, $grouping = FALSE,
  51     $localize = FALSE, $valueColumnName = 'label'
  52   ) {
  53     self::$_values = array();
  54
  55     while ($dao->fetch()) {
  56       if ($flip) {
  57         if ($grouping) {
  58           self::$_values[$dao->value] = $dao->grouping;
  59         }
  60         else {
  61           self::$_values[$dao->{$valueColumnName}] = $dao->value;
  62         }
  63       }
  64       else {
  65         if ($grouping) {
  66           self::$_values[$dao->{$valueColumnName}] = $dao->grouping;
  67         }
  68         else {
  69           self::$_values[$dao->value] = $dao->{$valueColumnName};
  70         }
  71       }
  72     }
  73     if ($localize) {
  74       $i18n = CRM_Core_I18n::singleton();
  75       $i18n->localizeArray(self::$_values);
  76     }
  77     return self::$_values;
  78   }
  79
  80   /**
  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
  85    *
  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'
  96    *
  97    * @return array      the values as specified by the above params
  98    * @static
  99    * @void
 100    */
 101   static function &values(
 102     $name, $flip = FALSE, $grouping = FALSE,
 103     $localize = FALSE, $condition = NULL,
 104     $labelColumnName = 'label', $onlyActive = TRUE, $fresh = FALSE, $keyColumnName = 'value'
 105   ) {
 106     $cache = CRM_Utils_Cache::singleton();
 107     $cacheKey = self::createCacheKey($name, $flip, $grouping, $localize, $condition, $labelColumnName, $onlyActive, $keyColumnName);
 108
 109     if (!$fresh) {
 110       // Fetch from static var
 111       if (array_key_exists($cacheKey, self::$_cache)) {
 112         return self::$_cache[$cacheKey];
 113       }
 114       // Fetch from main cache
 115       $var = $cache->get($cacheKey);
 116       if ($var) {
 117         return $var;
 118       }
 119     }
 120
 121     $query = "
 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
 126   AND  g.name            = %1
 127   AND  g.is_active       = 1 ";
 128
 129     if ($onlyActive) {
 130       $query .= " AND  v.is_active = 1 ";
 131     }
 132     if (in_array($name, self::$_domainIDGroups)) {
 133       $query .= " AND v.domain_id = " . CRM_Core_Config::domainID();
 134     }
 135
 136     if ($condition) {
 137       $query .= $condition;
 138     }
 139
 140     $query .= " ORDER BY v.weight";
 141
 142     $p = array(1 => array($name, 'String'));
 143     $dao = CRM_Core_DAO::executeQuery($query, $p);
 144
 145     $var = self::valuesCommon($dao, $flip, $grouping, $localize, $labelColumnName);
 146
 147     // call option value hook
 148     CRM_Utils_Hook::optionValues($var, $name);
 149
 150     self::$_cache[$cacheKey] = $var;
 151     $cache->set($cacheKey, $var);
 152
 153     return $var;
 154   }
 155
 156   /**
 157    * Counterpart to values() which removes the item from the cache
 158    *
 159    * @param $name
 160    * @param $flip
 161    * @param $grouping
 162    * @param $localize
 163    * @param $condition
 164    * @param $labelColumnName
 165    * @param $onlyActive
 166    * @param string $keyColumnName
 167    */
 168   protected static function flushValues($name, $flip, $grouping, $localize, $condition, $labelColumnName, $onlyActive, $keyColumnName = 'value') {
 169     $cacheKey = self::createCacheKey($name, $flip, $grouping, $localize, $condition, $labelColumnName, $onlyActive, $keyColumnName);
 170     $cache = CRM_Utils_Cache::singleton();
 171     $cache->delete($cacheKey);
 172     unset(self::$_cache[$cacheKey]);
 173   }
 174
 175   protected static function createCacheKey() {
 176     $cacheKey = "CRM_OG_" . serialize(func_get_args());
 177     return $cacheKey;
 178   }
 179
 180   /**
 181    * This function retrieves all the values for the specific option group by id
 182    * this is primarily used to create various html based form elements
 183    * (radio, select, checkbox etc). OptionGroups for most cases have the
 184    * 'label' in the label colum and the 'id' or 'name' in the value column
 185    *
 186    * @param $id         integer id of the option group
 187    * @param $flip       boolean results are return in id => label format if false
 188    *                            if true, the results are reversed
 189    * @param $grouping   boolean if true, return the value in 'grouping' column
 190    * @param $localize   boolean if true, localize the results before returning
 191    * @param $labelColumnName string the column to use for 'label'
 192    *
 193    * @param bool $onlyActive
 194    * @param bool $fresh
 195    *
 196    * @return array      the values as specified by the above params
 197    * @static
 198    * @void
 199    */
 200   static function &valuesByID($id, $flip = FALSE, $grouping = FALSE, $localize = FALSE, $labelColumnName = 'label', $onlyActive = TRUE, $fresh = FALSE) {
 201     $cacheKey = self::createCacheKey($id, $flip, $grouping, $localize, $labelColumnName, $onlyActive);
 202
 203     $cache = CRM_Utils_Cache::singleton();
 204     if (!$fresh) {
 205       $var = $cache->get($cacheKey);
 206       if ($var) {
 207         return $var;
 208       }
 209     }
 210     $query = "
 211 SELECT  v.{$labelColumnName} as {$labelColumnName} ,v.value as value, v.grouping as grouping
 212 FROM   civicrm_option_value v,
 213        civicrm_option_group g
 214 WHERE  v.option_group_id = g.id
 215   AND  g.id              = %1
 216   AND  g.is_active       = 1
 217 ";
 218     if ($onlyActive) {
 219       $query .= " AND  v.is_active = 1 ";
 220     }
 221     $query .= " ORDER BY v.weight, v.label";
 222
 223     $p = array(1 => array($id, 'Integer'));
 224     $dao = CRM_Core_DAO::executeQuery($query, $p);
 225
 226     $var = self::valuesCommon($dao, $flip, $grouping, $localize, $labelColumnName);
 227     $cache->set($cacheKey, $var);
 228
 229     return $var;
 230   }
 231
 232   /**
 233    * Function to lookup titles OR ids for a set of option_value populated fields. The retrieved value
 234    * is assigned a new fieldname by id or id's by title
 235    * (each within a specificied option_group)
 236    *
 237    * @param  array   $params   Reference array of values submitted by the form. Based on
 238    *                           $flip, creates new elements in $params for each field in
 239    *                           the $names array.
 240    *                           If $flip = false, adds     root field name     => title
 241    *                           If $flip = true, adds      actual field name   => id
 242    *
 243    * @param  array   $names    Reference array of fieldnames we want transformed.
 244    *                           Array key = 'postName' (field name submitted by form in $params).
 245    *                           Array value = array(
 246      'newName' => $newName, 'groupName' => $groupName).
 247    *
 248    *
 249    * @param  boolean $flip
 250    *
 251    * @return void
 252    *
 253    * @access public
 254    * @static
 255    */
 256   static function lookupValues(&$params, &$names, $flip = FALSE) {
 257     foreach ($names as $postName => $value) {
 258       // See if $params field is in $names array (i.e. is a value that we need to lookup)
 259       if ($postalName = CRM_Utils_Array::value($postName, $params)) {
 260         $postValues = array();
 261         // params[$postName] may be a Ctrl+A separated value list
 262         if (is_string($postalName) &&
 263           strpos($postalName, CRM_Core_DAO::VALUE_SEPARATOR) == FALSE
 264         ) {
 265           // eliminate the ^A frm the beginning and end if present
 266           if (substr($postalName, 0, 1) == CRM_Core_DAO::VALUE_SEPARATOR) {
 267             $params[$postName] = substr($params[$postName], 1, -1);
 268           }
 269           $postValues = explode(CRM_Core_DAO::VALUE_SEPARATOR, $params[$postName]);
 270         }
 271         elseif (is_array($postalName)) {
 272           $postValues = $postalName;
 273         }
 274         $newValue = array();
 275         foreach ($postValues as $postValue) {
 276           if (!$postValue) {
 277             continue;
 278           }
 279
 280           if ($flip) {
 281             $p        = array(1 => array($postValue, 'String'));
 282             $lookupBy = 'v.label= %1';
 283             $select   = "v.value";
 284           }
 285           else {
 286             $p        = array(1 => array($postValue, 'Integer'));
 287             $lookupBy = 'v.value = %1';
 288             $select   = "v.label";
 289           }
 290
 291           $p[2] = array($value['groupName'], 'String');
 292           $query = "
 293                         SELECT $select
 294                         FROM   civicrm_option_value v,
 295                                civicrm_option_group g
 296                         WHERE  v.option_group_id = g.id
 297                         AND    g.name            = %2
 298                         AND    $lookupBy";
 299
 300           $newValue[] = CRM_Core_DAO::singleValueQuery($query, $p);
 301           $newValue = str_replace(',', '_', $newValue);
 302         }
 303         $params[$value['newName']] = implode(', ', $newValue);
 304       }
 305     }
 306   }
 307
 308   static function getLabel($groupName, $value, $onlyActiveValue = TRUE) {
 309     if (empty($groupName) ||
 310       empty($value)
 311     ) {
 312       return NULL;
 313     }
 314
 315     $query = "
 316 SELECT  v.label as label ,v.value as value
 317 FROM   civicrm_option_value v,
 318        civicrm_option_group g
 319 WHERE  v.option_group_id = g.id
 320   AND  g.name            = %1
 321   AND  g.is_active       = 1
 322   AND  v.value           = %2
 323 ";
 324     if ($onlyActiveValue) {
 325       $query .= " AND  v.is_active = 1 ";
 326     }
 327     $p = array(1 => array($groupName, 'String'),
 328       2 => array($value, 'Integer'),
 329     );
 330     $dao = CRM_Core_DAO::executeQuery($query, $p);
 331     if ($dao->fetch()) {
 332       return $dao->label;
 333     }
 334     return NULL;
 335   }
 336
 337   static function getValue($groupName,
 338     $label,
 339     $labelField = 'label',
 340     $labelType  = 'String',
 341     $valueField = 'value'
 342   ) {
 343     if (empty($label)) {
 344       return NULL;
 345     }
 346
 347     $query = "
 348 SELECT  v.label as label ,v.{$valueField} as value
 349 FROM   civicrm_option_value v,
 350        civicrm_option_group g
 351 WHERE  v.option_group_id = g.id
 352   AND  g.name            = %1
 353   AND  v.is_active       = 1
 354   AND  g.is_active       = 1
 355   AND  v.$labelField     = %2
 356 ";
 357
 358     $p = array(1 => array($groupName, 'String'),
 359       2 => array($label, $labelType),
 360     );
 361     $dao = CRM_Core_DAO::executeQuery($query, $p);
 362     if ($dao->fetch()) {
 363       $dao->free();
 364       return $dao->value;
 365     }
 366     $dao->free();
 367     return NULL;
 368   }
 369
 370   /**
 371    * Get option_value.value from default option_value row for an option group
 372    *
 373    * @param string $groupName the name of the option group
 374    *
 375    * @access public
 376    * @static
 377    *
 378    * @return string   the value from the row where is_default = true
 379    */
 380   static function getDefaultValue($groupName) {
 381     if (empty($groupName)) {
 382       return NULL;
 383     }
 384     $query = "
 385 SELECT v.value
 386 FROM   civicrm_option_value v,
 387        civicrm_option_group g
 388 WHERE  v.option_group_id = g.id
 389   AND  g.name            = %1
 390   AND  v.is_active       = 1
 391   AND  g.is_active       = 1
 392   AND  v.is_default      = 1
 393 ";
 394     if (in_array($groupName, self::$_domainIDGroups)) {
 395       $query .= " AND v.domain_id = " . CRM_Core_Config::domainID();
 396     }
 397
 398     $p = array(1 => array($groupName, 'String'));
 399     return CRM_Core_DAO::singleValueQuery($query, $p);
 400   }
 401
 402   /**
 403    * Creates a new option group with the passed in values
 404    * @TODO: Should update the group if it already exists intelligently, so multi-lingual is
 405    * not messed up. Currently deletes the old group
 406    *
 407    * @param string $groupName the name of the option group - make sure there is no conflict
 408    * @param array  $values    the associative array that has information on the option values
 409    *                          the keys of this array are:
 410    *                          string 'title'       (required)
 411    *                          string 'value'       (required)
 412    *                          string 'name'        (optional)
 413    *                          string 'description' (optional)
 414    *                          int    'weight'      (optional) - the order in which the value are displayed
 415    *                          bool   'is_default'  (optional) - is this the default one to display when rendered in form
 416    *                          bool   'is_active'   (optional) - should this element be rendered
 417    * @param int    $defaultID (reference) - the option value ID of the default element (if set) is returned else 'null'
 418    * @param string $groupLabel            - the optional label of the option group else set to group name
 419    *
 420    * @access public
 421    * @static
 422    *
 423    * @return int   the option group ID
 424    *
 425    */
 426   static function createAssoc($groupName, &$values, &$defaultID, $groupTitle = NULL) {
 427     self::deleteAssoc($groupName);
 428     if (!empty($values)) {
 429       $group              = new CRM_Core_DAO_OptionGroup();
 430       $group->name        = $groupName;
 431       $group->title       = empty($groupTitle) ? $groupName : $groupTitle;
 432       $group->is_reserved = 1;
 433       $group->is_active   = 1;
 434       $group->save();
 435
 436       foreach ($values as $v) {
 437         $value = new CRM_Core_DAO_OptionValue();
 438         $value->option_group_id = $group->id;
 439         $value->label = $v['label'];
 440         $value->value = $v['value'];
 441         $value->name = CRM_Utils_Array::value('name', $v);
 442         $value->description = CRM_Utils_Array::value('description', $v);
 443         $value->weight = CRM_Utils_Array::value('weight', $v);
 444         $value->is_default = CRM_Utils_Array::value('is_default', $v);
 445         $value->is_active = CRM_Utils_Array::value('is_active', $v);
 446         $value->save();
 447
 448         if ($value->is_default) {
 449           $defaultID = $value->id;
 450         }
 451       }
 452     }
 453     else {
 454       return $defaultID = 'null';
 455     }
 456
 457     return $group->id;
 458   }
 459
 460   static function getAssoc($groupName, &$values, $flip = FALSE, $field = 'name') {
 461     $query = "
 462 SELECT v.id as amount_id, v.value, v.label, v.name, v.description, v.weight
 463   FROM civicrm_option_group g,
 464        civicrm_option_value v
 465  WHERE g.id = v.option_group_id
 466    AND g.$field = %1
 467 ORDER BY v.weight
 468 ";
 469     $params = array(1 => array($groupName, 'String'));
 470     $dao = CRM_Core_DAO::executeQuery($query, $params);
 471
 472     $fields = array('value', 'label', 'name', 'description', 'amount_id', 'weight');
 473     if ($flip) {
 474       $values = array();
 475     }
 476     else {
 477       foreach ($fields as $field) {
 478         $values[$field] = array();
 479       }
 480     }
 481     $index = 1;
 482
 483     while ($dao->fetch()) {
 484       if ($flip) {
 485         $value = array();
 486         foreach ($fields as $field) {
 487           $value[$field] = $dao->$field;
 488         }
 489         $values[$dao->amount_id] = $value;
 490       }
 491       else {
 492         foreach ($fields as $field) {
 493           $values[$field][$index] = $dao->$field;
 494         }
 495         $index++;
 496       }
 497     }
 498   }
 499
 500   static function deleteAssoc($groupName, $operator = "=") {
 501     $query = "
 502 DELETE g, v
 503   FROM civicrm_option_group g,
 504        civicrm_option_value v
 505  WHERE g.id = v.option_group_id
 506    AND g.name {$operator} %1";
 507
 508     $params = array(1 => array($groupName, 'String'));
 509
 510     $dao = CRM_Core_DAO::executeQuery($query, $params);
 511   }
 512
 513   static function optionLabel($groupName, $value) {
 514     $query = "
 515 SELECT v.label
 516   FROM civicrm_option_group g,
 517        civicrm_option_value v
 518  WHERE g.id = v.option_group_id
 519    AND g.name  = %1
 520    AND v.value = %2";
 521     $params = array(1 => array($groupName, 'String'),
 522       2 => array($value, 'String'),
 523     );
 524     return CRM_Core_DAO::singleValueQuery($query, $params);
 525   }
 526
 527   static function getRowValues($groupName, $fieldValue, $field = 'name',
 528     $fieldType = 'String', $active = TRUE
 529   ) {
 530     $query = "
 531 SELECT v.id, v.label, v.value, v.name, v.weight, v.description
 532 FROM   civicrm_option_value v,
 533        civicrm_option_group g
 534 WHERE  v.option_group_id = g.id
 535   AND  g.name            = %1
 536   AND  g.is_active       = 1
 537   AND  v.$field          = %2
 538 ";
 539
 540     if ($active) {
 541       $query .= " AND  v.is_active = 1";
 542     }
 543
 544     $p = array(1 => array($groupName, 'String'),
 545       2 => array($fieldValue, $fieldType),
 546     );
 547     $dao = CRM_Core_DAO::executeQuery($query, $p);
 548     $row = array();
 549
 550     if ($dao->fetch()) {
 551       foreach (array(
 552         'id', 'name', 'value', 'label', 'weight', 'description') as $fld) {
 553         $row[$fld] = $dao->$fld;
 554       }
 555     }
 556     return $row;
 557   }
 558
 559   /*
 560    * Wrapper for calling values with fresh set to true to empty the given value
 561    *
 562    * Since there appears to be some inconsistency
 563    * (@todo remove inconsistency) around the pseudoconstant operations
 564    * (for example CRM_Contribution_Pseudoconstant::paymentInstrument doesn't specify isActive
 565    * which is part of the cache key
 566    * will do a couple of variations & aspire to someone cleaning it up later
 567    */
 568   static function flush($name, $params = array()){
 569     $defaults = array(
 570       'flip' => FALSE,
 571       'grouping' => FALSE,
 572       'localize' => FALSE,
 573       'condition' => NULL,
 574       'labelColumnName' => 'label',
 575     );
 576
 577     $params = array_merge($defaults, $params);
 578     self::flushValues(
 579       $name,
 580       $params['flip'],
 581       $params['grouping'],
 582       $params['localize'],
 583       $params['condition'],
 584       $params['labelColumnName'],
 585       TRUE,
 586       TRUE
 587     );
 588     self::flushValues(
 589       $name,
 590       $params['flip'],
 591       $params['grouping'],
 592       $params['localize'],
 593       $params['condition'],
 594       $params['labelColumnName'],
 595       FALSE,
 596       TRUE
 597     );
 598   }
 599
 600   static function flushAll() {
 601     self::$_values = array();
 602     self::$_cache = array();
 603     CRM_Utils_Cache::singleton()->flush();
 604   }
 605 }
 606