api/v3/MailingContact.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 contact and mailing.
  14  *
  15  * @package CiviCRM_APIv3
  16  */
  17
  18 /**
  19  * Get all the mailings and details that a contact was involved with.
  20  *
  21  * @param array $params
  22  *   Input parameters - see _spec for details (returned by getfields)
  23  *
  24  * @return array
  25  *   API result
  26  */
  27 function civicrm_api3_mailing_contact_get($params) {
  28   return civicrm_api3_create_success(_civicrm_api3_mailing_contact_getresults($params, FALSE));
  29 }
  30
  31 /**
  32  * This is a wrapper for the functions that return the results from the 'quasi-entity' mailing contact.
  33  *
  34  * @param array $params
  35  * @param bool $count
  36  *
  37  * @throws Exception
  38  */
  39 function _civicrm_api3_mailing_contact_getresults($params, $count) {
  40   if (empty($params['type'])) {
  41     //ie. because the api is an anomaly & passing in id is not valid
  42     throw new Exception('This api call does not accept api as a parameter');
  43   }
  44   $options  = _civicrm_api3_get_options_from_params($params, TRUE, 'contribution', 'get');
  45   $fnName = '_civicrm_api3_mailing_contact_get_' . strtolower($params['type']);
  46   if (!function_exists($fnName)) {
  47     throw new API_Exception('Invalid mailing type: ' . $params['type']);
  48   }
  49   return $fnName(
  50       $params['contact_id'],
  51       $options['offset'],
  52       $options['limit'],
  53       $options['sort'],
  54       $count
  55   );
  56 }
  57
  58 /**
  59  * Adjust Metadata for Get action.
  60  *
  61  * @param array $params
  62  *   Array of parameters determined by getfields.
  63  */
  64 function _civicrm_api3_mailing_contact_get_spec(&$params) {
  65   $params['contact_id'] = [
  66     'api.required' => 1,
  67     'title' => 'Contact ID',
  68     'type' => CRM_Utils_Type::T_INT,
  69   ];
  70
  71   $params['type'] = [
  72     'api.default' => 'Delivered',
  73     // doesn't really explain the field - but not sure I understand it to explain it better
  74     'title' => 'Type',
  75     'type' => CRM_Utils_Type::T_STRING,
  76     'options' => [
  77       'Delivered' => 'Delivered',
  78       'Bounced' => 'Bounced',
  79     ],
  80   ];
  81 }
  82
  83 /**
  84  * Helper function for mailing contact queries.
  85  *
  86  * @param int $contactID
  87  * @param int $offset
  88  * @param int $limit
  89  * @param array|null $selectFields
  90  * @param string|null $fromClause
  91  * @param string|null $whereClause
  92  * @param string|null $sort
  93  * @param bool $getCount
  94  *
  95  * @return array
  96  */
  97 function _civicrm_api3_mailing_contact_query(
  98   $contactID,
  99   $offset,
 100   $limit,
 101   $selectFields,
 102   $fromClause,
 103   $whereClause,
 104   $sort,
 105   $getCount
 106 ) {
 107
 108   if ($getCount) {
 109     $sql = "
 110 SELECT     count(*)
 111 FROM       civicrm_mailing m
 112 INNER JOIN civicrm_contact c ON m.created_id = c.id
 113 INNER JOIN civicrm_mailing_job j ON j.mailing_id = m.id
 114 INNER JOIN civicrm_mailing_event_queue meq ON meq.job_id = j.id
 115            $fromClause
 116 WHERE      j.is_test = 0
 117 AND        meq.contact_id = %1
 118            $whereClause
 119 GROUP BY   m.id
 120 ";
 121
 122     $qParams = [
 123       1 => [$contactID, 'Integer'],
 124     ];
 125     $dao = CRM_Core_DAO::executeQuery($sql, $qParams);
 126
 127     $results = $dao->N;
 128   }
 129   else {
 130     $defaultFields = [
 131       'm.id'       => 'mailing_id',
 132       'm.subject'  => 'subject',
 133       'c.id' => 'creator_id',
 134       'c.sort_name' => 'creator_name',
 135     ];
 136
 137     if ($selectFields) {
 138       $fields = array_merge($selectFields, $defaultFields);
 139     }
 140     else {
 141       $fields = $defaultFields;
 142     }
 143
 144     $select = [];
 145     foreach ($fields as $n => $l) {
 146       $select[] = "$n as $l";
 147     }
 148     $select = implode(', ', $select);
 149
 150     $orderBy = 'ORDER BY MIN(j.start_date) DESC';
 151     if ($sort) {
 152       $orderBy = "ORDER BY $sort";
 153     }
 154
 155     $groupBy = CRM_Contact_BAO_Query::getGroupByFromSelectColumns(array_keys($fields), "m.id");
 156
 157     $sql = "
 158 SELECT     $select
 159 FROM       civicrm_mailing m
 160 INNER JOIN civicrm_contact c ON m.created_id = c.id
 161 INNER JOIN civicrm_mailing_job j ON j.mailing_id = m.id
 162 INNER JOIN civicrm_mailing_event_queue meq ON meq.job_id = j.id
 163            $fromClause
 164 WHERE      j.is_test = 0
 165 AND        meq.contact_id = %1
 166            $whereClause
 167 {$groupBy}
 168 {$orderBy}
 169 ";
 170
 171     if ($limit > 0) {
 172       $sql .= "
 173 LIMIT %2, %3
 174 ";
 175     }
 176
 177     $qParams = [
 178       1 => [$contactID, 'Integer'],
 179       2 => [$offset, 'Integer'],
 180       3 => [$limit, 'Integer'],
 181     ];
 182     $dao = CRM_Core_DAO::executeQuery($sql, $qParams);
 183
 184     $results = [];
 185     while ($dao->fetch()) {
 186       foreach ($fields as $n => $l) {
 187         $results[$dao->mailing_id][$l] = $dao->$l;
 188       }
 189     }
 190   }
 191
 192   return $results;
 193 }
 194
 195 /**
 196  * Get delivered mailing contacts.
 197  *
 198  * @param int $contactID
 199  * @param int $offset
 200  * @param int $limit
 201  * @param string|null $sort
 202  * @param bool $getCount
 203  *
 204  * @return array
 205  */
 206 function _civicrm_api3_mailing_contact_get_delivered(
 207   $contactID,
 208   $offset,
 209   $limit,
 210   $sort,
 211   $getCount
 212 ) {
 213   $selectFields = ['med.time_stamp' => 'start_date'];
 214
 215   $fromClause = "
 216 INNER JOIN civicrm_mailing_event_delivered med ON med.event_queue_id = meq.id
 217 LEFT  JOIN civicrm_mailing_event_bounce meb ON meb.event_queue_id = meq.id
 218 ";
 219
 220   $whereClause = "
 221 AND        meb.id IS NULL
 222 ";
 223
 224   return _civicrm_api3_mailing_contact_query(
 225     $contactID,
 226     $offset,
 227     $limit,
 228     $selectFields,
 229     $fromClause,
 230     $whereClause,
 231     $sort,
 232     $getCount
 233   );
 234 }
 235
 236 /**
 237  * Get bounced mailing contact records.
 238  *
 239  * @param int $contactID
 240  * @param int $offset
 241  * @param int $limit
 242  * @param string|null $sort
 243  * @param bool $getCount
 244  *
 245  * @return array
 246  */
 247 function _civicrm_api3_mailing_contact_get_bounced(
 248   $contactID,
 249   $offset,
 250   $limit,
 251   $sort,
 252   $getCount
 253 ) {
 254   $fromClause = "
 255 INNER JOIN civicrm_mailing_event_bounce meb ON meb.event_queue_id = meq.id
 256 ";
 257
 258   return _civicrm_api3_mailing_contact_query(
 259     $contactID,
 260     $offset,
 261     $limit,
 262     NULL,
 263     $fromClause,
 264     NULL,
 265     $sort,
 266     $getCount
 267   );
 268 }
 269
 270 /**
 271  * Get count of all the mailings that a contact was involved with.
 272  *
 273  * @param array $params
 274  *   Input parameters per getfields
 275  *
 276  * @return array
 277  *   API result
 278  */
 279 function civicrm_api3_mailing_contact_getcount($params) {
 280   return _civicrm_api3_mailing_contact_getresults($params, TRUE);
 281 }