CRM/Mailing/Selector/Event.php

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