api/v3/Generic/Getlist.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4 | CiviCRM version 4.6                                                |
   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  * Generic api wrapper used for quicksearch and autocomplete.
  29  *
  30  * @param array $apiRequest
  31  *
  32  * @return mixed
  33  */
  34 function civicrm_api3_generic_getList($apiRequest) {
  35   $entity = _civicrm_api_get_entity_name_from_camel($apiRequest['entity']);
  36   $request = $apiRequest['params'];
  37
  38   // Hey api, would you like to provide default values?
  39   $fnName = "_civicrm_api3_{$entity}_getlist_defaults";
  40   $defaults = function_exists($fnName) ? $fnName($request) : array();
  41   _civicrm_api3_generic_getList_defaults($entity, $request, $defaults);
  42
  43   // Hey api, would you like to format the search params?
  44   $fnName = "_civicrm_api3_{$entity}_getlist_params";
  45   $fnName = function_exists($fnName) ? $fnName : '_civicrm_api3_generic_getlist_params';
  46   $fnName($request);
  47
  48   $request['params']['check_permissions'] = !empty($apiRequest['params']['check_permissions']);
  49   $result = civicrm_api3($entity, 'get', $request['params']);
  50
  51   // Hey api, would you like to format the output?
  52   $fnName = "_civicrm_api3_{$entity}_getlist_output";
  53   $fnName = function_exists($fnName) ? $fnName : '_civicrm_api3_generic_getlist_output';
  54   $values = $fnName($result, $request);
  55
  56   $output = array('page_num' => $request['page_num']);
  57
  58   // Limit is set for searching but not fetching by id
  59   if (!empty($request['params']['options']['limit'])) {
  60     // If we have an extra result then this is not the last page
  61     $last = $request['params']['options']['limit'] - 1;
  62     $output['more_results'] = isset($values[$last]);
  63     unset($values[$last]);
  64   }
  65
  66   return civicrm_api3_create_success($values, $request['params'], $entity, 'getlist', CRM_Core_DAO::$_nullObject, $output);
  67 }
  68
  69 /**
  70  * Set defaults for api.getlist
  71  *
  72  * @param string $entity
  73  * @param array $request
  74  * @param array $apiDefaults
  75  */
  76 function _civicrm_api3_generic_getList_defaults($entity, &$request, $apiDefaults) {
  77   $config = CRM_Core_Config::singleton();
  78   $fields = _civicrm_api_get_fields($entity);
  79   $defaults = array(
  80     'page_num' => 1,
  81     'input' => '',
  82     'image_field' => NULL,
  83     'id_field' => $entity == 'option_value' ? 'value' : 'id',
  84     'description_field' => array(),
  85     'params' => array(),
  86     'extra' => array(),
  87   );
  88   // Find main field from meta
  89   foreach (array('sort_name', 'title', 'label', 'name', 'subject') as $field) {
  90     if (isset($fields[$field])) {
  91       $defaults['label_field'] = $defaults['search_field'] = $field;
  92       break;
  93     }
  94   }
  95   // Find fields to be used for the description
  96   foreach (array('description') as $field) {
  97     if (isset($fields[$field])) {
  98       $defaults['description_field'][] = $field;
  99     }
 100   }
 101   $resultsPerPage = CRM_Core_BAO_Setting::getItem(CRM_Core_BAO_Setting::SYSTEM_PREFERENCES_NAME, 'search_autocomplete_count', NULL, 10);
 102   $request += $apiDefaults + $defaults;
 103   // Default api params
 104   $params = array(
 105     'options' => array(
 106       // Adding one extra result allows us to see if there are any more
 107       'limit' => $resultsPerPage + 1,
 108       // Because sql is zero-based
 109       'offset' => ($request['page_num'] - 1) * $resultsPerPage,
 110       'sort' => $request['label_field'],
 111     ),
 112     'sequential' => 1,
 113   );
 114   // When searching e.g. autocomplete
 115   if ($request['input']) {
 116     $params[$request['search_field']] = array('LIKE' => ($config->includeWildCardInName ? '%' : '') . $request['input'] . '%');
 117   }
 118   // When looking up a field e.g. displaying existing record
 119   if (!empty($request['id'])) {
 120     if (is_string($request['id']) && strpos($request['id'], ',')) {
 121       $request['id'] = explode(',', trim($request['id'], ', '));
 122     }
 123     // Don't run into search limits when prefilling selection
 124     $params['options']['limit'] = NULL;
 125     unset($params['options']['offset'], $request['params']['options']['limit'], $request['params']['options']['offset']);
 126     $params[$request['id_field']] = is_array($request['id']) ? array('IN' => $request['id']) : $request['id'];
 127   }
 128   $request['params'] += $params;
 129 }
 130
 131 /**
 132  * Fallback implementation of getlist_params. May be overridden by individual apis
 133  *
 134  * @param array $request
 135  */
 136 function _civicrm_api3_generic_getlist_params(&$request) {
 137   $fieldsToReturn = array($request['id_field'], $request['label_field']);
 138   if (!empty($request['image_field'])) {
 139     $fieldsToReturn[] = $request['image_field'];
 140   }
 141   if (!empty($request['description_field'])) {
 142     $fieldsToReturn = array_merge($fieldsToReturn, (array) $request['description_field']);
 143   }
 144   $request['params']['return'] = array_unique(array_merge($fieldsToReturn, $request['extra']));
 145 }
 146
 147 /**
 148  * Fallback implementation of getlist_output. May be overridden by individual apis
 149  *
 150  * @param array $result
 151  * @param array $request
 152  *
 153  * @return array
 154  */
 155 function _civicrm_api3_generic_getlist_output($result, $request) {
 156   $output = array();
 157   if (!empty($result['values'])) {
 158     foreach ($result['values'] as $row) {
 159       $data = array(
 160         'id' => $row[$request['id_field']],
 161         'label' => $row[$request['label_field']],
 162       );
 163       if (!empty($request['description_field'])) {
 164         $data['description'] = array();
 165         foreach ((array) $request['description_field'] as $field) {
 166           if (!empty($row[$field])) {
 167             $data['description'][] = $row[$field];
 168           }
 169         }
 170       };
 171       if (!empty($request['image_field'])) {
 172         $data['image'] = isset($row[$request['image_field']]) ? $row[$request['image_field']] : '';
 173       }
 174       foreach ($request['extra'] as $field) {
 175         $data['extra'][$field] = isset($row[$field]) ? $row[$field] : NULL;
 176       }
 177       $output[] = $data;
 178     }
 179   }
 180   return $output;
 181 }