api/v3/MailingContact.php

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