api/v3/MailingContact.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | CiviCRM version 4.3                                                |
   5  +--------------------------------------------------------------------+
   6  | Copyright CiviCRM LLC (c) 2004-2013                                |
   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-2013
  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/Page/Tab.php
  51  *
  52  */
  53 function civicrm_api3_mailing_contact_get($params) {
  54   if (empty($params['contact_id'])) {
  55     return civicrm_api3_create_error('contact_id is a required field');
  56   }
  57
  58   if (empty($params['type'])) {
  59     $params['type'] = 'Delivered';
  60   }
  61
  62   $validTypeValues = array('Delivered', 'Bounced');
  63   if (!in_array($params['type'], $validTypeValues)) {
  64     return civicrm_api3_create_error(
  65       'type should be one of the following: ' .
  66       implode(', ', $validTypeValues)
  67     );
  68   }
  69
  70   if (!isset($params['offset'])) {
  71     $params['offset'] = 0;
  72   }
  73
  74
  75   if (!isset($params['limit'])) {
  76     $params['limit'] = 50;
  77   }
  78
  79   $fnName = '_civicrm_api3_mailing_contact_get_' . strtolower($params['type']);
  80   return $fnName(
  81     $params['contact_id'],
  82     $params['offset'],
  83     $params['limit']
  84   );
  85 }
  86
  87 function _civicrm_api3_mailing_contact_query(
  88   $type,
  89   $contactID,
  90   $offset,
  91   $limit,
  92   $selectFields,
  93   $fromClause,
  94   $whereClause
  95 ) {
  96   $defaultFields = array(
  97     'm.id'       => 'mailing_id',
  98     'm.subject'  => 'subject',
  99     'c.id' => 'creator_id',
 100     'c.sort_name' => 'creator_name',
 101   );
 102
 103   if ($selectFields) {
 104     $fields = array_merge($selectFields, $defaultFields);
 105   }
 106   else {
 107     $fields = $defaultFields;
 108   }
 109
 110   $select = array();
 111   foreach ($fields as $n => $l) {
 112     $select[] = "$n as $l";
 113   }
 114   $select = implode(', ', $select);
 115
 116   $sql = "
 117 SELECT     $select
 118 FROM       civicrm_mailing m
 119 INNER JOIN civicrm_contact c ON m.created_id = c.id
 120 INNER JOIN civicrm_mailing_job j ON j.mailing_id = m.id
 121 INNER JOIN civicrm_mailing_event_queue meq ON meq.job_id = j.id
 122            $fromClause
 123 WHERE      j.is_test = 0
 124 AND        meq.contact_id = %1
 125            $whereClause
 126 GROUP BY   m.id
 127 ORDER BY   j.start_date
 128 ";
 129
 130   if ($limit > 0) {
 131     $sql .= "
 132 LIMIT %2, %3
 133 ";
 134   }
 135
 136   $qParams = array(
 137     1 => array($contactID, 'Integer'),
 138     2 => array($offset, 'Integer'),
 139     3 => array($limit, 'Integer')
 140   );
 141   $dao = CRM_Core_DAO::executeQuery($sql, $qParams);
 142
 143   $results = array();
 144   while ($dao->fetch()) {
 145     foreach ($fields as $n => $l) {
 146       $results[$dao->mailing_id][$l] = $dao->$l;
 147     }
 148   }
 149
 150   $params = array(
 151     'type'   => $type,
 152     'contact_id' => $contactID,
 153     'offset' => $offset,
 154     'limit'  => $limit
 155   );
 156   return civicrm_api3_create_success($results, $params);
 157 }
 158
 159 function _civicrm_api3_mailing_contact_get_delivered(
 160   $contactID,
 161   $offset,
 162   $limit
 163 ) {
 164   $selectFields = array('med.time_stamp' => 'start_date');
 165
 166   $fromClause = "
 167 INNER JOIN civicrm_mailing_event_delivered med ON med.event_queue_id = meq.id
 168 LEFT  JOIN civicrm_mailing_event_bounce meb ON meb.event_queue_id = meq.id
 169 ";
 170
 171   $whereClause = "
 172 AND        meb.id IS NULL
 173 ";
 174
 175   return _civicrm_api3_mailing_contact_query(
 176     'Delivered',
 177     $contactID,
 178     $offset,
 179     $limit,
 180     $selectFields,
 181     $fromClause,
 182     $whereClause
 183   );
 184 }
 185
 186 function _civicrm_api3_mailing_contact_get_bounced(
 187   $contactID,
 188   $offset,
 189   $limit
 190 ) {
 191   $fromClause = "
 192 INNER JOIN civicrm_mailing_event_bounce meb ON meb.event_queue_id = meq.id
 193 ";
 194
 195   return _civicrm_api3_mailing_contact_query(
 196     'Bounced',
 197     $contactID,
 198     $offset,
 199     $limit,
 200     NULL,
 201     $fromClause,
 202     NULL
 203   );
 204 }