CRM/Mailing/Selector/Event.php

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