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   $params['event_tz']['api.default'] = CRM_Core_Config::singleton()->userSystem->getTimeZoneString();
  63 }
  64
  65 /**
  66  * Support for schema changes made in 4.2.
  67  *
  68  * The main purpose of the API is to provide integrators a level of stability not provided by
  69  * the core code or schema - this means we have to provide support for api calls (where possible)
  70  * across schema changes.
  71  *
  72  * @param array $params
  73  */
  74 function _civicrm_api3_event_create_legacy_support_42(&$params) {
  75   if (!empty($params['payment_processor_id'])) {
  76     $params['payment_processor'] = CRM_Core_DAO::VALUE_SEPARATOR . $params['payment_processor_id'] . CRM_Core_DAO::VALUE_SEPARATOR;
  77   }
  78 }
  79
  80 /**
  81  * Get Event record.
  82  *
  83  * @param array $params
  84  *
  85  * @return array
  86  *   Array of all found event property values.
  87  */
  88 function civicrm_api3_event_get($params) {
  89
  90   //legacy support for $params['return.sort']
  91   if (!empty($params['return.sort'])) {
  92     $params['options']['sort'] = $params['return.sort'];
  93     unset($params['return.sort']);
  94   }
  95
  96   //legacy support for $params['return.offset']
  97   if (!empty($params['return.offset'])) {
  98     $params['options']['offset'] = $params['return.offset'];
  99     unset($params['return.offset']);
 100   }
 101
 102   //legacy support for $params['return.max_results']
 103   if (!empty($params['return.max_results'])) {
 104     $params['options']['limit'] = $params['return.max_results'];
 105     unset($params['return.max_results']);
 106   }
 107
 108   $sql = CRM_Utils_SQL_Select::fragment();
 109   if (!empty($params['isCurrent'])) {
 110     $sql->where('(start_date >= CURDATE() || end_date >= CURDATE())');
 111   }
 112
 113   $events = _civicrm_api3_basic_get(_civicrm_api3_get_BAO(__FUNCTION__), $params, FALSE, 'Event', $sql, TRUE);
 114   $options = _civicrm_api3_get_options_from_params($params, TRUE);
 115   if ($options['is_count']) {
 116     return civicrm_api3_create_success($events, $params, 'Event', 'get');
 117   }
 118   foreach ($events as $id => $event) {
 119     if (!empty($options['return']['is_full'])) {
 120       _civicrm_api3_event_getisfull($events, $id);
 121     }
 122     _civicrm_api3_event_get_legacy_support_42($events, $id);
 123     if (!empty($options['return']['price_set_id'])) {
 124       $events[$id]['price_set_id'] = CRM_Price_BAO_PriceSet::getFor('civicrm_event', $id);
 125     }
 126   }
 127
 128   return civicrm_api3_create_success($events, $params, 'Event', 'get');
 129 }
 130
 131 /**
 132  * Adjust Metadata for Get action.
 133  *
 134  * The metadata is used for setting defaults, documentation & validation.
 135  *
 136  * @param array $params
 137  *   Array of parameters determined by getfields.
 138  */
 139 function _civicrm_api3_event_get_spec(&$params) {
 140   $params['financial_type_id']['api.aliases'] = ['contribution_type_id'];
 141 }
 142
 143 /**
 144  * Support for schema changes made in 4.2.
 145  *
 146  * The main purpose of the API is to provide integrators a level of stability not provided by
 147  * the core code or schema - this means we have to provide support for api calls (where possible)
 148  * across schema changes.
 149  *
 150  * @param array $event
 151  * @param int $event_id
 152  */
 153 function _civicrm_api3_event_get_legacy_support_42(&$event, $event_id) {
 154   if (!empty($event[$event_id]['payment_processor'])) {
 155     $processors = explode(CRM_Core_DAO::VALUE_SEPARATOR, $event[$event_id]['payment_processor']);
 156     if (count($processors) == 3) {
 157       $event[$event_id]['payment_processor_id'] = $processors[1];
 158     }
 159   }
 160 }
 161
 162 /**
 163  * Delete an existing Event.
 164  *
 165  * This API is used for deleting a event given its id.
 166  *
 167  * @param array $params
 168  *
 169  * @return array
 170  */
 171 function civicrm_api3_event_delete($params) {
 172   return CRM_Event_BAO_Event::del($params['id']) ? civicrm_api3_create_success() : civicrm_api3_create_error(ts('Error while deleting event'));
 173 }
 174
 175 /**
 176  * Add 'is_full' & 'available_seats' to the return array.
 177  *
 178  * (this might be better in the BAO)
 179  * Default BAO function returns a string if full rather than a Bool - which is more appropriate to a form
 180  *
 181  * @param array $event
 182  *   Return array of the event.
 183  * @param int $event_id
 184  *   Id of the event to be updated.
 185  */
 186 function _civicrm_api3_event_getisfull(&$event, $event_id) {
 187   $eventFullResult = CRM_Event_BAO_Participant::eventFull($event_id, 1);
 188   if (!empty($eventFullResult) && is_int($eventFullResult)) {
 189     $event[$event_id]['available_places'] = $eventFullResult;
 190   }
 191   elseif (is_null($eventFullResult)) {
 192     return $event[$event_id]['is_full'] = 0;
 193   }
 194   else {
 195     $event[$event_id]['available_places'] = 0;
 196   }
 197   $event[$event_id]['is_full'] = $event[$event_id]['available_places'] == 0 ? 1 : 0;
 198 }
 199
 200 /**
 201  * Get event list parameters.
 202  *
 203  * @see _civicrm_api3_generic_getlist_params
 204  *
 205  * @param array $request
 206  */
 207 function _civicrm_api3_event_getlist_params(&$request) {
 208   $fieldsToReturn = [
 209     'start_date',
 210     'event_type_id',
 211     'title',
 212     'summary',
 213     $request['id_field'],
 214     $request['label_field'],
 215   ];
 216   $request['params']['return'] = array_unique(array_merge($fieldsToReturn, $request['extra']));
 217   $request['params']['options']['sort'] = 'start_date DESC';
 218   if (empty($request['params']['id'])) {
 219     $request['params'] += [
 220       'is_template' => 0,
 221       'is_active' => 1,
 222     ];
 223   }
 224 }
 225
 226 /**
 227  * Get event list output.
 228  *
 229  * @see _civicrm_api3_generic_getlist_output
 230  *
 231  * @param array $result
 232  * @param array $request
 233  *
 234  * @return array
 235  */
 236 function _civicrm_api3_event_getlist_output($result, $request) {
 237   $output = [];
 238   if (!empty($result['values'])) {
 239     foreach ($result['values'] as $row) {
 240       $data = [
 241         'id' => $row[$request['id_field']],
 242         'label' => $row[$request['label_field']],
 243         'description' => [
 244           CRM_Core_PseudoConstant::getLabel('CRM_Event_BAO_Event', 'event_type_id', $row['event_type_id']),
 245         ],
 246       ];
 247       if (!empty($row['start_date'])) {
 248         $data['description'][0] .= ': ' . CRM_Utils_Date::customFormat($row['start_date']);
 249       }
 250       if (!empty($row['summary'])) {
 251         $data['description'][] = $row['summary'];
 252       }
 253       // Add repeating info
 254       $repeat = CRM_Core_BAO_RecurringEntity::getPositionAndCount($row['id'], 'civicrm_event');
 255       $data['extra']['is_recur'] = FALSE;
 256       if ($repeat) {
 257         $data['suffix'] = ts('(%1 of %2)', [1 => $repeat[0], 2 => $repeat[1]]);
 258         $data['extra']['is_recur'] = TRUE;
 259       }
 260       $output[] = $data;
 261     }
 262   }
 263   return $output;
 264 }
 265
 266 /**
 267  * Add missing timezones to all events.
 268  *
 269  * @return array
 270  */
 271 function civicrm_api3_event_addmissingtimezones($params) {
 272   $defaultTZ = CRM_Core_Config::singleton()->userSystem->getTimeZoneString();
 273
 274   CRM_Core_DAO::executeQuery('UPDATE civicrm_event SET event_tz = %1 WHERE event_tz IS NULL OR event_tz = ""', [1 => [$defaultTZ, 'String']]);
 275   return civicrm_api3_create_success($events, $params, 'Event', 'addMissingTimezones');
 276 }