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