crm.fsf.org/20131203/files/sites/all/modules-new/civicrm/CRM/Core/OptionGroup.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | CiviCRM version 4.6                                                |
   5  +--------------------------------------------------------------------+
   6  | Copyright CiviCRM LLC (c) 2004-2015                                |
   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-2016
  32  */
  33 class CRM_Core_OptionGroup {
  34   static $_values = array();
  35   static $_cache = array();
  36
  37   /**
  38    * $_domainIDGroups array maintains the list of option groups for whom
  39    * domainID is to be considered.
  40    */
  41   static $_domainIDGroups = array(
  42     'from_email_address',
  43     'grant_type',
  44   );
  45
  46   /**
  47    * @param CRM_Core_DAO $dao
  48    * @param bool $flip
  49    * @param bool $grouping
  50    * @param bool $localize
  51    * @param string $valueColumnName
  52    *
  53    * @return array
  54    */
  55   public static function &valuesCommon(
  56     $dao, $flip = FALSE, $grouping = FALSE,
  57     $localize = FALSE, $valueColumnName = 'label'
  58   ) {
  59     self::$_values = array();
  60
  61     while ($dao->fetch()) {
  62       if ($flip) {
  63         if ($grouping) {
  64           self::$_values[$dao->value] = $dao->grouping;
  65         }
  66         else {
  67           self::$_values[$dao->{$valueColumnName}] = $dao->value;
  68         }
  69       }
  70       else {
  71         if ($grouping) {
  72           self::$_values[$dao->{$valueColumnName}] = $dao->grouping;
  73         }
  74         else {
  75           self::$_values[$dao->value] = $dao->{$valueColumnName};
  76         }
  77       }
  78     }
  79     if ($localize) {
  80       $i18n = CRM_Core_I18n::singleton();
  81       $i18n->localizeArray(self::$_values);
  82     }
  83     return self::$_values;
  84   }
  85
  86   /**
  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
  91    *
  92    * @param string $name
  93    *   name of the option group.
  94    * @param bool $flip
  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.
 107    * @param bool $fresh
 108    *   ignore cache entries and go back to DB.
 109    * @param string $keyColumnName
 110    *   the column to use for 'key'.
 111    *
 112    * @return array
 113    *   the values as specified by the above params
 114    * @void
 115    */
 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'
 120   ) {
 121     $cache = CRM_Utils_Cache::singleton();
 122     $cacheKey = self::createCacheKey($name, $flip, $grouping, $localize, $condition, $labelColumnName, $onlyActive, $keyColumnName);
 123
 124     if (!$fresh) {
 125       // Fetch from static var
 126       if (array_key_exists($cacheKey, self::$_cache)) {
 127         return self::$_cache[$cacheKey];
 128       }
 129       // Fetch from main cache
 130       $var = $cache->get($cacheKey);
 131       if ($var) {
 132         return $var;
 133       }
 134     }
 135
 136     $query = "
 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
 141   AND  g.name            = %1
 142   AND  g.is_active       = 1 ";
 143
 144     if ($onlyActive) {
 145       $query .= " AND  v.is_active = 1 ";
 146     }
 147     if (in_array($name, self::$_domainIDGroups)) {
 148       $query .= " AND v.domain_id = " . CRM_Core_Config::domainID();
 149     }
 150
 151     if ($condition) {
 152       $query .= $condition;
 153     }
 154
 155     $query .= " ORDER BY v.weight";
 156
 157     $p = array(1 => array($name, 'String'));
 158     $dao = CRM_Core_DAO::executeQuery($query, $p);
 159
 160     $var = self::valuesCommon($dao, $flip, $grouping, $localize, $labelColumnName);
 161
 162     // call option value hook
 163     CRM_Utils_Hook::optionValues($var, $name);
 164
 165     self::$_cache[$cacheKey] = $var;
 166     $cache->set($cacheKey, $var);
 167
 168     return $var;
 169   }
 170
 171   /**
 172    * Counterpart to values() which removes the item from the cache
 173    *
 174    * @param string $name
 175    * @param $flip
 176    * @param $grouping
 177    * @param $localize
 178    * @param $condition
 179    * @param string $labelColumnName
 180    * @param $onlyActive
 181    * @param string $keyColumnName
 182    */
 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]);
 188   }
 189
 190   /**
 191    * @return string
 192    */
 193   protected static function createCacheKey() {
 194     $cacheKey = "CRM_OG_" . serialize(func_get_args());
 195     return $cacheKey;
 196   }
 197
 198   /**
 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
 203    *
 204    * @param int $id
 205    *   id of the option group.
 206    * @param bool $flip
 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
 216    * @param bool $fresh
 217    *
 218    * @return array
 219    *   Array of values as specified by the above params
 220    * @void
 221    */
 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);
 224
 225     $cache = CRM_Utils_Cache::singleton();
 226     if (!$fresh) {
 227       $var = $cache->get($cacheKey);
 228       if ($var) {
 229         return $var;
 230       }
 231     }
 232     $query = "
 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
 237   AND  g.id              = %1
 238   AND  g.is_active       = 1
 239 ";
 240     if ($onlyActive) {
 241       $query .= " AND  v.is_active = 1 ";
 242     }
 243     $query .= " ORDER BY v.weight, v.label";
 244
 245     $p = array(1 => array($id, 'Integer'));
 246     $dao = CRM_Core_DAO::executeQuery($query, $p);
 247
 248     $var = self::valuesCommon($dao, $flip, $grouping, $localize, $labelColumnName);
 249     $cache->set($cacheKey, $var);
 250
 251     return $var;
 252   }
 253
 254   /**
 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)
 258    *
 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
 262    *   the $names array.
 263    *   If $flip = false, adds root field name => title
 264    *   If $flip = true, adds actual field name => id
 265    *
 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).
 270    *
 271    *
 272    * @param bool $flip
 273    */
 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
 282         ) {
 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);
 286           }
 287           $postValues = explode(CRM_Core_DAO::VALUE_SEPARATOR, $params[$postName]);
 288         }
 289         elseif (is_array($postalName)) {
 290           $postValues = $postalName;
 291         }
 292         $newValue = array();
 293         foreach ($postValues as $postValue) {
 294           if (!$postValue) {
 295             continue;
 296           }
 297
 298           if ($flip) {
 299             $p = array(1 => array($postValue, 'String'));
 300             $lookupBy = 'v.label= %1';
 301             $select = "v.value";
 302           }
 303           else {
 304             $p = array(1 => array($postValue, 'Integer'));
 305             $lookupBy = 'v.value = %1';
 306             $select = "v.label";
 307           }
 308
 309           $p[2] = array($value['groupName'], 'String');
 310           $query = "
 311                         SELECT $select
 312                         FROM   civicrm_option_value v,
 313                                civicrm_option_group g
 314                         WHERE  v.option_group_id = g.id
 315                         AND    g.name            = %2
 316                         AND    $lookupBy";
 317
 318           $newValue[] = CRM_Core_DAO::singleValueQuery($query, $p);
 319           $newValue = str_replace(',', '_', $newValue);
 320         }
 321         $params[$value['newName']] = implode(', ', $newValue);
 322       }
 323     }
 324   }
 325
 326   /**
 327    * @deprecated - use CRM_Core_Pseudoconstant::getLabel
 328    *
 329    * @param string $groupName
 330    * @param $value
 331    * @param bool $onlyActiveValue
 332    *
 333    * @return null
 334    */
 335   public static function getLabel($groupName, $value, $onlyActiveValue = TRUE) {
 336     if (empty($groupName) ||
 337       empty($value)
 338     ) {
 339       return NULL;
 340     }
 341
 342     $query = "
 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
 347   AND  g.name            = %1
 348   AND  g.is_active       = 1
 349   AND  v.value           = %2
 350 ";
 351     if ($onlyActiveValue) {
 352       $query .= " AND  v.is_active = 1 ";
 353     }
 354     $p = array(
 355       1 => array($groupName, 'String'),
 356       2 => array($value, 'Integer'),
 357     );
 358     $dao = CRM_Core_DAO::executeQuery($query, $p);
 359     if ($dao->fetch()) {
 360       return $dao->label;
 361     }
 362     return NULL;
 363   }
 364
 365   /**
 366    * @deprecated
 367    *
 368    * This function is not cached.
 369    *
 370    * @param string $groupName
 371    * @param $label
 372    * @param string $labelField
 373    * @param string $labelType
 374    * @param string $valueField
 375    *
 376    * @return null
 377    */
 378   public static function getValue(
 379     $groupName,
 380     $label,
 381     $labelField = 'label',
 382     $labelType = 'String',
 383     $valueField = 'value'
 384   ) {
 385     if (empty($label)) {
 386       return NULL;
 387     }
 388
 389     $query = "
 390 SELECT  v.label as label ,v.{$valueField} as value
 391 FROM   civicrm_option_value v,
 392        civicrm_option_group g
 393 WHERE  v.option_group_id = g.id
 394   AND  g.name            = %1
 395   AND  v.is_active       = 1
 396   AND  g.is_active       = 1
 397   AND  v.$labelField     = %2
 398 ";
 399
 400     $p = array(
 401       1 => array($groupName, 'String'),
 402       2 => array($label, $labelType),
 403     );
 404     $dao = CRM_Core_DAO::executeQuery($query, $p);
 405     if ($dao->fetch()) {
 406       $dao->free();
 407       return $dao->value;
 408     }
 409     $dao->free();
 410     return NULL;
 411   }
 412
 413   /**
 414    * Get option_value.value from default option_value row for an option group
 415    *
 416    * @param string $groupName
 417    *   The name of the option group.
 418    *
 419    *
 420    * @return string
 421    *   the value from the row where is_default = true
 422    */
 423   public static function getDefaultValue($groupName) {
 424     if (empty($groupName)) {
 425       return NULL;
 426     }
 427     $query = "
 428 SELECT v.value
 429 FROM   civicrm_option_value v,
 430        civicrm_option_group g
 431 WHERE  v.option_group_id = g.id
 432   AND  g.name            = %1
 433   AND  v.is_active       = 1
 434   AND  g.is_active       = 1
 435   AND  v.is_default      = 1
 436 ";
 437     if (in_array($groupName, self::$_domainIDGroups)) {
 438       $query .= " AND v.domain_id = " . CRM_Core_Config::domainID();
 439     }
 440
 441     $p = array(1 => array($groupName, 'String'));
 442     return CRM_Core_DAO::singleValueQuery($query, $p);
 443   }
 444
 445   /**
 446    * Creates a new option group with the passed in values.
 447    * @TODO: Should update the group if it already exists intelligently, so multi-lingual is
 448    * not messed up. Currently deletes the old group
 449    *
 450    * @param string $groupName
 451    *   The name of the option group - make sure there is no conflict.
 452    * @param array $values
 453    *   The associative array that has information on the option values.
 454    *                          the keys of this array are:
 455    *                          string 'title'       (required)
 456    *                          string 'value'       (required)
 457    *                          string 'name'        (optional)
 458    *                          string 'description' (optional)
 459    *                          int    'weight'      (optional) - the order in which the value are displayed
 460    *                          bool   'is_default'  (optional) - is this the default one to display when rendered in form
 461    *                          bool   'is_active'   (optional) - should this element be rendered
 462    * @param int $defaultID
 463    *   (reference) - the option value ID of the default element (if set) is returned else 'null'.
 464    * @param null $groupTitle
 465    *   The optional label of the option group else set to group name.
 466    *
 467    *
 468    * @return int
 469    *   the option group ID
 470    */
 471   public static function createAssoc($groupName, &$values, &$defaultID, $groupTitle = NULL) {
 472     self::deleteAssoc($groupName);
 473     if (!empty($values)) {
 474       $group = new CRM_Core_DAO_OptionGroup();
 475       $group->name = $groupName;
 476       $group->title = empty($groupTitle) ? $groupName : $groupTitle;
 477       $group->is_reserved = 1;
 478       $group->is_active = 1;
 479       $group->save();
 480
 481       foreach ($values as $v) {
 482         $value = new CRM_Core_DAO_OptionValue();
 483         $value->option_group_id = $group->id;
 484         $value->label = $v['label'];
 485         $value->value = $v['value'];
 486         $value->name = CRM_Utils_Array::value('name', $v);
 487         $value->description = CRM_Utils_Array::value('description', $v);
 488         $value->weight = CRM_Utils_Array::value('weight', $v);
 489         $value->is_default = CRM_Utils_Array::value('is_default', $v);
 490         $value->is_active = CRM_Utils_Array::value('is_active', $v);
 491         $value->save();
 492
 493         if ($value->is_default) {
 494           $defaultID = $value->id;
 495         }
 496       }
 497     }
 498     else {
 499       return $defaultID = 'null';
 500     }
 501
 502     return $group->id;
 503   }
 504
 505   /**
 506    * @param string $groupName
 507    * @param $values
 508    * @param bool $flip
 509    * @param string $field
 510    */
 511   public static function getAssoc($groupName, &$values, $flip = FALSE, $field = 'name') {
 512     $query = "
 513 SELECT v.id as amount_id, v.value, v.label, v.name, v.description, v.weight
 514   FROM civicrm_option_group g,
 515        civicrm_option_value v
 516  WHERE g.id = v.option_group_id
 517    AND g.$field = %1
 518 ORDER BY v.weight
 519 ";
 520     $params = array(1 => array($groupName, 'String'));
 521     $dao = CRM_Core_DAO::executeQuery($query, $params);
 522
 523     $fields = array('value', 'label', 'name', 'description', 'amount_id', 'weight');
 524     if ($flip) {
 525       $values = array();
 526     }
 527     else {
 528       foreach ($fields as $field) {
 529         $values[$field] = array();
 530       }
 531     }
 532     $index = 1;
 533
 534     while ($dao->fetch()) {
 535       if ($flip) {
 536         $value = array();
 537         foreach ($fields as $field) {
 538           $value[$field] = $dao->$field;
 539         }
 540         $values[$dao->amount_id] = $value;
 541       }
 542       else {
 543         foreach ($fields as $field) {
 544           $values[$field][$index] = $dao->$field;
 545         }
 546         $index++;
 547       }
 548     }
 549   }
 550
 551   /**
 552    * @param string $groupName
 553    * @param string $operator
 554    */
 555   public static function deleteAssoc($groupName, $operator = "=") {
 556     $query = "
 557 DELETE g, v
 558   FROM civicrm_option_group g,
 559        civicrm_option_value v
 560  WHERE g.id = v.option_group_id
 561    AND g.name {$operator} %1";
 562
 563     $params = array(1 => array($groupName, 'String'));
 564
 565     $dao = CRM_Core_DAO::executeQuery($query, $params);
 566   }
 567
 568   /**
 569    * @param string $groupName
 570    * @param $value
 571    *
 572    * @return null|string
 573    */
 574   public static function optionLabel($groupName, $value) {
 575     $query = "
 576 SELECT v.label
 577   FROM civicrm_option_group g,
 578        civicrm_option_value v
 579  WHERE g.id = v.option_group_id
 580    AND g.name  = %1
 581    AND v.value = %2";
 582     $params = array(
 583       1 => array($groupName, 'String'),
 584       2 => array($value, 'String'),
 585     );
 586     return CRM_Core_DAO::singleValueQuery($query, $params);
 587   }
 588
 589   /**
 590    * @param string $groupName
 591    * @param $fieldValue
 592    * @param string $field
 593    * @param string $fieldType
 594    * @param bool $active
 595    * @param bool $localize
 596    *   if true, localize the results before returning.
 597    *
 598    * @return array
 599    */
 600   public static function getRowValues(
 601     $groupName, $fieldValue, $field = 'name',
 602     $fieldType = 'String', $active = TRUE, $localize = FALSE
 603   ) {
 604     $query = "
 605 SELECT v.id, v.label, v.value, v.name, v.weight, v.description
 606 FROM   civicrm_option_value v,
 607        civicrm_option_group g
 608 WHERE  v.option_group_id = g.id
 609   AND  g.name            = %1
 610   AND  g.is_active       = 1
 611   AND  v.$field          = %2
 612 ";
 613
 614     if ($active) {
 615       $query .= " AND  v.is_active = 1";
 616     }
 617
 618     $p = array(
 619       1 => array($groupName, 'String'),
 620       2 => array($fieldValue, $fieldType),
 621     );
 622     $dao = CRM_Core_DAO::executeQuery($query, $p);
 623     $row = array();
 624
 625     if ($dao->fetch()) {
 626       foreach (array(
 627                  'id',
 628                  'name',
 629                  'value',
 630                  'label',
 631                  'weight',
 632                  'description',
 633                ) as $fld) {
 634         $row[$fld] = $dao->$fld;
 635         if ($localize && in_array($fld, array('label', 'description'))) {
 636           $row[$fld] = ts($row[$fld]);
 637         }
 638       }
 639     }
 640
 641     return $row;
 642   }
 643
 644   /**
 645    * Wrapper for calling values with fresh set to true to empty the given value.
 646    *
 647    * Since there appears to be some inconsistency
 648    * (@todo remove inconsistency) around the pseudoconstant operations
 649    * (for example CRM_Contribution_Pseudoconstant::paymentInstrument doesn't specify isActive
 650    * which is part of the cache key
 651    * will do a couple of variations & aspire to someone cleaning it up later
 652    *
 653    * @param string $name
 654    * @param array $params
 655    */
 656   public static function flush($name, $params = array()) {
 657     $defaults = array(
 658       'flip' => FALSE,
 659       'grouping' => FALSE,
 660       'localize' => FALSE,
 661       'condition' => NULL,
 662       'labelColumnName' => 'label',
 663     );
 664
 665     $params = array_merge($defaults, $params);
 666     self::flushValues(
 667       $name,
 668       $params['flip'],
 669       $params['grouping'],
 670       $params['localize'],
 671       $params['condition'],
 672       $params['labelColumnName'],
 673       TRUE,
 674       TRUE
 675     );
 676     self::flushValues(
 677       $name,
 678       $params['flip'],
 679       $params['grouping'],
 680       $params['localize'],
 681       $params['condition'],
 682       $params['labelColumnName'],
 683       FALSE,
 684       TRUE
 685     );
 686   }
 687
 688   public static function flushAll() {
 689     self::$_values = array();
 690     self::$_cache = array();
 691     CRM_Utils_Cache::singleton()->flush();
 692   }
 693
 694 }