api/v3/Participant.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  * This api exposes CiviCRM participant.
  14  *
  15  * @package CiviCRM_APIv3
  16  */
  17
  18 /**
  19  * Create an Event Participant.
  20  *
  21  * @param array $params
  22  *   An associative array of name/value property values of civicrm_participant.
  23  *
  24  * @return array
  25  *   API result array
  26  *
  27  * @throws \CiviCRM_API3_Exception
  28  * @throws \CRM_Core_Exception
  29  */
  30 function civicrm_api3_participant_create($params) {
  31   // Check that event id is not an template - should be done @ BAO layer.
  32   if (!empty($params['event_id'])) {
  33     $isTemplate = CRM_Core_DAO::getFieldValue('CRM_Event_DAO_Event', $params['event_id'], 'is_template');
  34     if (!empty($isTemplate)) {
  35       return civicrm_api3_create_error(ts('Event templates are not meant to be registered.'));
  36     }
  37   }
  38
  39   $values = $participant = [];
  40   _civicrm_api3_custom_format_params($params, $values, 'Participant');
  41   $params = array_merge($values, $params);
  42
  43   $participantBAO = CRM_Event_BAO_Participant::create($params);
  44
  45   if (empty($params['price_set_id']) && empty($params['id']) && !empty($params['fee_level'])) {
  46     _civicrm_api3_participant_createlineitem($params, $participantBAO);
  47   }
  48   _civicrm_api3_object_to_array($participantBAO, $participant[$participantBAO->id]);
  49
  50   return civicrm_api3_create_success($participant, $params, 'Participant', 'create', $participantBAO);
  51 }
  52
  53 /**
  54  * Create a default participant line item.
  55  *
  56  * @todo this should be done in the BAO not the api
  57  *
  58  * @param array $params
  59  * @param $participant
  60  *
  61  * @throws \CiviCRM_API3_Exception
  62  */
  63 function _civicrm_api3_participant_createlineitem(&$params, $participant) {
  64   // it is possible that a fee level contains information about multiple
  65   // price field values.
  66
  67   $priceFieldValueDetails = CRM_Utils_Array::explodePadded(
  68     $params["fee_level"]);
  69
  70   foreach ($priceFieldValueDetails as $detail) {
  71     if (preg_match('/- ([0-9]+)$/', $detail, $matches)) {
  72       // it is possible that a price field value is payd for multiple times.
  73       // (FIXME: if the price field value ends in minus followed by whitespace
  74       // and a number, things will go wrong.)
  75
  76       $qty = $matches[1];
  77       preg_match('/^(.*) - [0-9]+$/', $detail, $matches);
  78       $label = $matches[1];
  79     }
  80     else {
  81       $label = $detail;
  82       $qty = 1;
  83     }
  84
  85     $sql = "
  86       SELECT      ps.id AS setID, pf.id AS priceFieldID, pfv.id AS priceFieldValueID, pfv.amount AS amount
  87       FROM  civicrm_price_set_entity cpse
  88       LEFT JOIN civicrm_price_set ps ON cpse.price_set_id = ps.id AND cpse.entity_id = %1 AND cpse.entity_table = 'civicrm_event'
  89       LEFT JOIN   civicrm_price_field pf ON pf.`price_set_id` = ps.id
  90       LEFT JOIN   civicrm_price_field_value pfv ON pfv.price_field_id = pf.id
  91       where ps.id is not null and pfv.label = %2
  92     ";
  93
  94     $qParams = [
  95       1 => [$params['event_id'], 'Integer'],
  96       2 => [$label, 'String'],
  97     ];
  98
  99     $dao = CRM_Core_DAO::executeQuery($sql, $qParams);
 100     if ($dao->fetch()) {
 101       $lineItemParams = [
 102         'price_field_id' => $dao->priceFieldID,
 103         'price_field_value_id' => $dao->priceFieldValueID,
 104         'entity_table' => 'civicrm_participant',
 105         'entity_id' => $participant->id,
 106         'label' => $label,
 107         'qty' => $qty,
 108         'participant_count' => 0,
 109         'unit_price' => $dao->amount,
 110         'line_total' => $qty * $dao->amount,
 111       ];
 112       civicrm_api3('line_item', 'create', $lineItemParams);
 113     }
 114
 115   }
 116 }
 117
 118 /**
 119  * Adjust Metadata for Create action.
 120  *
 121  * The metadata is used for setting defaults, documentation & validation.
 122  *
 123  * @param array $params
 124  *   Array of parameters determined by getfields.
 125  */
 126 function _civicrm_api3_participant_create_spec(&$params) {
 127   $params['status_id']['api.default'] = "1";
 128   $params['register_date']['api.default'] = "now";
 129   $params['event_id']['api.required'] = 1;
 130   $params['contact_id']['api.required'] = 1;
 131   // These are for the sake of search builder options - can be removed if that is fixed
 132   $params['role_id']['api.aliases'] = ['participant_role'];
 133   $params['status_id']['api.aliases'] = ['participant_status'];
 134 }
 135
 136 /**
 137  * Retrieve a specific participant, given a set of input params.
 138  *
 139  * @param array $params
 140  *   input parameters.
 141  *
 142  * @return array
 143  *   array of properties, if error an array with an error id and error message
 144  */
 145 function civicrm_api3_participant_get($params) {
 146   $mode = CRM_Contact_BAO_Query::MODE_EVENT;
 147
 148   list($dao, $query) = _civicrm_api3_get_query_object($params, $mode, 'Participant');
 149
 150   $participant = [];
 151   while ($dao->fetch()) {
 152     $query->convertToPseudoNames($dao, FALSE, TRUE);
 153     $participant[$dao->participant_id] = $query->store($dao);
 154     //@todo - is this required - contribution & pledge use the same query but don't self-retrieve custom data
 155     _civicrm_api3_custom_data_get($participant[$dao->participant_id], CRM_Utils_Array::value('check_permissions', $params), 'Participant', $dao->participant_id, NULL);
 156   }
 157
 158   return civicrm_api3_create_success($participant, $params, 'Participant', 'get', $dao);
 159 }
 160
 161 /**
 162  * Adjust Metadata for Get action.
 163  *
 164  * The metadata is used for setting defaults, documentation & validation.
 165  *
 166  * @param array $params
 167  *   Array of parameters determined by getfields.
 168  */
 169 function _civicrm_api3_participant_get_spec(&$params) {
 170   $params['participant_test'] = [
 171     'api.default' => 0,
 172     'title' => 'Get Test Participants',
 173     'type' => CRM_Utils_Type::T_BOOLEAN,
 174   ];
 175 }
 176
 177 /**
 178  * Deletes an existing contact participant.
 179  *
 180  * This API is used for deleting a contact participant
 181  *
 182  * @param array $params
 183  *   Array containing Id of the contact participant to be deleted.
 184  *
 185  * @throws Exception
 186  * @return array
 187  */
 188 function civicrm_api3_participant_delete($params) {
 189
 190   $result = CRM_Event_BAO_Participant::deleteParticipant($params['id']);
 191
 192   if ($result) {
 193     return civicrm_api3_create_success();
 194   }
 195   else {
 196     throw new Exception('Error while deleting participant');
 197   }
 198 }