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  */
  48 function civicrm_api3_mailing_contact_get($params) {
  49   return civicrm_api3_create_success(_civicrm_api3_mailing_contact_getresults($params, FALSE));
  50 }
  51 /**
  52  * This is a wrapper for the functions that return the results from the 'quasi-entity'
  53  * mailing contact
  54  * @param array $params
  55  * @param bool $count
  56  * @throws Exception
  57  */
  58 function _civicrm_api3_mailing_contact_getresults($params, $count) {
  59   if (empty($params['type'])) {
  60     //ie. because the api is an anomaly & passing in id is not valid
  61     throw new Exception('This api call does not accept api as a parameter');
  62   }
  63   $options  = _civicrm_api3_get_options_from_params($params, TRUE,'contribution','get');
  64   $fnName = '_civicrm_api3_mailing_contact_get_' . strtolower($params['type']);
  65   return $fnName(
  66       $params['contact_id'],
  67       $options['offset'],
  68       $options['limit'],
  69       $options['sort'],
  70       $count
  71   );
  72 }
  73 /**
  74  * Adjust Metadata for Get action
  75  *
  76  * @param array $params
  77  *   Array or parameters determined by getfields.
  78  */
  79 function _civicrm_api3_mailing_contact_get_spec(&$params) {
  80   $params['contact_id']['api.required'] = 1;
  81   $params['contact_id']['title'] = 'Contact ID';
  82   $params['type'] = array(
  83     'api.default' => 'Delivered',
  84     'title' => 'Type',// doesn't really explain the field - but not sure I understand it to explain it better
  85     'type' => CRM_Utils_Type::T_STRING,
  86     'options' => array(
  87       'Delivered' => 'Delivered',
  88       'Bounced' => 'Bounced',
  89     ),
  90   );
  91 }
  92
  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  * @param int $contactID
 203  * @param $offset
 204  * @param $limit
 205  * @param $sort
 206  * @param $getCount
 207  *
 208  * @return array
 209  */
 210 function _civicrm_api3_mailing_contact_get_delivered(
 211   $contactID,
 212   $offset,
 213   $limit,
 214   $sort,
 215   $getCount
 216 ) {
 217   $selectFields = array('med.time_stamp' => 'start_date');
 218
 219   $fromClause = "
 220 INNER JOIN civicrm_mailing_event_delivered med ON med.event_queue_id = meq.id
 221 LEFT  JOIN civicrm_mailing_event_bounce meb ON meb.event_queue_id = meq.id
 222 ";
 223
 224   $whereClause = "
 225 AND        meb.id IS NULL
 226 ";
 227
 228   return _civicrm_api3_mailing_contact_query(
 229     $contactID,
 230     $offset,
 231     $limit,
 232     $selectFields,
 233     $fromClause,
 234     $whereClause,
 235     $sort,
 236     $getCount
 237   );
 238 }
 239
 240 /**
 241  * @param int $contactID
 242  * @param $offset
 243  * @param $limit
 244  * @param $sort
 245  * @param $getCount
 246  *
 247  * @return array
 248  */
 249 function _civicrm_api3_mailing_contact_get_bounced(
 250   $contactID,
 251   $offset,
 252   $limit,
 253   $sort,
 254   $getCount
 255 ) {
 256   $fromClause = "
 257 INNER JOIN civicrm_mailing_event_bounce meb ON meb.event_queue_id = meq.id
 258 ";
 259
 260   return _civicrm_api3_mailing_contact_query(
 261     $contactID,
 262     $offset,
 263     $limit,
 264     NULL,
 265     $fromClause,
 266     NULL,
 267     $sort,
 268     $getCount
 269   );
 270 }
 271
 272 /**
 273  * Get count of all the mailings that a contact was involved with
 274  *
 275  * @param array $params
 276  *   Input parameters per getfields
 277  *
 278  * @return array
 279  *   API result
 280  */
 281 function civicrm_api3_mailing_contact_getcount($params) {
 282   return _civicrm_api3_mailing_contact_getresults($params, TRUE);
 283 }