/**
* Get metadata.
*
* Function fills the 'options' array on the metadata returned by getfields if
* 1) the param option 'get_options' is defined - e.g. $params['options']['get_options'] => array('custom_1)
* (this is passed in as the $fieldsToResolve array)
* 2) the field is a pseudoconstant and is NOT an FK
* - the reason for this is that checking / transformation is done on pseudoconstants but
* - if the field is an FK then mysql will enforce the data quality (& we have handling on failure)
* @todo - if may be we should define a 'resolve' key on the pseudoconstant for when these rules are not fine enough
*
* This function is only split out for the purpose of code clarity / comment block documentation
*
* @param array $metadata
* The array of metadata that will form the result of the getfields function.
* @param array $apiRequest
* @param string $fieldname
* Field currently being processed.
* @param array $fieldSpec
* Metadata for that field.
*/
function _civicrm_api3_generic_get_metadata_options(&$metadata, $apiRequest, $fieldname, $fieldSpec)
{
if (empty($fieldSpec['pseudoconstant']) && empty($fieldSpec['option_group_id'])) {
return;
}
$fieldsToResolve = $apiRequest['params']['options']['get_options'];
if (!empty($metadata[$fieldname]['options']) || !in_array($fieldname, $fieldsToResolve) && !in_array('all', $fieldsToResolve)) {
return;
}
// Allow caller to specify context
$context = CRM_Utils_Array::value('get_options_context', $apiRequest['params']['options']);
// Default to api action if it is a supported context.
if (!$context) {
$action = CRM_Utils_Array::value('action', $apiRequest['params']);
$contexts = CRM_Core_DAO::buildOptionsContext();
if (isset($contexts[$action])) {
$context = $action;
}
}
$options = civicrm_api($apiRequest['entity'], 'getoptions', array('version' => 3, 'field' => $fieldname, 'context' => $context));
if (is_array(CRM_Utils_Array::value('values', $options))) {
$metadata[$fieldname]['options'] = $options['values'];
}
}
/**
* Low-level option getter, rarely accessed directly.
* NOTE: Rather than calling this function directly use CRM_*_BAO_*::buildOptions()
*
* @param String $daoName
* @param String $fieldName
* @param Array $params
* - name string name of the option group
* - flip boolean results are return in id => label format if false
* if true, the results are reversed
* - grouping boolean if true, return the value in 'grouping' column (currently unsupported for tables other than option_value)
* - localize boolean if true, localize the results before returning
* - condition string|array add condition(s) to the sql query - will be concatenated using 'AND'
* - keyColumn string the column to use for 'id'
* - labelColumn string the column to use for 'label'
* - orderColumn string the column to use for sorting, defaults to 'weight' column if one exists, else defaults to labelColumn
* - onlyActive boolean return only the action option values
* - fresh boolean ignore cache entries and go back to DB
* @param String $context: Context string
*
* @return Array on success, FALSE on error.
*
* @static
*/
public static function get($daoName, $fieldName, $params = array(), $context = NULL)
{
CRM_Core_DAO::buildOptionsContext($context);
$flip = !empty($params['flip']);
// Merge params with defaults
$params += array('grouping' => FALSE, 'localize' => FALSE, 'onlyActive' => $context == 'validate' || $context == 'get' ? FALSE : TRUE, 'fresh' => FALSE);
// Custom fields are not in the schema
if (strpos($fieldName, 'custom_') === 0 && is_numeric($fieldName[7])) {
$customField = new CRM_Core_DAO_CustomField();
$customField->id = (int) substr($fieldName, 7);
$customField->find(TRUE);
$options = FALSE;
if (!empty($customField->option_group_id)) {
$options = CRM_Core_OptionGroup::valuesByID($customField->option_group_id, $flip, $params['grouping'], $params['localize'], CRM_Utils_Array::value('labelColumn', $params, 'label'), $params['onlyActive'], $params['fresh']);
} else {
if ($customField->data_type === 'StateProvince') {
$options = self::stateProvince();
} elseif ($customField->data_type === 'Country') {
$options = $context == 'validate' ? self::countryIsoCode() : self::country();
} elseif ($customField->data_type === 'Boolean') {
$options = $context == 'validate' ? array(0, 1) : array(1 => ts('Yes'), 0 => ts('No'));
}
$options = $options && $flip ? array_flip($options) : $options;
}
if ($options !== FALSE) {
CRM_Utils_Hook::customFieldOptions($customField->id, $options, FALSE);
}
$customField->free();
return $options;
}
// Core field: load schema
$dao = new $daoName();
$fields = $dao->fields();
$fieldKeys = $dao->fieldKeys();
$dao->free();
// Support "unique names" as well as sql names
$fieldKey = $fieldName;
if (empty($fields[$fieldKey])) {
$fieldKey = CRM_Utils_Array::value($fieldName, $fieldKeys);
}
// If neither worked then this field doesn't exist. Return false.
if (empty($fields[$fieldKey])) {
return FALSE;
}
$fieldSpec = $fields[$fieldKey];
// If the field is an enum, explode the enum definition and return the array.
if (isset($fieldSpec['enumValues'])) {
// use of a space after the comma is inconsistent in xml
$enumStr = str_replace(', ', ',', $fieldSpec['enumValues']);
$output = explode(',', $enumStr);
return array_combine($output, $output);
} elseif (!empty($fieldSpec['pseudoconstant'])) {
$pseudoconstant = $fieldSpec['pseudoconstant'];
// Merge params with schema defaults
$params += array('condition' => CRM_Utils_Array::value('condition', $pseudoconstant, array()), 'keyColumn' => CRM_Utils_Array::value('keyColumn', $pseudoconstant), 'labelColumn' => CRM_Utils_Array::value('labelColumn', $pseudoconstant));
// Fetch option group from option_value table
if (!empty($pseudoconstant['optionGroupName'])) {
if ($context == 'validate') {
$params['labelColumn'] = 'name';
}
// Call our generic fn for retrieving from the option_value table
return CRM_Core_OptionGroup::values($pseudoconstant['optionGroupName'], $flip, $params['grouping'], $params['localize'], $params['condition'] ? ' AND ' . implode(' AND ', (array) $params['condition']) : NULL, $params['labelColumn'] ? $params['labelColumn'] : 'label', $params['onlyActive'], $params['fresh'], $params['keyColumn'] ? $params['keyColumn'] : 'value');
}
// Fetch options from other tables
if (!empty($pseudoconstant['table'])) {
// Normalize params so the serialized cache string will be consistent.
CRM_Utils_Array::remove($params, 'flip', 'fresh');
ksort($params);
$cacheKey = $daoName . $fieldName . serialize($params);
// Retrieve cached options
if (isset(self::$cache[$cacheKey]) && empty($params['fresh'])) {
$output = self::$cache[$cacheKey];
} else {
$daoName = CRM_Core_DAO_AllCoreTables::getClassForTable($pseudoconstant['table']);
if (!class_exists($daoName)) {
return FALSE;
}
// Get list of fields for the option table
$dao = new $daoName();
$availableFields = array_keys($dao->fieldKeys());
$dao->free();
$select = "SELECT %1 AS id, %2 AS label";
$from = "FROM %3";
$wheres = array();
$order = "ORDER BY %2";
// Use machine name instead of label in validate context
if ($context == 'validate') {
if (!empty($pseudoconstant['nameColumn'])) {
$params['labelColumn'] = $pseudoconstant['nameColumn'];
} elseif (in_array('name', $availableFields)) {
$params['labelColumn'] = 'name';
}
}
// Condition param can be passed as an sql clause string or an array of clauses
if (!empty($params['condition'])) {
$wheres[] = implode(' AND ', (array) $params['condition']);
}
// onlyActive param will automatically filter on common flags
if (!empty($params['onlyActive'])) {
foreach (array('is_active' => 1, 'is_deleted' => 0, 'is_test' => 0) as $flag => $val) {
if (in_array($flag, $availableFields)) {
$wheres[] = "{$flag} = {$val}";
}
}
}
// Filter domain specific options
if (in_array('domain_id', $availableFields)) {
$wheres[] = 'domain_id = ' . CRM_Core_Config::domainID();
}
$queryParams = array(1 => array($params['keyColumn'], 'String', CRM_Core_DAO::QUERY_FORMAT_NO_QUOTES), 2 => array($params['labelColumn'], 'String', CRM_Core_DAO::QUERY_FORMAT_NO_QUOTES), 3 => array($pseudoconstant['table'], 'String', CRM_Core_DAO::QUERY_FORMAT_NO_QUOTES));
// Add orderColumn param
if (!empty($params['orderColumn'])) {
$queryParams[4] = array($params['orderColumn'], 'String', CRM_Core_DAO::QUERY_FORMAT_NO_QUOTES);
$order = "ORDER BY %4";
} elseif (isset($params['orderColumn']) && $params['orderColumn'] === FALSE) {
$order = '';
} elseif (in_array('weight', $availableFields)) {
$order = "ORDER BY weight";
}
$output = array();
$query = "{$select} {$from}";
if ($wheres) {
$query .= " WHERE " . implode($wheres, ' AND ');
}
$query .= ' ' . $order;
$dao = CRM_Core_DAO::executeQuery($query, $queryParams);
while ($dao->fetch()) {
$output[$dao->id] = $dao->label;
}
$dao->free();
// Localize results
if (!empty($params['localize']) || $pseudoconstant['table'] == 'civicrm_country' || $pseudoconstant['table'] == 'civicrm_state_province') {
$I18nParams = array();
if ($pseudoconstant['table'] == 'civicrm_country') {
$I18nParams['context'] = 'country';
}
if ($pseudoconstant['table'] == 'civicrm_state_province') {
$I18nParams['context'] = 'province';
}
$i18n = CRM_Core_I18n::singleton();
$i18n->localizeArray($output, $I18nParams);
// Maintain sort by label
if ($order == "ORDER BY %2") {
CRM_Utils_Array::asort($output);
}
}
self::$cache[$cacheKey] = $output;
}
return $flip ? array_flip($output) : $output;
}
} elseif (CRM_Utils_Array::value('type', $fieldSpec) === CRM_Utils_Type::T_BOOLEAN) {
$output = $context == 'validate' ? array(0, 1) : array(1 => ts('Yes'), 0 => ts('No'));
return $flip ? array_flip($output) : $output;
}
// If we're still here, it's an error. Return FALSE.
return FALSE;
}
/**
* API wrapper for getoptions function
*
* @param array $apiRequest api request as an array.
*
* @return array of results
*/
function civicrm_api3_generic_getoptions($apiRequest)
{
// Resolve aliases
$fieldName = _civicrm_api3_api_resolve_alias($apiRequest['entity'], $apiRequest['params']['field']);
if (!$fieldName) {
return civicrm_api3_create_error("The field '{$apiRequest['params']['field']}' doesn't exist.");
}
// Validate 'context' from params
$context = CRM_Utils_Array::value('context', $apiRequest['params']);
CRM_Core_DAO::buildOptionsContext($context);
unset($apiRequest['params']['context'], $apiRequest['params']['field']);
$baoName = _civicrm_api3_get_BAO($apiRequest['entity']);
$options = $output = $baoName::buildOptions($fieldName, $context, $apiRequest['params']);
if ($options === FALSE) {
return civicrm_api3_create_error("The field '{$fieldName}' has no associated option list.");
}
// Support 'sequential' output as a non-associative array
if (!empty($apiRequest['params']['sequential'])) {
$output = array();
foreach ($options as $key => $val) {
$output[] = array('key' => $key, 'value' => $val);
}
}
return civicrm_api3_create_success($output);
}
/**
* @param string $context
* @return array|bool
*/
public function getOptions($context = NULL)
{
CRM_Core_DAO::buildOptionsContext($context);
if (!$this->id) {
return FALSE;
}
if (!$this->data_type || !$this->custom_group_id) {
$this->find(TRUE);
}
if (!empty($this->option_group_id)) {
$options = CRM_Core_OptionGroup::valuesByID($this->option_group_id, FALSE, FALSE, FALSE, 'label', !($context == 'validate' || $context == 'get'));
} elseif ($this->data_type === 'StateProvince') {
$options = CRM_Core_Pseudoconstant::stateProvince();
} elseif ($this->data_type === 'Country') {
$options = $context == 'validate' ? CRM_Core_Pseudoconstant::countryIsoCode() : CRM_Core_Pseudoconstant::country();
} elseif ($this->data_type === 'Boolean') {
$options = $context == 'validate' ? array(0, 1) : CRM_Core_SelectValues::boolean();
} else {
return FALSE;
}
CRM_Utils_Hook::customFieldOptions($this->id, $options, FALSE);
CRM_Utils_Hook::fieldOptions($this->getEntity(), "custom_{$this->id}", $options, array('context' => $context));
return $options;
}
/**
* Low-level option getter, rarely accessed directly.
* NOTE: Rather than calling this function directly use CRM_*_BAO_*::buildOptions()
* @see http://wiki.civicrm.org/confluence/display/CRMDOC/Pseudoconstant+%28option+list%29+Reference
*
* NOTE: If someone undertakes a refactoring of this, please consider the use-case of
* the Setting.getoptions API. There is no DAO/field, but it would be nice to use the
* same 'pseudoconstant' struct in *.settings.php. This means loosening the coupling
* between $field lookup and the $pseudoconstant evaluation.
*
* @param string $daoName
* @param string $fieldName
* @param array $params
* - name string name of the option group
* - flip boolean results are return in id => label format if false
* if true, the results are reversed
* - grouping boolean if true, return the value in 'grouping' column (currently unsupported for tables other than option_value)
* - localize boolean if true, localize the results before returning
* - condition string|array add condition(s) to the sql query - will be concatenated using 'AND'
* - keyColumn string the column to use for 'id'
* - labelColumn string the column to use for 'label'
* - orderColumn string the column to use for sorting, defaults to 'weight' column if one exists, else defaults to labelColumn
* - onlyActive boolean return only the action option values
* - fresh boolean ignore cache entries and go back to DB
* @param string $context : Context string
*
* @return array|bool
* array on success, FALSE on error.
*
*/
public static function get($daoName, $fieldName, $params = array(), $context = NULL)
{
CRM_Core_DAO::buildOptionsContext($context);
$flip = !empty($params['flip']);
// Merge params with defaults
$params += array('grouping' => FALSE, 'localize' => FALSE, 'onlyActive' => $context == 'validate' || $context == 'get' ? FALSE : TRUE, 'fresh' => FALSE, 'context' => $context);
$entity = CRM_Core_DAO_AllCoreTables::getBriefName(CRM_Core_DAO_AllCoreTables::getCanonicalClassName($daoName));
// Custom fields are not in the schema
if (strpos($fieldName, 'custom_') === 0 && is_numeric($fieldName[7])) {
$customField = new CRM_Core_BAO_CustomField();
$customField->id = (int) substr($fieldName, 7);
$options = $customField->getOptions();
if ($options && $flip) {
$options = array_flip($options);
}
$customField->free();
return $options;
}
// Core field: load schema
$dao = new $daoName();
$fieldSpec = $dao->getFieldSpec($fieldName);
$dao->free();
// Ensure we have the canonical name for this field
$fieldName = CRM_Utils_Array::value('name', $fieldSpec, $fieldName);
// Return false if field doesn't exist.
if (empty($fieldSpec)) {
return FALSE;
} elseif (!empty($fieldSpec['pseudoconstant'])) {
$pseudoconstant = $fieldSpec['pseudoconstant'];
// if callback is specified..
if (!empty($pseudoconstant['callback'])) {
return call_user_func(Civi\Core\Resolver::singleton()->get($pseudoconstant['callback']));
}
// Merge params with schema defaults
$params += array('condition' => CRM_Utils_Array::value('condition', $pseudoconstant, array()), 'keyColumn' => CRM_Utils_Array::value('keyColumn', $pseudoconstant), 'labelColumn' => CRM_Utils_Array::value('labelColumn', $pseudoconstant));
if ($context == 'abbreviate') {
switch ($fieldName) {
case 'state_province_id':
$params['labelColumn'] = 'abbreviation';
break;
case 'country_id':
$params['labelColumn'] = 'iso_code';
break;
default:
}
}
// Fetch option group from option_value table
if (!empty($pseudoconstant['optionGroupName'])) {
if ($context == 'validate') {
$params['labelColumn'] = 'name';
}
if ($context == 'match') {
$params['keyColumn'] = 'name';
}
// Call our generic fn for retrieving from the option_value table
$options = CRM_Core_OptionGroup::values($pseudoconstant['optionGroupName'], $flip, $params['grouping'], $params['localize'], $params['condition'] ? ' AND ' . implode(' AND ', (array) $params['condition']) : NULL, $params['labelColumn'] ? $params['labelColumn'] : 'label', $params['onlyActive'], $params['fresh'], $params['keyColumn'] ? $params['keyColumn'] : 'value');
CRM_Utils_Hook::fieldOptions($entity, $fieldName, $options, $params);
return $options;
}
// Fetch options from other tables
if (!empty($pseudoconstant['table'])) {
// Normalize params so the serialized cache string will be consistent.
CRM_Utils_Array::remove($params, 'flip', 'fresh');
ksort($params);
$cacheKey = $daoName . $fieldName . serialize($params);
// Retrieve cached options
if (isset(self::$cache[$cacheKey]) && empty($params['fresh'])) {
$output = self::$cache[$cacheKey];
} else {
$daoName = CRM_Core_DAO_AllCoreTables::getClassForTable($pseudoconstant['table']);
if (!class_exists($daoName)) {
return FALSE;
}
// Get list of fields for the option table
$dao = new $daoName();
$availableFields = array_keys($dao->fieldKeys());
$dao->free();
$select = "SELECT %1 AS id, %2 AS label";
$from = "FROM %3";
$wheres = array();
$order = "ORDER BY %2";
// Use machine name in certain contexts
if ($context == 'validate' || $context == 'match') {
$nameField = $context == 'validate' ? 'labelColumn' : 'keyColumn';
if (!empty($pseudoconstant['nameColumn'])) {
$params[$nameField] = $pseudoconstant['nameColumn'];
} elseif (in_array('name', $availableFields)) {
$params[$nameField] = 'name';
}
}
// Condition param can be passed as an sql clause string or an array of clauses
if (!empty($params['condition'])) {
$wheres[] = implode(' AND ', (array) $params['condition']);
}
// onlyActive param will automatically filter on common flags
if (!empty($params['onlyActive'])) {
foreach (array('is_active' => 1, 'is_deleted' => 0, 'is_test' => 0, 'is_hidden' => 0) as $flag => $val) {
if (in_array($flag, $availableFields)) {
$wheres[] = "{$flag} = {$val}";
}
}
}
// Filter domain specific options
if (in_array('domain_id', $availableFields)) {
$wheres[] = 'domain_id = ' . CRM_Core_Config::domainID();
}
$queryParams = array(1 => array($params['keyColumn'], 'String', CRM_Core_DAO::QUERY_FORMAT_NO_QUOTES), 2 => array($params['labelColumn'], 'String', CRM_Core_DAO::QUERY_FORMAT_NO_QUOTES), 3 => array($pseudoconstant['table'], 'String', CRM_Core_DAO::QUERY_FORMAT_NO_QUOTES));
// Add orderColumn param
if (!empty($params['orderColumn'])) {
$queryParams[4] = array($params['orderColumn'], 'String', CRM_Core_DAO::QUERY_FORMAT_NO_QUOTES);
$order = "ORDER BY %4";
} elseif (isset($params['orderColumn']) && $params['orderColumn'] === FALSE) {
$order = '';
} elseif (in_array('weight', $availableFields)) {
$order = "ORDER BY weight";
}
$output = array();
$query = "{$select} {$from}";
if ($wheres) {
$query .= " WHERE " . implode($wheres, ' AND ');
}
$query .= ' ' . $order;
$dao = CRM_Core_DAO::executeQuery($query, $queryParams);
while ($dao->fetch()) {
$output[$dao->id] = $dao->label;
}
$dao->free();
// Localize results
if (!empty($params['localize']) || $pseudoconstant['table'] == 'civicrm_country' || $pseudoconstant['table'] == 'civicrm_state_province') {
$I18nParams = array();
if ($pseudoconstant['table'] == 'civicrm_country') {
$I18nParams['context'] = 'country';
}
if ($pseudoconstant['table'] == 'civicrm_state_province') {
$I18nParams['context'] = 'province';
}
$i18n = CRM_Core_I18n::singleton();
$i18n->localizeArray($output, $I18nParams);
// Maintain sort by label
if ($order == "ORDER BY %2") {
CRM_Utils_Array::asort($output);
}
}
CRM_Utils_Hook::fieldOptions($entity, $fieldName, $output, $params);
self::$cache[$cacheKey] = $output;
}
return $flip ? array_flip($output) : $output;
}
} elseif (CRM_Utils_Array::value('type', $fieldSpec) === CRM_Utils_Type::T_BOOLEAN) {
$output = $context == 'validate' ? array(0, 1) : CRM_Core_SelectValues::boolean();
CRM_Utils_Hook::fieldOptions($entity, $fieldName, $output, $params);
return $flip ? array_flip($output) : $output;
}
// If we're still here, it's an error. Return FALSE.
return FALSE;
}
