api/v3/Event.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | Copyright CiviCRM LLC. All rights reserved.                        |
   5  |                                                                    |
   6  | This work is published under the GNU AGPLv3 license with some      |
   7  | permitted exceptions and without any warranty. For full license    |
   8  | and copyright information, see https://civicrm.org/licensing       |
   9  +--------------------------------------------------------------------+
  10  */
  11
  12 /**
  13  *
  14  * This api exposes CiviCRM Event.
  15  *
  16  * @package CiviCRM_APIv3
  17  */
  18
  19 /**
  20  * Create a Event.
  21  *
  22  * @param array $params
  23  *   Input parameters.
  24  *
  25  * @return array
  26  *   API result Array.
  27  * @throws \CRM_Core_Exception
  28  * @throws \API_Exception
  29  */
  30 function civicrm_api3_event_create($params) {
  31   // Required fields for creating an event
  32   if (empty($params['id']) && empty($params['is_template'])) {
  33     civicrm_api3_verify_mandatory($params, NULL, [
  34       'start_date',
  35       'title',
  36       ['event_type_id', 'template_id'],
  37     ]);
  38   }
  39   // Required fields for creating an event template
  40   elseif (empty($params['id']) && !empty($params['is_template'])) {
  41     civicrm_api3_verify_mandatory($params, NULL, [
  42       'template_title',
  43     ]);
  44   }
  45
  46   _civicrm_api3_event_create_legacy_support_42($params);
  47   return _civicrm_api3_basic_create(_civicrm_api3_get_BAO(__FUNCTION__), $params, 'Event');
  48 }
  49
  50 /**
  51  * Adjust Metadata for Create action.
  52  *
  53  * The metadata is used for setting defaults, documentation & validation.
  54  *
  55  * @param array $params
  56  *   Array of parameters determined by getfields.
  57  */
  58 function _civicrm_api3_event_create_spec(&$params) {
  59   $params['is_active']['api.default'] = 1;
  60   $params['financial_type_id']['api.aliases'] = ['contribution_type_id'];
  61   $params['is_template']['api.default'] = 0;
  62 }
  63
  64 /**
  65  * Support for schema changes made in 4.2.
  66  *
  67  * The main purpose of the API is to provide integrators a level of stability not provided by
  68  * the core code or schema - this means we have to provide support for api calls (where possible)
  69  * across schema changes.
  70  *
  71  * @param array $params
  72  */
  73 function _civicrm_api3_event_create_legacy_support_42(&$params) {
  74   if (!empty($params['payment_processor_id'])) {
  75     $params['payment_processor'] = CRM_Core_DAO::VALUE_SEPARATOR . $params['payment_processor_id'] . CRM_Core_DAO::VALUE_SEPARATOR;
  76   }
  77 }
  78
  79 /**
  80  * Get Event record.
  81  *
  82  * @param array $params
  83  *
  84  * @return array
  85  *   Array of all found event property values.
  86  */
  87 function civicrm_api3_event_get($params) {
  88
  89   //legacy support for $params['return.sort']
  90   if (!empty($params['return.sort'])) {
  91     $params['options']['sort'] = $params['return.sort'];
  92     unset($params['return.sort']);
  93   }
  94
  95   //legacy support for $params['return.offset']
  96   if (!empty($params['return.offset'])) {
  97     $params['options']['offset'] = $params['return.offset'];
  98     unset($params['return.offset']);
  99   }
 100
 101   //legacy support for $params['return.max_results']
 102   if (!empty($params['return.max_results'])) {
 103     $params['options']['limit'] = $params['return.max_results'];
 104     unset($params['return.max_results']);
 105   }
 106
 107   $sql = CRM_Utils_SQL_Select::fragment();
 108   if (!empty($params['isCurrent'])) {
 109     $sql->where('(start_date >= CURDATE() || end_date >= CURDATE())');
 110   }
 111
 112   $events = _civicrm_api3_basic_get(_civicrm_api3_get_BAO(__FUNCTION__), $params, FALSE, 'Event', $sql, TRUE);
 113   $options = _civicrm_api3_get_options_from_params($params, TRUE);
 114   if ($options['is_count']) {
 115     return civicrm_api3_create_success($events, $params, 'Event', 'get');
 116   }
 117   foreach ($events as $id => $event) {
 118     if (!empty($options['return']['is_full'])) {
 119       _civicrm_api3_event_getisfull($events, $id);
 120     }
 121     _civicrm_api3_event_get_legacy_support_42($events, $id);
 122     if (!empty($options['return']['price_set_id'])) {
 123       $events[$id]['price_set_id'] = CRM_Price_BAO_PriceSet::getFor('civicrm_event', $id);
 124     }
 125   }
 126
 127   return civicrm_api3_create_success($events, $params, 'Event', 'get');
 128 }
 129
 130 /**
 131  * Adjust Metadata for Get action.
 132  *
 133  * The metadata is used for setting defaults, documentation & validation.
 134  *
 135  * @param array $params
 136  *   Array of parameters determined by getfields.
 137  */
 138 function _civicrm_api3_event_get_spec(&$params) {
 139   $params['financial_type_id']['api.aliases'] = ['contribution_type_id'];
 140 }
 141
 142 /**
 143  * Support for schema changes made in 4.2.
 144  *
 145  * The main purpose of the API is to provide integrators a level of stability not provided by
 146  * the core code or schema - this means we have to provide support for api calls (where possible)
 147  * across schema changes.
 148  *
 149  * @param array $event
 150  * @param int $event_id
 151  */
 152 function _civicrm_api3_event_get_legacy_support_42(&$event, $event_id) {
 153   if (!empty($event[$event_id]['payment_processor'])) {
 154     $processors = explode(CRM_Core_DAO::VALUE_SEPARATOR, $event[$event_id]['payment_processor']);
 155     if (count($processors) == 3) {
 156       $event[$event_id]['payment_processor_id'] = $processors[1];
 157     }
 158   }
 159 }
 160
 161 /**
 162  * Delete an existing Event.
 163  *
 164  * This API is used for deleting a event given its id.
 165  *
 166  * @param array $params
 167  *
 168  * @return array
 169  */
 170 function civicrm_api3_event_delete($params) {
 171   return CRM_Event_BAO_Event::del($params['id']) ? civicrm_api3_create_success() : civicrm_api3_create_error(ts('Error while deleting event'));
 172 }
 173
 174 /**
 175  * Add 'is_full' & 'available_seats' to the return array.
 176  *
 177  * (this might be better in the BAO)
 178  * Default BAO function returns a string if full rather than a Bool - which is more appropriate to a form
 179  *
 180  * @param array $event
 181  *   Return array of the event.
 182  * @param int $event_id
 183  *   Id of the event to be updated.
 184  */
 185 function _civicrm_api3_event_getisfull(&$event, $event_id) {
 186   $eventFullResult = CRM_Event_BAO_Participant::eventFull($event_id, 1);
 187   if (!empty($eventFullResult) && is_int($eventFullResult)) {
 188     $event[$event_id]['available_places'] = $eventFullResult;
 189   }
 190   elseif (is_null($eventFullResult)) {
 191     return $event[$event_id]['is_full'] = 0;
 192   }
 193   else {
 194     $event[$event_id]['available_places'] = 0;
 195   }
 196   $event[$event_id]['is_full'] = $event[$event_id]['available_places'] == 0 ? 1 : 0;
 197 }
 198
 199 /**
 200  * Get event list parameters.
 201  *
 202  * @see _civicrm_api3_generic_getlist_params
 203  *
 204  * @param array $request
 205  */
 206 function _civicrm_api3_event_getlist_params(&$request) {
 207   $fieldsToReturn = ['start_date', 'event_type_id', 'title', 'summary'];
 208   $request['params']['return'] = array_unique(array_merge($fieldsToReturn, $request['extra']));
 209   $request['params']['options']['sort'] = 'start_date DESC';
 210   if (empty($request['params']['id'])) {
 211     $request['params'] += [
 212       'is_template' => 0,
 213       'is_active' => 1,
 214     ];
 215   }
 216 }
 217
 218 /**
 219  * Get event list output.
 220  *
 221  * @see _civicrm_api3_generic_getlist_output
 222  *
 223  * @param array $result
 224  * @param array $request
 225  *
 226  * @return array
 227  */
 228 function _civicrm_api3_event_getlist_output($result, $request) {
 229   $output = [];
 230   if (!empty($result['values'])) {
 231     foreach ($result['values'] as $row) {
 232       $data = [
 233         'id' => $row[$request['id_field']],
 234         'label' => $row[$request['label_field']],
 235         'description' => [
 236           CRM_Core_PseudoConstant::getLabel('CRM_Event_BAO_Event', 'event_type_id', $row['event_type_id']),
 237         ],
 238       ];
 239       if (!empty($row['start_date'])) {
 240         $data['description'][0] .= ': ' . CRM_Utils_Date::customFormat($row['start_date']);
 241       }
 242       if (!empty($row['summary'])) {
 243         $data['description'][] = $row['summary'];
 244       }
 245       // Add repeating info
 246       $repeat = CRM_Core_BAO_RecurringEntity::getPositionAndCount($row['id'], 'civicrm_event');
 247       $data['extra']['is_recur'] = FALSE;
 248       if ($repeat) {
 249         $data['suffix'] = ts('(%1 of %2)', [1 => $repeat[0], 2 => $repeat[1]]);
 250         $data['extra']['is_recur'] = TRUE;
 251       }
 252       $output[] = $data;
 253     }
 254   }
 255   return $output;
 256 }