api/v2/Participant.php

   1 <?php
   2 // $Id: Participant.php 45502 2013-02-08 13:32:55Z kurund $
   3
   4
   5 /*
   6  +--------------------------------------------------------------------+
   7  | CiviCRM version 4.3                                                |
   8  +--------------------------------------------------------------------+
   9  | Copyright CiviCRM LLC (c) 2004-2013                                |
  10  +--------------------------------------------------------------------+
  11  | This file is a part of CiviCRM.                                    |
  12  |                                                                    |
  13  | CiviCRM is free software; you can copy, modify, and distribute it  |
  14  | under the terms of the GNU Affero General Public License           |
  15  | Version 3, 19 November 2007 and the CiviCRM Licensing Exception.   |
  16  |                                                                    |
  17  | CiviCRM is distributed in the hope that it will be useful, but     |
  18  | WITHOUT ANY WARRANTY; without even the implied warranty of         |
  19  | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.               |
  20  | See the GNU Affero General Public License for more details.        |
  21  |                                                                    |
  22  | You should have received a copy of the GNU Affero General Public   |
  23  | License and the CiviCRM Licensing Exception along                  |
  24  | with this program; if not, contact CiviCRM LLC                     |
  25  | at info[AT]civicrm[DOT]org. If you have questions about the        |
  26  | GNU Affero General Public License or the licensing of CiviCRM,     |
  27  | see the CiviCRM license FAQ at http://civicrm.org/licensing        |
  28  +--------------------------------------------------------------------+
  29 */
  30
  31 /**
  32  * File for the CiviCRM APIv2 participant functions
  33  *
  34  * @package CiviCRM_APIv2
  35  * @subpackage API_Participant
  36  *
  37  * @copyright CiviCRM LLC (c) 2004-2013
  38  * @version $Id: Participant.php 45502 2013-02-08 13:32:55Z kurund $
  39  *
  40  */
  41
  42 /**
  43  * Files required for this package
  44  */
  45 require_once 'api/v2/utils.php';
  46 require_once 'api/v2/ParticipantPayment.php';
  47
  48 /**
  49  * Create an Event Participant
  50  *
  51  * This API is used for creating a participants in an event.
  52  * Required parameters : event_id AND contact_id for new creation
  53  *                     : participant as name/value with participantid for edit
  54  *
  55  * @param   array  $params     an associative array of name/value property values of civicrm_participant
  56  *
  57  * @return array participant id if participant is created/edited otherwise is_error = 1
  58  * @access public
  59  */
  60 function civicrm_participant_create(&$params) {
  61   _civicrm_initialize();
  62
  63   if (!is_array($params)) {
  64     $error = civicrm_create_error('Parameters is not an array');
  65     return $error;
  66   }
  67
  68   if (!isset($params['event_id']) || !isset($params['contact_id'])) {
  69     $error = civicrm_create_error('Required parameter missing');
  70     return $error;
  71   }
  72
  73   if (!isset($params['status_id'])) {
  74     $params['status_id'] = 1;
  75   }
  76
  77   if (!isset($params['register_date'])) {
  78     $params['register_date'] = date('YmdHis');
  79   }
  80   $errors = civicrm_participant_check_params($params);
  81   if (civicrm_error($errors)) {
  82     return $errors;
  83   }
  84
  85   require_once 'CRM/Event/BAO/Participant.php';
  86   $participant = CRM_Event_BAO_Participant::create($params);
  87
  88   if (is_a($participant, 'CRM_Core_Error')) {
  89     return civicrm_create_error("Participant is not created");
  90   }
  91   else {
  92     return civicrm_create_success($participant->id);
  93   }
  94 }
  95
  96 /**
  97  * Retrieve a specific participant, given a set of input params
  98  * If more than one matching participant exists, return an error, unless
  99  * the client has requested to return the first found contact
 100  *
 101  * @param  array   $params           (reference ) input parameters
 102  *
 103  * @return array (reference )        array of properties, if error an array with an error id and error message
 104  * @static void
 105  * @access public
 106  */
 107 function &civicrm_participant_get(&$params) {
 108   _civicrm_initialize();
 109
 110   $values = array();
 111   if (empty($params)) {
 112     $error = civicrm_create_error(ts('No input parameters present'));
 113     return $error;
 114   }
 115
 116   if (!is_array($params)) {
 117     $error = civicrm_create_error(ts('Input parameters is not an array'));
 118     return $error;
 119   }
 120
 121   if (isset($params['id'])) {
 122     $params['participant_id'] = $params['id'];
 123     unset($params['id']);
 124   }
 125
 126   $participant = &civicrm_participant_search($params);
 127
 128
 129   if (count($participant) != 1 &&
 130     !CRM_Utils_Array::value('returnFirst', $params)
 131   ) {
 132     $error = civicrm_create_error(ts('%1 participant matching input params', array(1 => count($participant))),
 133       $participant
 134     );
 135     return $error;
 136   }
 137
 138   if (civicrm_error($participant)) {
 139     return $participant;
 140   }
 141
 142   $participant = array_values($participant);
 143   return $participant[0];
 144 }
 145
 146 /**
 147  * Get contact participant record.
 148  *
 149  * This api is used for finding an existing participant record.
 150  *
 151  * @param  array  $params     an associative array of name/value property values of civicrm_participant
 152  *
 153  * @return  participant property values.
 154  * @access public
 155  */
 156 function &civicrm_participant_search(&$params) {
 157
 158   if (!is_array($params)) {
 159     return civicrm_create_error('Params need to be of type array!');
 160   }
 161
 162   $inputParams      = array();
 163   $returnProperties = array();
 164   $otherVars        = array('sort', 'offset', 'rowCount');
 165
 166   $sort     = NULL;
 167   $offset   = 0;
 168   $rowCount = 25;
 169   foreach ($params as $n => $v) {
 170     if (substr($n, 0, 7) == 'return.') {
 171       $returnProperties[substr($n, 7)] = $v;
 172     }
 173     elseif (in_array($n, $otherVars)) {
 174       $$n = $v;
 175     }
 176     else {
 177       $inputParams[$n] = $v;
 178     }
 179   }
 180
 181   // add is_test to the clause if not present
 182   if (!array_key_exists('participant_test', $inputParams)) {
 183     $inputParams['participant_test'] = 0;
 184   }
 185
 186   require_once 'CRM/Contact/BAO/Query.php';
 187   require_once 'CRM/Event/BAO/Query.php';
 188   if (empty($returnProperties)) {
 189     $returnProperties = CRM_Event_BAO_Query::defaultReturnProperties(CRM_Contact_BAO_Query::MODE_EVENT);
 190   }
 191
 192   $newParams = CRM_Contact_BAO_Query::convertFormValues($params);
 193   $query = new CRM_Contact_BAO_Query($newParams, $returnProperties, NULL);
 194   list($select, $from, $where, $having) = $query->query();
 195
 196   $sql = "$select $from $where $having";
 197
 198   if (!empty($sort)) {
 199     $sql .= " ORDER BY $sort ";
 200   }
 201   $sql .= " LIMIT $offset, $rowCount ";
 202   $dao = CRM_Core_DAO::executeQuery($sql, CRM_Core_DAO::$_nullArray);
 203
 204   $participant = array();
 205   while ($dao->fetch()) {
 206     $participant[$dao->participant_id] = $query->store($dao);
 207   }
 208   $dao->free();
 209
 210   return $participant;
 211 }
 212
 213 /**
 214  * Update an existing contact participant
 215  *
 216  * This api is used for updating an existing contact participant.
 217  * Required parrmeters : id of a participant
 218  *
 219  * @param  Array   $params  an associative array of name/value property values of civicrm_participant
 220  *
 221  * @return array of updated participant property values
 222  * @access public
 223  */
 224 function &civicrm_participant_update(&$params) {
 225   _civicrm_initialize();
 226   if (!is_array($params)) {
 227     return civicrm_create_error('Parameters is not an array');
 228   }
 229
 230   if (!isset($params['id'])) {
 231     $error = civicrm_create_error('Required parameter missing');
 232     return $error;
 233   }
 234   $errors = civicrm_participant_check_params($params);
 235   if (civicrm_error($errors)) {
 236     return $errors;
 237   }
 238   require_once 'CRM/Event/BAO/Participant.php';
 239   $participantBAO = CRM_Event_BAO_Participant::create($params);
 240
 241   $participant = array();
 242   _civicrm_object_to_array($participantBAO, $participant);
 243   return $participant;
 244 }
 245
 246 /**
 247  * Deletes an existing contact participant
 248  *
 249  * This API is used for deleting a contact participant
 250  *
 251  * @param  Int  $participantID   Id of the contact participant to be deleted
 252  *
 253  * @return boolean        true if success, else false
 254  * @access public
 255  */
 256 function &civicrm_participant_delete(&$params) {
 257   _civicrm_initialize();
 258
 259   if (!is_array($params)) {
 260     $error = civicrm_create_error('Params is not an array');
 261     return $error;
 262   }
 263
 264   if (!isset($params['id'])) {
 265     $error = civicrm_create_error('Required parameter missing');
 266     return $error;
 267   }
 268   require_once 'CRM/Event/BAO/Participant.php';
 269   $participant = new CRM_Event_BAO_Participant();
 270   $result = $participant->deleteParticipant($params['id']);
 271
 272   if ($result) {
 273     $values = civicrm_create_success();
 274   }
 275   else {
 276     $values = civicrm_create_error('Error while deleting participant');
 277   }
 278   return $values;
 279 }
 280
 281 /**
 282  *
 283  * @param <type> $params
 284  * @param <type> $onDuplicate
 285  *
 286  * @return <type>
 287  */
 288 function civicrm_create_participant_formatted(&$params, $onDuplicate) {
 289   _civicrm_initialize();
 290
 291   // return error if we have no params
 292   if (empty($params)) {
 293     return civicrm_create_error('Input Parameters empty');
 294   }
 295
 296   require_once 'CRM/Event/Import/Parser.php';
 297   if ($onDuplicate != CRM_Event_Import_Parser::DUPLICATE_NOCHECK) {
 298     CRM_Core_Error::reset();
 299     $error = civicrm_participant_check_params($params, TRUE);
 300     if (civicrm_error($error)) {
 301       return $error;
 302     }
 303   }
 304
 305   return civicrm_participant_create($params);
 306 }
 307
 308 /**
 309  *
 310  * @param <type> $params
 311  *
 312  * @return <type>
 313  */
 314 function civicrm_participant_check_params(&$params, $checkDuplicate = FALSE) {
 315   require_once 'CRM/Event/BAO/Participant.php';
 316   //check if participant id is valid or not
 317   if (CRM_Utils_Array::value('id', $params)) {
 318     $participant = new CRM_Event_BAO_Participant();
 319     $participant->id = $params['id'];
 320     if (!$participant->find(TRUE)) {
 321       return civicrm_create_error(ts('Participant  id is not valid'));
 322     }
 323   }
 324   require_once 'CRM/Contact/BAO/Contact.php';
 325   //check if contact id is valid or not
 326   if (CRM_Utils_Array::value('contact_id', $params)) {
 327     $contact = new CRM_Contact_BAO_Contact();
 328     $contact->id = $params['contact_id'];
 329     if (!$contact->find(TRUE)) {
 330       return civicrm_create_error(ts('Contact id is not valid'));
 331     }
 332   }
 333
 334   //check that event id is not an template
 335   if (CRM_Utils_Array::value('event_id', $params)) {
 336     $isTemplate = CRM_Core_DAO::getFieldValue('CRM_Event_DAO_Event', $params['event_id'], 'is_template');
 337     if (!empty($isTemplate)) {
 338       return civicrm_create_error(ts('Event templates are not meant to be registered'));
 339     }
 340   }
 341
 342   $result = array();
 343   if ($checkDuplicate) {
 344     if (CRM_Event_BAO_Participant::checkDuplicate($params, $result)) {
 345       $participantID = array_pop($result);
 346
 347       $error = CRM_Core_Error::createError("Found matching participant record.",
 348         CRM_Core_Error::DUPLICATE_PARTICIPANT,
 349         'Fatal', $participantID
 350       );
 351
 352       return civicrm_create_error($error->pop(),
 353         array(
 354           'contactID' => $params['contact_id'],
 355           'participantID' => $participantID,
 356         )
 357       );
 358     }
 359   }
 360   return TRUE;
 361 }
 362