api/v3/MailingContact.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | CiviCRM version 4.5                                                |
   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 input parameters
  43  *                    - key: contact_id, value: int - required
  44  *                    - key: type, value: Delivered | Bounced - optional, defaults to Delivered
  45  *                    - Future extensions will include: Opened, Clicked, Forwarded
  46  *
  47  * @return array API result
  48  * @static void
  49  * @access public
  50  * @example CRM/Mailing/BAO/Mailing.php
  51  *
  52  */
  53 function civicrm_api3_mailing_contact_get($params) {
  54   return civicrm_api3_create_success(_civicrm_api3_mailing_contact_getresults($params, FALSE));
  55 }
  56 /**
  57  * This is a wrapper for the functions that return the results from the 'quasi-entity'
  58  * mailing contact
  59  * @param array $params
  60  * @param Boolean $count
  61  * @throws Exception
  62  */
  63 function _civicrm_api3_mailing_contact_getresults($params, $count){
  64   if(empty($params['type'])){
  65     //ie. because the api is an anomoly & passing in id is not valid
  66     throw new Exception('This api call does not accept api as a parameter');
  67   }
  68   $options  = _civicrm_api3_get_options_from_params($params, TRUE,'contribution','get');
  69   $fnName = '_civicrm_api3_mailing_contact_get_' . strtolower($params['type']);
  70   return $fnName(
  71       $params['contact_id'],
  72       $options['offset'],
  73       $options['limit'],
  74       $options['sort'],
  75       $count
  76   );
  77 }
  78 /**
  79  * Adjust Metadata for Get action
  80  *
  81  * @param array $params array or parameters determined by getfields
  82  */
  83 function _civicrm_api3_mailing_contact_get_spec(&$params) {
  84   $params['contact_id']['api.required'] = 1;
  85   $params['type'] = array(
  86     'api.default' => 'Delivered',
  87     'type' => CRM_Utils_Type::T_STRING,
  88     'options' => array(
  89       'Delivered' => 'Delivered',
  90       'Bounced' => 'Bounced',
  91     )
  92   );
  93 }
  94
  95 function _civicrm_api3_mailing_contact_query(
  96   $type,
  97   $contactID,
  98   $offset,
  99   $limit,
 100   $selectFields,
 101   $fromClause,
 102   $whereClause,
 103   $sort,
 104   $getCount
 105 ) {
 106
 107   if ($getCount) {
 108     $sql = "
 109 SELECT     count(*)
 110 FROM       civicrm_mailing m
 111 INNER JOIN civicrm_contact c ON m.created_id = c.id
 112 INNER JOIN civicrm_mailing_job j ON j.mailing_id = m.id
 113 INNER JOIN civicrm_mailing_event_queue meq ON meq.job_id = j.id
 114            $fromClause
 115 WHERE      j.is_test = 0
 116 AND        meq.contact_id = %1
 117            $whereClause
 118 GROUP BY   m.id
 119 ";
 120
 121     $qParams = array(
 122       1 => array($contactID, 'Integer')
 123     );
 124     $dao = CRM_Core_DAO::executeQuery($sql, $qParams);
 125
 126     $params = array(
 127       'type'   => $type,
 128       'contact_id' => $contactID
 129     );
 130
 131     $results = $dao->N;
 132   }
 133   else {
 134     $defaultFields = array(
 135       'm.id'       => 'mailing_id',
 136       'm.subject'  => 'subject',
 137       'c.id' => 'creator_id',
 138       'c.sort_name' => 'creator_name',
 139     );
 140
 141     if ($selectFields) {
 142       $fields = array_merge($selectFields, $defaultFields);
 143     }
 144     else {
 145       $fields = $defaultFields;
 146     }
 147
 148     $select = array();
 149     foreach ($fields as $n => $l) {
 150       $select[] = "$n as $l";
 151     }
 152     $select = implode(', ', $select);
 153
 154     $orderBy = 'ORDER BY j.start_date DESC';
 155     if ($sort) {
 156       $orderBy = "ORDER BY $sort";
 157     }
 158
 159     $sql = "
 160 SELECT     $select
 161 FROM       civicrm_mailing m
 162 INNER JOIN civicrm_contact c ON m.created_id = c.id
 163 INNER JOIN civicrm_mailing_job j ON j.mailing_id = m.id
 164 INNER JOIN civicrm_mailing_event_queue meq ON meq.job_id = j.id
 165            $fromClause
 166 WHERE      j.is_test = 0
 167 AND        meq.contact_id = %1
 168            $whereClause
 169 GROUP BY   m.id
 170 {$orderBy}
 171 ";
 172
 173     if ($limit > 0) {
 174       $sql .= "
 175 LIMIT %2, %3
 176 ";
 177     }
 178
 179     $qParams = array(
 180       1 => array($contactID, 'Integer'),
 181       2 => array($offset, 'Integer'),
 182       3 => array($limit, 'Integer')
 183     );
 184     $dao = CRM_Core_DAO::executeQuery($sql, $qParams);
 185
 186     $results = array();
 187     while ($dao->fetch()) {
 188       foreach ($fields as $n => $l) {
 189         $results[$dao->mailing_id][$l] = $dao->$l;
 190       }
 191     }
 192   }
 193
 194   return $results;
 195 }
 196
 197 function _civicrm_api3_mailing_contact_get_delivered(
 198   $contactID,
 199   $offset,
 200   $limit,
 201   $sort,
 202   $getCount
 203 ) {
 204   $selectFields = array('med.time_stamp' => 'start_date');
 205
 206   $fromClause = "
 207 INNER JOIN civicrm_mailing_event_delivered med ON med.event_queue_id = meq.id
 208 LEFT  JOIN civicrm_mailing_event_bounce meb ON meb.event_queue_id = meq.id
 209 ";
 210
 211   $whereClause = "
 212 AND        meb.id IS NULL
 213 ";
 214
 215   return _civicrm_api3_mailing_contact_query(
 216     'Delivered',
 217     $contactID,
 218     $offset,
 219     $limit,
 220     $selectFields,
 221     $fromClause,
 222     $whereClause,
 223     $sort,
 224     $getCount
 225   );
 226 }
 227
 228 function _civicrm_api3_mailing_contact_get_bounced(
 229   $contactID,
 230   $offset,
 231   $limit,
 232   $sort,
 233   $getCount
 234 ) {
 235   $fromClause = "
 236 INNER JOIN civicrm_mailing_event_bounce meb ON meb.event_queue_id = meq.id
 237 ";
 238
 239   return _civicrm_api3_mailing_contact_query(
 240     'Bounced',
 241     $contactID,
 242     $offset,
 243     $limit,
 244     NULL,
 245     $fromClause,
 246     NULL,
 247     $sort,
 248     $getCount
 249   );
 250 }
 251
 252 /**
 253  * Get count of all the mailings that a contact was involved with
 254  *
 255  * @param array    $params input parameters
 256  *                    - key: contact_id, value: int - required
 257  *                    - key: type, value: Delivered | Bounced - optional, defaults to Delivered
 258  *                    - Future extensions will include: Opened, Clicked, Forwarded
 259  *
 260  * @return array API result
 261  * @static void
 262  * @access public
 263  * @example CRM/Mailing/BAO/Mailing.php
 264  *
 265  */
 266 function civicrm_api3_mailing_contact_getcount($params) {
 267   return _civicrm_api3_mailing_contact_getresults($params, TRUE);
 268 }