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  * File for the CiviCRM APIv3 contact and mailing functions
  30  *
  31  * @package CiviCRM_APIv3
  32  * @subpackage API_MailingContact
  33  *
  34  * @copyright CiviCRM LLC (c) 2004-2014
  35  * @version $Id$
  36  *
  37  */
  38
  39 /**
  40  * Get all the mailings and details that a contact was involved with
  41  *
  42  * @param array $params
  43  *   Input parameters - see _spec for details (returned by getfields)
  44  *
  45  * @return array
  46  *   API result
  47  * @access public
  48  *
  49  */
  50 function civicrm_api3_mailing_contact_get($params) {
  51   return civicrm_api3_create_success(_civicrm_api3_mailing_contact_getresults($params, FALSE));
  52 }
  53 /**
  54  * This is a wrapper for the functions that return the results from the 'quasi-entity'
  55  * mailing contact
  56  * @param array $params
  57  * @param bool $count
  58  * @throws Exception
  59  */
  60 function _civicrm_api3_mailing_contact_getresults($params, $count) {
  61   if (empty($params['type'])) {
  62     //ie. because the api is an anomaly & passing in id is not valid
  63     throw new Exception('This api call does not accept api as a parameter');
  64   }
  65   $options  = _civicrm_api3_get_options_from_params($params, TRUE,'contribution','get');
  66   $fnName = '_civicrm_api3_mailing_contact_get_' . strtolower($params['type']);
  67   return $fnName(
  68       $params['contact_id'],
  69       $options['offset'],
  70       $options['limit'],
  71       $options['sort'],
  72       $count
  73   );
  74 }
  75 /**
  76  * Adjust Metadata for Get action
  77  *
  78  * @param array $params
  79  *   Array or parameters determined by getfields.
  80  */
  81 function _civicrm_api3_mailing_contact_get_spec(&$params) {
  82   $params['contact_id']['api.required'] = 1;
  83   $params['contact_id']['title'] = 'Contact ID';
  84   $params['type'] = array(
  85     'api.default' => 'Delivered',
  86     'title' => 'Type',// doesn't really explain the field - but not sure I understand it to explain it better
  87     'type' => CRM_Utils_Type::T_STRING,
  88     'options' => array(
  89       'Delivered' => 'Delivered',
  90       'Bounced' => 'Bounced',
  91     ),
  92   );
  93 }
  94
  95 /**
  96  * @param int $contactID
  97  * @param $offset
  98  * @param $limit
  99  * @param $selectFields
 100  * @param $fromClause
 101  * @param $whereClause
 102  * @param $sort
 103  * @param $getCount
 104  *
 105  * @return array
 106  */
 107 function _civicrm_api3_mailing_contact_query(
 108   $contactID,
 109   $offset,
 110   $limit,
 111   $selectFields,
 112   $fromClause,
 113   $whereClause,
 114   $sort,
 115   $getCount
 116 ) {
 117
 118   if ($getCount) {
 119     $sql = "
 120 SELECT     count(*)
 121 FROM       civicrm_mailing m
 122 INNER JOIN civicrm_contact c ON m.created_id = c.id
 123 INNER JOIN civicrm_mailing_job j ON j.mailing_id = m.id
 124 INNER JOIN civicrm_mailing_event_queue meq ON meq.job_id = j.id
 125            $fromClause
 126 WHERE      j.is_test = 0
 127 AND        meq.contact_id = %1
 128            $whereClause
 129 GROUP BY   m.id
 130 ";
 131
 132     $qParams = array(
 133       1 => array($contactID, 'Integer'),
 134     );
 135     $dao = CRM_Core_DAO::executeQuery($sql, $qParams);
 136
 137     $results = $dao->N;
 138   }
 139   else {
 140     $defaultFields = array(
 141       'm.id'       => 'mailing_id',
 142       'm.subject'  => 'subject',
 143       'c.id' => 'creator_id',
 144       'c.sort_name' => 'creator_name',
 145     );
 146
 147     if ($selectFields) {
 148       $fields = array_merge($selectFields, $defaultFields);
 149     }
 150     else {
 151       $fields = $defaultFields;
 152     }
 153
 154     $select = array();
 155     foreach ($fields as $n => $l) {
 156       $select[] = "$n as $l";
 157     }
 158     $select = implode(', ', $select);
 159
 160     $orderBy = 'ORDER BY j.start_date DESC';
 161     if ($sort) {
 162       $orderBy = "ORDER BY $sort";
 163     }
 164
 165     $sql = "
 166 SELECT     $select
 167 FROM       civicrm_mailing m
 168 INNER JOIN civicrm_contact c ON m.created_id = c.id
 169 INNER JOIN civicrm_mailing_job j ON j.mailing_id = m.id
 170 INNER JOIN civicrm_mailing_event_queue meq ON meq.job_id = j.id
 171            $fromClause
 172 WHERE      j.is_test = 0
 173 AND        meq.contact_id = %1
 174            $whereClause
 175 GROUP BY   m.id
 176 {$orderBy}
 177 ";
 178
 179     if ($limit > 0) {
 180       $sql .= "
 181 LIMIT %2, %3
 182 ";
 183     }
 184
 185     $qParams = array(
 186       1 => array($contactID, 'Integer'),
 187       2 => array($offset, 'Integer'),
 188       3 => array($limit, 'Integer'),
 189     );
 190     $dao = CRM_Core_DAO::executeQuery($sql, $qParams);
 191
 192     $results = array();
 193     while ($dao->fetch()) {
 194       foreach ($fields as $n => $l) {
 195         $results[$dao->mailing_id][$l] = $dao->$l;
 196       }
 197     }
 198   }
 199
 200   return $results;
 201 }
 202
 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  * @param int $contactID
 244  * @param $offset
 245  * @param $limit
 246  * @param $sort
 247  * @param $getCount
 248  *
 249  * @return array
 250  */
 251 function _civicrm_api3_mailing_contact_get_bounced(
 252   $contactID,
 253   $offset,
 254   $limit,
 255   $sort,
 256   $getCount
 257 ) {
 258   $fromClause = "
 259 INNER JOIN civicrm_mailing_event_bounce meb ON meb.event_queue_id = meq.id
 260 ";
 261
 262   return _civicrm_api3_mailing_contact_query(
 263     $contactID,
 264     $offset,
 265     $limit,
 266     NULL,
 267     $fromClause,
 268     NULL,
 269     $sort,
 270     $getCount
 271   );
 272 }
 273
 274 /**
 275  * Get count of all the mailings that a contact was involved with
 276  *
 277  * @param array $params
 278  *   Input parameters per getfields
 279  *
 280  * @return array
 281  *   API result
 282  * @access public
 283  * @example CRM/Mailing/BAO/Mailing.php
 284  *
 285  */
 286 function civicrm_api3_mailing_contact_getcount($params) {
 287   return _civicrm_api3_mailing_contact_getresults($params, TRUE);
 288 }