includes/class_notification.php

   1 <?php
   2 /*=====================================================================*\
   3 || ###################################################################
   4 || # Bugdar [#]version[#]
   5 || # Copyright ©2002-[#]year[#] Iris Studios, Inc.
   6 || #
   7 || # This program is free software; you can redistribute it and/or modify
   8 || # it under the terms of the GNU General Public License as published by
   9 || # the Free Software Foundation; version [#]gpl[#] of the License.
  10 || #
  11 || # This program is distributed in the hope that it will be useful, but
  12 || # WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  13 || # or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
  14 || # more details.
  15 || #
  16 || # You should have received a copy of the GNU General Public License along
  17 || # with this program; if not, write to the Free Software Foundation, Inc.,
  18 || # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
  19 || ###################################################################
  20 \*=====================================================================*/
  21
  22 /**
  23 * Notification Center
  24 *
  25 * This class determines which emails need to be sent out based on user
  26 * options and bug changes, and then it sends said emails.
  27 *
  28 * @author               Iris Studios, Inc.
  29 * @copyright    Copyright ©2002 - [#]year[#], Iris Studios, Inc.
  30 * @version              $Revision$
  31 * @package              Bugdar
  32 *
  33 */
  34 class NotificationCenter
  35 {
  36         /**
  37         * Bug information
  38         * @var  array
  39         * @access       private
  40         */
  41         var $bug = array();
  42
  43         /**
  44         * Original bug data
  45         * @var  array
  46         * @access       private
  47         */
  48         var $original = array();
  49
  50         /**
  51         * Modified bug data
  52         * @var  array
  53         * @access       private
  54         */
  55         var $modified = array();
  56
  57         /**
  58         * Global bugsys registry
  59         * @var  object
  60         * @access       private
  61         */
  62         var $registry = null;
  63
  64         /**
  65         * Role list: a list of user IDs with their relations to the bug
  66         * @var  array
  67         * @access       private
  68         */
  69         var $roles = array(
  70                 '-notapplicable-' => array(),
  71                 'reporter' => array(),
  72                 'assignee' => array(),
  73                 'favourite' => array(),
  74                 'voter' => array(),
  75                 'commenter' => array()
  76         );
  77
  78         /**
  79         * User cache list
  80         * @var  array
  81         * @access       private
  82         */
  83         var $users = array();
  84
  85         /**
  86         * A list of notices per-user that are combined together in NotificationCenter::finalize()
  87         * @var  array
  88         * @access       private
  89         */
  90         var $notices = array();
  91
  92         // ###################################################################
  93         /**
  94         * Constructor: set database objects
  95         *
  96         * @access       public
  97         */
  98         function __construct()
  99         {
 100                 global $bugsys;
 101
 102                 $this->registry =& $bugsys;
 103         }
 104
 105         // ###################################################################
 106         /**
 107         * (PHP 4) Constructor
 108         *
 109         * @access       public
 110         */
 111         function NotificationCenter()
 112         {
 113                 $this->__construct();
 114         }
 115
 116         // ###################################################################
 117         /**
 118         * Sets the bug data so that all methods in this class have access to
 119         * it when sending emails.
 120         *
 121         * @access       public
 122         *
 123         * @param        array   Original bug data
 124         * @param        array   Modified bug data
 125         */
 126         function set_bug_data($original, $modified = array())
 127         {
 128                 if (sizeof($modified) > 0)
 129                 {
 130                         $this->bug = $modified;
 131                 }
 132
 133                 $this->original = $original;
 134                 $this->modified = $modified;
 135
 136                 $this->roles['-notapplicable-'] = (sizeof($modified) > 0 ? array($original['assignedto'], $modified['assignedto']) : array($original['assignedto']));
 137                 $this->roles['reporter'] = array($original['userid']);
 138                 $this->roles['assignee'] = (sizeof($modified) > 0 ? array($modified['assignedto']) : array($original['assignedto']));
 139
 140                 $this->fetch_user_cache();
 141         }
 142
 143         // ###################################################################
 144         /**
 145         * Fetches all the users who could be related to the bug and sticks
 146         * their information into an array.
 147         *
 148         * @access       private
 149         */
 150         function fetch_user_cache()
 151         {
 152                 $favourites = $this->registry->db->query("SELECT userid FROM " . TABLE_PREFIX . "favourite WHERE bugid = " . $this->registry->clean($this->bug['bugid'], TYPE_UINT));
 153                 while ($fav = $this->registry->db->fetch_array($favourites))
 154                 {
 155                         $this->roles['favourite']["$fav[userid]"] = $fav['userid'];
 156                 }
 157
 158                 $voters = $this->registry->db->query_first("SELECT userids FROM " . TABLE_PREFIX . "vote WHERE bugid = " . $this->registry->clean($this->bug['bugid'], TYPE_UINT));
 159                 $this->roles['voter'] = preg_split('#,#', $voters['userids'], 0, PREG_SPLIT_NO_EMPTY);
 160
 161                 $commenters = $this->registry->db->query("SELECT userid FROM " . TABLE_PREFIX . "comment WHERE bugid = " . $this->registry->clean($this->bug['bugid'], TYPE_UINT));
 162                 while ($comment = $this->registry->db->fetch_array($commenters))
 163                 {
 164                         $this->roles['commenter']["$comment[userid]"] = $comment['userid'];
 165                 }
 166
 167                 $masterids = array_merge($this->roles['-notapplicable-'], $this->roles['reporter'], $this->roles['assignee'], $this->roles['favourite'], $this->roles['voter'], $this->roles['commenter']);
 168                 $masterids = array_unique($masterids);
 169
 170                 $userinfo = $this->registry->db->query("
 171                         SELECT user.*, useremail.*
 172                         FROM " . TABLE_PREFIX . "useremail AS useremail
 173                         LEFT JOIN " . TABLE_PREFIX . "user AS user
 174                                 ON (user.userid = useremail.userid)
 175                         WHERE useremail.userid IN (" . implode(',', $masterids) . ")
 176                 ");
 177                 while ($user = $this->registry->db->fetch_array($userinfo))
 178                 {
 179                         if (!is_array($this->users["$user[userid]"]))
 180                         {
 181                                 $this->users["$user[userid]"] = $user;
 182                                 unset($this->users["$user[userid]"]['mask'], $this->users["$user[userid]"]['relation']);
 183                         }
 184                         $this->users["$user[userid]"]['options']["$user[relation]"] = $user['mask'];
 185                 }
 186         }
 187
 188         // ###################################################################
 189         /**
 190         * Sends the appropriate emails for changes to bugs. This function
 191         * works a lot like the Logging class by taking BugAPI->objdata and
 192         * BugAPI->values and then comparing the two arries and sending emails
 193         * with the differences.
 194         *
 195         * @access       public
 196         */
 197         function send_bug_changes_notice()
 198         {
 199                 if (!isset($this->modified['bugid']))
 200                 {
 201                         return;
 202                 }
 203
 204                 if ($this->original['assignedto'] != $this->modified['assignedto'])
 205                 {
 206                         if ($this->original['assignedto'] != '')
 207                         {
 208                                 $this->notice_no_longer_assigned($this->original['assignedto']);
 209                         }
 210                         if ($this->modified['assignedto'] != '')
 211                         {
 212                                 $this->notice_now_assigned($this->modified['assignedto']);
 213                         }
 214                 }
 215
 216                 if ($this->original['status'] != $this->modified['status'])
 217                 {
 218                         $this->notice_status_change($this->original['status'], $this->modified['status']);
 219                 }
 220                 if ($this->original['resolution'] != $this->modified['resoultion'])
 221                 {
 222                         $this->notice_resolution_change($this->original['resolution'], $this->modified['resolution']);
 223                 }
 224
 225                 if ($this->original['duplicates'] != $this->modified['duplicates'])
 226                 {
 227                         $this->notice_duplicates_change($this->original['duplicates'], $this->modified['duplicates']);
 228                 }
 229         }
 230
 231         // ###################################################################
 232         /**
 233         * Sends an email to the specified user ID that they are no longer the
 234         * person assigned to the bug.
 235         *
 236         * @access       private
 237         *
 238         * @param        integer User ID to send to
 239         */
 240         function notice_no_longer_assigned($userid)
 241         {
 242                 if ($this->users["$userid"]['options'][0] & $this->registry->emailoptions['notifications']['assignedto'] AND in_array($userid, $this->roles['-notapplicable-']))
 243                 {
 244                         $this->notices["$userid"][] = sprintf(
 245 $this->registry->lang->string('You are no longer assigned to this bug, per %1$s\'s changes.'),
 246
 247                                 construct_user_display($this->registry->userinfo, false)
 248                         );
 249                 }
 250         }
 251
 252         // ###################################################################
 253         /**
 254         * Informs the user that they have been made the assignee of the bug.
 255         *
 256         * @access       private
 257         *
 258         * @param        integer User ID
 259         */
 260         function notice_now_assigned($userid)
 261         {
 262                 if ($this->users["$userid"]['options'][0] & $this->registry->emailoptions['notifications']['assignedto'] AND in_array($userid, $this->roles['-notapplicable-']))
 263                 {
 264                         $this->notices["$userid"][] = sprintf(
 265 $this->registry->lang->string('You have been assigned to this bug by %1$s.'),
 266
 267                                 construct_user_display($this->registry->userinfo, false)
 268                         );
 269                 }
 270         }
 271
 272         // ###################################################################
 273         /**
 274         * Sends a message to inform users that the status has changed.
 275         *
 276         * @access       private
 277         *
 278         * @param        integer Old status
 279         * @param        integer New status
 280         */
 281         function notice_status_change($old, $new)
 282         {
 283                 $userlist = $this->fetch_users_with_on_bit('statusresolve');
 284                 foreach ($userlist AS $userid => $user)
 285                 {
 286                         $this->notices["$user[userid]"][] = sprintf(
 287 $this->registry->lang->string('The status field has changed from "%1$s" to "%2$s".'),
 288
 289                                 $this->registry->datastore['status']["$old"]['status'],
 290                                 $this->registry->datastore['status']["$new"]['status']
 291                         );
 292                 }
 293         }
 294
 295         // ###################################################################
 296         /**
 297         * Sends an email to inform users that the resolution has changed.
 298         *
 299         * @access       private
 300         *
 301         * @param        integer Old resolution
 302         * @param        integer New resolution
 303         */
 304         function notice_resolution_change($old, $new)
 305         {
 306                 $userlist = $this->fetch_users_with_on_bit('statusresolve');
 307                 foreach ($userlist AS $userid => $user)
 308                 {
 309                         $this->notices["$user[userid]"][] = sprintf(
 310 $this->registry->lang->string('The resolution field has changed from "%1$s" to "%2$s".'),
 311
 312                                 $this->registry->datastore['resolution']["$old"]['resolution'],
 313                                 $this->registry->datastore['resolution']["$new"]['resolution']
 314                         );
 315                 }
 316         }
 317
 318         // ###################################################################
 319         /**
 320         * Informs users that the duplicates list has changed.
 321         *
 322         * @access       private
 323         *
 324         * @param        string  Old duplicates list
 325         * @param        string  New duplicates list
 326         */
 327         function notice_duplicates_change($old, $new)
 328         {
 329
 330         }
 331
 332         // ###################################################################
 333         /**
 334         * Sends the appropriate users information about a new comment being
 335         * posted to the bug report.
 336         *
 337         * @access       public
 338         *
 339         * @param        array   CommentAPI->values array
 340         */
 341         function send_new_comment_notice($comment)
 342         {
 343                 $userlist = $this->fetch_users_with_on_bit('newcomment');
 344                 foreach ($userlist AS $userid => $user)
 345                 {
 346                         $this->notices["$user[userid]"][] = sprintf(
 347 $this->registry->lang->string('The following comment was added by %1$s on %2$s:
 348 ============================================
 349 %3$s
 350 ============================================'),
 351
 352                                 construct_user_display($this->registry->userinfo, false),
 353                                 $this->registry->modules['date']->format($this->registry->options['dateformat'], $comment['dateline']),
 354                                 $comment['comment']
 355                         );
 356                 }
 357         }
 358
 359         // ###################################################################
 360         /**
 361         * Generates an array of users who have a given email notification flag
 362         * turned on in their bitfields.
 363         *
 364         * @access       private
 365         *
 366         * @param        string  Notification bitfield name
 367         *
 368         * @return       array   Array of users and their data
 369         */
 370         function fetch_users_with_on_bit($bitname)
 371         {
 372                 $idlist = array();
 373
 374                 foreach ($this->users AS $user)
 375                 {
 376                         foreach ($this->registry->emailoptions['relations'] AS $name => $bit)
 377                         {
 378                                 if (in_array($user['userid'], $this->roles["$name"]) AND $user['options']["$bit"] & $this->registry->emailoptions['notifications']["$bitname"])
 379                                 {
 380                                         $idlist[] = $user['userid'];
 381                                 }
 382                         }
 383                 }
 384
 385                 $masters = array_unique($idlist);
 386
 387                 $return = array();
 388                 foreach ($masters AS $userid)
 389                 {
 390                         $return["$userid"] =& $this->users["$userid"];
 391                 }
 392
 393                 return $return;
 394         }
 395 }
 396
 397 /*=====================================================================*\
 398 || ###################################################################
 399 || # $HeadURL$
 400 || # $Id$
 401 || ###################################################################
 402 \*=====================================================================*/
 403 ?>