CRM/Mailing/Selector/Event.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  *
  30  * @package CRM
  31  * @copyright CiviCRM LLC (c) 2004-2014
  32  * $Id$
  33  *
  34  */
  35
  36 /**
  37  * This class is used to retrieve and display a range of
  38  * contacts that match the given criteria (specifically for
  39  * results of advanced search options.
  40  *
  41  */
  42 class CRM_Mailing_Selector_Event extends CRM_Core_Selector_Base implements CRM_Core_Selector_API {
  43
  44   /**
  45    * array of supported links, currenly null
  46    *
  47    * @var array
  48    * @static
  49    */
  50   static $_links = NULL;
  51
  52   /**
  53    * what event type are we browsing?
  54    */
  55   private $_event;
  56
  57   /**
  58    * should we only count distinct contacts?
  59    */
  60   private $_is_distinct;
  61
  62   /**
  63    * which mailing are we browsing events from?
  64    */
  65   private $_mailing_id;
  66
  67   /**
  68    * do we want events tied to a specific job?
  69    */
  70   private $_job_id;
  71
  72   /**
  73    * for click-through events, do we only want those from a specific url?
  74    */
  75   private $_url_id;
  76
  77   /**
  78    * we use desc to remind us what that column is, name is used in the tpl
  79    *
  80    * @var array
  81    */
  82   public $_columnHeaders;
  83
  84   /**
  85    * Class constructor
  86    *
  87    * @param string $event The event type (queue/delivered/open...)
  88    * @param boolean $distinct Count only distinct contact events?
  89    * @param int $mailing ID of the mailing to query
  90    * @param int $job ID of the job to query.  If null, all jobs from $mailing are queried.
  91    * @param int $url If the event type is a click-through, do we want only those from a specific url?
  92    *
  93    * @return \CRM_Mailing_Selector_Event
  94   @access public
  95    */
  96   function __construct($event, $distinct, $mailing, $job = NULL, $url = NULL) {
  97     $this->_event_type  = $event;
  98     $this->_is_distinct = $distinct;
  99     $this->_mailing_id  = $mailing;
 100     $this->_job_id      = $job;
 101     $this->_url_id      = $url;
 102   }
 103   //end of constructor
 104
 105   /**
 106    * This method returns the links that are given for each search row.
 107    *
 108    * @return array
 109    * @access public
 110    * @static
 111    */
 112   static function &links() {
 113     return self::$_links;
 114   }
 115   //end of function
 116
 117   /**
 118    * getter for array of the parameters required for creating pager.
 119    *
 120    * @param $action
 121    * @param $params
 122    *
 123    * @internal param $
 124    * @access public
 125    */
 126   function getPagerParams($action, &$params) {
 127     $params['csvString'] = NULL;
 128     $params['rowCount']  = CRM_Utils_Pager::ROWCOUNT;
 129     $params['status']    = ts('%1 %%StatusMessage%%', array(1 => $this->eventToTitle()));
 130     $params['buttonTop'] = 'PagerTopButton';
 131     $params['buttonBottom'] = 'PagerBottomButton';
 132   }
 133   //end of function
 134
 135   /**
 136    * returns the column headers as an array of tuples:
 137    * (name, sortName (key to the sort array))
 138    *
 139    * @param string $action the action being performed
 140    * @param enum   $output what should the result set include (web/email/csv)
 141    *
 142    * @return array the column headers that need to be displayed
 143    * @access public
 144    */
 145   function &getColumnHeaders($action = NULL, $output = NULL) {
 146     $mailing = CRM_Mailing_BAO_Mailing::getTableName();
 147
 148     $contact = CRM_Contact_BAO_Contact::getTableName();
 149
 150     $email = CRM_Core_BAO_Email::getTableName();
 151
 152     $job = CRM_Mailing_BAO_MailingJob::getTableName();
 153     if (!isset($this->_columnHeaders)) {
 154
 155       $this->_columnHeaders = array(
 156         array(
 157           'name' => ts('Contact'),
 158           'sort' => $contact . '.sort_name',
 159           'direction' => CRM_Utils_Sort::ASCENDING,
 160         ),
 161         array(
 162           'name' => ts('Email Address'),
 163           'sort' => $email . '.email',
 164           'direction' => CRM_Utils_Sort::DONTCARE,
 165         ),
 166       );
 167
 168       switch ($this->_event_type) {
 169         case 'queue':
 170           $dateSort = $job . '.start_date';
 171           break;
 172
 173         case 'delivered':
 174           $dateSort = CRM_Mailing_Event_BAO_Delivered::getTableName() . '.time_stamp';
 175           break;
 176
 177         case 'opened':
 178           $dateSort = CRM_Mailing_Event_BAO_Opened::getTableName() . '.time_stamp';
 179           break;
 180
 181         case 'bounce':
 182           $dateSort = CRM_Mailing_Event_BAO_Bounce::getTableName() . '.time_stamp';
 183           $this->_columnHeaders = array_merge($this->_columnHeaders,
 184             array(
 185               array(
 186                 'name' => ts('Bounce Type'),
 187               ),
 188               array(
 189                 'name' => ts('Bounce Reason'),
 190               ),
 191             )
 192           );
 193           break;
 194
 195         case 'forward':
 196           $dateSort = CRM_Mailing_Event_BAO_Forward::getTableName() . '.time_stamp';
 197
 198           $this->_columnHeaders = array_merge($this->_columnHeaders,
 199             array(
 200               array(
 201                 'name' => ts('Forwarded Email'),
 202               ),
 203             )
 204           );
 205           break;
 206
 207         case 'reply':
 208           $dateSort = CRM_Mailing_Event_BAO_Reply::getTableName() . '.time_stamp';
 209           break;
 210
 211         case 'unsubscribe':
 212           $dateSort = CRM_Mailing_Event_BAO_Unsubscribe::getTableName() . '.time_stamp';
 213           $this->_columnHeaders = array_merge($this->_columnHeaders, array(
 214             array(
 215                 'name' => ts('Unsubscribe'),
 216               ),
 217             ));
 218           break;
 219
 220         case 'optout':
 221           $dateSort = CRM_Mailing_Event_BAO_Unsubscribe::getTableName() . '.time_stamp';
 222           $this->_columnHeaders = array_merge($this->_columnHeaders, array(
 223             array(
 224                 'name' => ts('Opt-Out'),
 225               ),
 226             ));
 227           break;
 228
 229         case 'click':
 230           $dateSort = CRM_Mailing_Event_BAO_TrackableURLOpen::getTableName() . '.time_stamp';
 231           $this->_columnHeaders = array_merge($this->_columnHeaders, array(
 232             array(
 233                 'name' => ts('URL'),
 234               ),
 235             ));
 236           break;
 237
 238         default:
 239           return 0;
 240       }
 241
 242       $this->_columnHeaders = array_merge($this->_columnHeaders,
 243         array(
 244           array(
 245             'name' => ts('Date'),
 246             'sort' => $dateSort,
 247             'direction' => CRM_Utils_Sort::DESCENDING,
 248           ),
 249         )
 250       );
 251     }
 252     return $this->_columnHeaders;
 253   }
 254
 255   /**
 256    * Returns total number of rows for the query.
 257    *
 258    * @param
 259    *
 260    * @return int Total number of rows
 261    * @access public
 262    */
 263   function getTotalCount($action) {
 264     switch ($this->_event_type) {
 265       case 'queue':
 266         $event = new CRM_Mailing_Event_BAO_Queue();
 267         return $event->getTotalCount($this->_mailing_id,
 268           $this->_job_id
 269         );
 270       break;
 271
 272       case 'delivered':
 273         $event = new CRM_Mailing_Event_BAO_Delivered();
 274         return $event->getTotalCount($this->_mailing_id,
 275           $this->_job_id,
 276           $this->_is_distinct
 277         );
 278       break;
 279
 280       case 'opened':
 281         $event = new CRM_Mailing_Event_BAO_Opened();
 282         return $event->getTotalCount($this->_mailing_id,
 283           $this->_job_id,
 284           $this->_is_distinct
 285         );
 286       break;
 287
 288       case 'bounce':
 289         $event = new CRM_Mailing_Event_BAO_Bounce();
 290         return $event->getTotalCount($this->_mailing_id,
 291           $this->_job_id,
 292           $this->_is_distinct
 293         );
 294       break;
 295
 296       case 'forward':
 297         $event = new CRM_Mailing_Event_BAO_Forward();
 298         return $event->getTotalCount($this->_mailing_id,
 299           $this->_job_id,
 300           $this->_is_distinct
 301         );
 302       break;
 303
 304       case 'reply':
 305         $event = new CRM_Mailing_Event_BAO_Reply();
 306         return $event->getTotalCount($this->_mailing_id,
 307           $this->_job_id,
 308           $this->_is_distinct
 309         );
 310       break;
 311
 312       case 'unsubscribe':
 313         $event = new CRM_Mailing_Event_BAO_Unsubscribe();
 314         return $event->getTotalCount($this->_mailing_id,
 315           $this->_job_id,
 316           $this->_is_distinct
 317         );
 318       break;
 319
 320       case 'optout':
 321         $event = new CRM_Mailing_Event_BAO_Unsubscribe();
 322         return $event->getTotalCount($this->_mailing_id,
 323           $this->_job_id,
 324           $this->_is_distinct,
 325           FALSE
 326         );
 327       break;
 328
 329       case 'click':
 330         $event = new CRM_Mailing_Event_BAO_TrackableURLOpen();
 331         return $event->getTotalCount($this->_mailing_id,
 332           $this->_job_id,
 333           $this->_is_distinct,
 334           $this->_url_id
 335         );
 336       break;
 337
 338       default:
 339         return 0;
 340     }
 341   }
 342
 343   /**
 344    * returns all the rows in the given offset and rowCount
 345    *
 346    * @param enum   $action   the action being performed
 347    * @param int    $offset   the row number to start from
 348    * @param int    $rowCount the number of rows to return
 349    * @param string $sort     the sql string that describes the sort order
 350    * @param enum   $output   what should the result set include (web/email/csv)
 351    *
 352    * @return int   the total number of rows for this action
 353    */
 354   function &getRows($action, $offset, $rowCount, $sort, $output = NULL) {
 355     switch ($this->_event_type) {
 356       case 'queue':
 357         return CRM_Mailing_Event_BAO_Queue::getRows($this->_mailing_id,
 358           $this->_job_id, $offset, $rowCount, $sort
 359         );
 360       break;
 361
 362       case 'delivered':
 363         return CRM_Mailing_Event_BAO_Delivered::getRows($this->_mailing_id,
 364           $this->_job_id, $this->_is_distinct,
 365           $offset, $rowCount, $sort
 366         );
 367       break;
 368
 369       case 'opened':
 370         return CRM_Mailing_Event_BAO_Opened::getRows($this->_mailing_id,
 371           $this->_job_id, $this->_is_distinct,
 372           $offset, $rowCount, $sort
 373         );
 374       break;
 375
 376       case 'bounce':
 377         return CRM_Mailing_Event_BAO_Bounce::getRows($this->_mailing_id,
 378           $this->_job_id, $this->_is_distinct,
 379           $offset, $rowCount, $sort
 380         );
 381       break;
 382
 383       case 'forward':
 384         return CRM_Mailing_Event_BAO_Forward::getRows($this->_mailing_id,
 385           $this->_job_id, $this->_is_distinct,
 386           $offset, $rowCount, $sort
 387         );
 388
 389       case 'reply':
 390         return CRM_Mailing_Event_BAO_Reply::getRows($this->_mailing_id,
 391           $this->_job_id, $this->_is_distinct,
 392           $offset, $rowCount, $sort
 393         );
 394       break;
 395
 396       case 'unsubscribe':
 397         return CRM_Mailing_Event_BAO_Unsubscribe::getRows($this->_mailing_id,
 398           $this->_job_id, $this->_is_distinct,
 399           $offset, $rowCount, $sort, TRUE
 400         );
 401       break;
 402
 403       case 'optout':
 404         return CRM_Mailing_Event_BAO_Unsubscribe::getRows($this->_mailing_id,
 405           $this->_job_id, $this->_is_distinct,
 406           $offset, $rowCount, $sort, FALSE
 407         );
 408       break;
 409
 410       case 'click':
 411         return CRM_Mailing_Event_BAO_TrackableURLOpen::getRows(
 412           $this->_mailing_id, $this->_job_id,
 413           $this->_is_distinct, $this->_url_id,
 414           $offset, $rowCount, $sort
 415         );
 416       break;
 417
 418       default:
 419         return NULL;
 420     }
 421   }
 422
 423   /**
 424    * name of export file.
 425    *
 426    * @param string $output type of output
 427    *
 428    * @return string name of the file
 429    */
 430   function getExportFileName($output = 'csv') {}
 431
 432   function eventToTitle() {
 433     static $events = NULL;
 434
 435     if (empty($events)) {
 436       $events = array(
 437         'queue' => ts('Intended Recipients'),
 438         'delivered' => ts('Successful Deliveries'),
 439         'bounce' => ts('Bounces'),
 440         'forward' => ts('Forwards'),
 441         'reply' => $this->_is_distinct
 442          ? ts('Unique Replies')
 443          : ts('Replies'),
 444         'unsubscribe' => ts('Unsubscribe Requests'),
 445         'optout' => ts('Opt-out Requests'),
 446         'click' => $this->_is_distinct
 447          ? ts('Unique Click-throughs')
 448          : ts('Click-throughs'),
 449         'opened' => $this->_is_distinct
 450          ? ts('Unique Tracked Opens')
 451          : ts('Tracked Opens'),
 452       );
 453     }
 454     return $events[$this->_event_type];
 455   }
 456
 457   function getTitle() {
 458     return $this->eventToTitle();
 459   }
 460 }
 461 //end of class
 462