includes/WatchedItem.php

   1 <?php
   2 /**
   3  * Accessor and mutator for watchlist entries.
   4  *
   5  * This program is free software; you can redistribute it and/or modify
   6  * it under the terms of the GNU General Public License as published by
   7  * the Free Software Foundation; either version 2 of the License, or
   8  * (at your option) any later version.
   9  *
  10  * This program is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  13  * GNU General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU General Public License along
  16  * with this program; if not, write to the Free Software Foundation, Inc.,
  17  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  18  * http://www.gnu.org/copyleft/gpl.html
  19  *
  20  * @file
  21  * @ingroup Watchlist
  22  */
  23
  24 /**
  25  * Representation of a pair of user and title for watchlist entries.
  26  *
  27  * @ingroup Watchlist
  28  */
  29 class WatchedItem {
  30         /** @var Title */
  31         public $mTitle;
  32
  33         /** @var User */
  34         public $mUser;
  35
  36         /** @var int */
  37         public $mCheckRights;
  38
  39         /** @var bool */
  40         private $loaded = false;
  41
  42         /** @var bool */
  43         private $watched;
  44
  45         /** @var string */
  46         private $timestamp;
  47
  48         /**
  49          * Constant to specify that user rights 'editmywatchlist' and
  50          * 'viewmywatchlist' should not be checked.
  51          * @since 1.22
  52          */
  53         const IGNORE_USER_RIGHTS = 0;
  54
  55         /**
  56          * Constant to specify that user rights 'editmywatchlist' and
  57          * 'viewmywatchlist' should be checked.
  58          * @since 1.22
  59          */
  60         const CHECK_USER_RIGHTS = 1;
  61
  62         /**
  63          * Do DB master updates right now
  64          * @since 1.26
  65          */
  66         const IMMEDIATE = 0;
  67         /**
  68          * Do DB master updates via the job queue
  69          * @since 1.26
  70          */
  71         const DEFERRED = 1;
  72
  73         /**
  74          * Create a WatchedItem object with the given user and title
  75          * @since 1.22 $checkRights parameter added
  76          * @param User $user The user to use for (un)watching
  77          * @param Title $title The title we're going to (un)watch
  78          * @param int $checkRights Whether to check the 'viewmywatchlist' and 'editmywatchlist' rights.
  79          *     Pass either WatchedItem::IGNORE_USER_RIGHTS or WatchedItem::CHECK_USER_RIGHTS.
  80          * @return WatchedItem
  81          */
  82         public static function fromUserTitle( $user, $title,
  83                 $checkRights = WatchedItem::CHECK_USER_RIGHTS
  84         ) {
  85                 $wl = new WatchedItem;
  86                 $wl->mUser = $user;
  87                 $wl->mTitle = $title;
  88                 $wl->mCheckRights = $checkRights;
  89
  90                 return $wl;
  91         }
  92
  93         /**
  94          * Title being watched
  95          * @return Title
  96          */
  97         protected function getTitle() {
  98                 return $this->mTitle;
  99         }
 100
 101         /**
 102          * Helper to retrieve the title namespace
 103          * @return int
 104          */
 105         protected function getTitleNs() {
 106                 return $this->getTitle()->getNamespace();
 107         }
 108
 109         /**
 110          * Helper to retrieve the title DBkey
 111          * @return string
 112          */
 113         protected function getTitleDBkey() {
 114                 return $this->getTitle()->getDBkey();
 115         }
 116
 117         /**
 118          * Helper to retrieve the user id
 119          * @return int
 120          */
 121         protected function getUserId() {
 122                 return $this->mUser->getId();
 123         }
 124
 125         /**
 126          * Return an array of conditions to select or update the appropriate database
 127          * row.
 128          *
 129          * @return array
 130          */
 131         private function dbCond() {
 132                 return array(
 133                         'wl_user' => $this->getUserId(),
 134                         'wl_namespace' => $this->getTitleNs(),
 135                         'wl_title' => $this->getTitleDBkey(),
 136                 );
 137         }
 138
 139         /**
 140          * Load the object from the database
 141          */
 142         private function load() {
 143                 if ( $this->loaded ) {
 144                         return;
 145                 }
 146                 $this->loaded = true;
 147
 148                 // Only loggedin user can have a watchlist
 149                 if ( $this->mUser->isAnon() ) {
 150                         $this->watched = false;
 151                         return;
 152                 }
 153
 154                 // some pages cannot be watched
 155                 if ( !$this->getTitle()->isWatchable() ) {
 156                         $this->watched = false;
 157                         return;
 158                 }
 159
 160                 # Pages and their talk pages are considered equivalent for watching;
 161                 # remember that talk namespaces are numbered as page namespace+1.
 162
 163                 $dbr = wfGetDB( DB_SLAVE );
 164                 $row = $dbr->selectRow( 'watchlist', 'wl_notificationtimestamp',
 165                         $this->dbCond(), __METHOD__ );
 166
 167                 if ( $row === false ) {
 168                         $this->watched = false;
 169                 } else {
 170                         $this->watched = true;
 171                         $this->timestamp = $row->wl_notificationtimestamp;
 172                 }
 173         }
 174
 175         /**
 176          * Check permissions
 177          * @param string $what 'viewmywatchlist' or 'editmywatchlist'
 178          * @return bool
 179          */
 180         private function isAllowed( $what ) {
 181                 return !$this->mCheckRights || $this->mUser->isAllowed( $what );
 182         }
 183
 184         /**
 185          * Is mTitle being watched by mUser?
 186          * @return bool
 187          */
 188         public function isWatched() {
 189                 if ( !$this->isAllowed( 'viewmywatchlist' ) ) {
 190                         return false;
 191                 }
 192
 193                 $this->load();
 194                 return $this->watched;
 195         }
 196
 197         /**
 198          * Get the notification timestamp of this entry.
 199          *
 200          * @return bool|null|string False if the page is not watched, the value of
 201          *   the wl_notificationtimestamp field otherwise
 202          */
 203         public function getNotificationTimestamp() {
 204                 if ( !$this->isAllowed( 'viewmywatchlist' ) ) {
 205                         return false;
 206                 }
 207
 208                 $this->load();
 209                 if ( $this->watched ) {
 210                         return $this->timestamp;
 211                 } else {
 212                         return false;
 213                 }
 214         }
 215
 216         /**
 217          * Reset the notification timestamp of this entry
 218          *
 219          * @param bool $force Whether to force the write query to be executed even if the
 220          *    page is not watched or the notification timestamp is already NULL.
 221          * @param int $oldid The revision id being viewed. If not given or 0, latest revision is assumed.
 222          * @mode int $mode WatchedItem::DEFERRED/IMMEDIATE
 223          */
 224         public function resetNotificationTimestamp(
 225                 $force = '', $oldid = 0, $mode = self::IMMEDIATE
 226         ) {
 227                 global $wgActivityUpdatesUseJobQueue;
 228
 229                 // Only loggedin user can have a watchlist
 230                 if ( wfReadOnly() || $this->mUser->isAnon() || !$this->isAllowed( 'editmywatchlist' ) ) {
 231                         return;
 232                 }
 233
 234                 if ( $force != 'force' ) {
 235                         $this->load();
 236                         if ( !$this->watched || $this->timestamp === null ) {
 237                                 return;
 238                         }
 239                 }
 240
 241                 $title = $this->getTitle();
 242                 if ( !$oldid ) {
 243                         // No oldid given, assuming latest revision; clear the timestamp.
 244                         $notificationTimestamp = null;
 245                 } elseif ( !$title->getNextRevisionID( $oldid ) ) {
 246                         // Oldid given and is the latest revision for this title; clear the timestamp.
 247                         $notificationTimestamp = null;
 248                 } else {
 249                         // See if the version marked as read is more recent than the one we're viewing.
 250                         // Call load() if it wasn't called before due to $force.
 251                         $this->load();
 252
 253                         if ( $this->timestamp === null ) {
 254                                 // This can only happen if $force is enabled.
 255                                 $notificationTimestamp = null;
 256                         } else {
 257                                 // Oldid given and isn't the latest; update the timestamp.
 258                                 // This will result in no further notification emails being sent!
 259                                 $notificationTimestamp = Revision::getTimestampFromId( $title, $oldid );
 260                                 // We need to go one second to the future because of various strict comparisons
 261                                 // throughout the codebase
 262                                 $ts = new MWTimestamp( $notificationTimestamp );
 263                                 $ts->timestamp->add( new DateInterval( 'PT1S' ) );
 264                                 $notificationTimestamp = $ts->getTimestamp( TS_MW );
 265
 266                                 if ( $notificationTimestamp < $this->timestamp ) {
 267                                         if ( $force != 'force' ) {
 268                                                 return;
 269                                         } else {
 270                                                 // This is a little silly…
 271                                                 $notificationTimestamp = $this->timestamp;
 272                                         }
 273                                 }
 274                         }
 275                 }
 276
 277                 // If the page is watched by the user (or may be watched), update the timestamp
 278                 if ( $mode === self::DEFERRED && $wgActivityUpdatesUseJobQueue ) {
 279                         JobQueueGroup::singleton()->push(
 280                                 EnqueueJob::newFromLocalJobs( new JobSpecification(
 281                                         'activityUpdateJob',
 282                                         array(
 283                                                 'type'      => 'updateWatchlistNotification',
 284                                                 'userid'    => $this->getUserId(),
 285                                                 'notifTime' => $notificationTimestamp,
 286                                                 'curTime'   => time()
 287                                         ),
 288                                         array( 'removeDuplicates' => true ),
 289                                         $title
 290                                 ) )
 291                         );
 292                 } else {
 293                         $dbw = wfGetDB( DB_MASTER );
 294                         $dbw->update( 'watchlist',
 295                                 array( 'wl_notificationtimestamp' => $notificationTimestamp ),
 296                                 $this->dbCond(),
 297                                 __METHOD__
 298                         );
 299                 }
 300
 301                 $this->timestamp = null;
 302         }
 303
 304         /**
 305          * @param WatchedItem[] $items
 306          * @return bool
 307          */
 308         public static function batchAddWatch( array $items ) {
 309
 310                 if ( wfReadOnly() ) {
 311                         return false;
 312                 }
 313
 314                 $rows = array();
 315                 foreach ( $items as $item ) {
 316                         // Only loggedin user can have a watchlist
 317                         if ( $item->mUser->isAnon() || !$item->isAllowed( 'editmywatchlist' ) ) {
 318                                 continue;
 319                         }
 320                         $rows[] = array(
 321                                 'wl_user' => $item->getUserId(),
 322                                 'wl_namespace' => MWNamespace::getSubject( $item->getTitleNs() ),
 323                                 'wl_title' => $item->getTitleDBkey(),
 324                                 'wl_notificationtimestamp' => null,
 325                         );
 326                         // Every single watched page needs now to be listed in watchlist;
 327                         // namespace:page and namespace_talk:page need separate entries:
 328                         $rows[] = array(
 329                                 'wl_user' => $item->getUserId(),
 330                                 'wl_namespace' => MWNamespace::getTalk( $item->getTitleNs() ),
 331                                 'wl_title' => $item->getTitleDBkey(),
 332                                 'wl_notificationtimestamp' => null
 333                         );
 334                         $item->watched = true;
 335                 }
 336
 337                 if ( !$rows ) {
 338                         return false;
 339                 }
 340
 341                 $dbw = wfGetDB( DB_MASTER );
 342                 foreach ( array_chunk( $rows, 100 ) as $toInsert ) {
 343                         // Use INSERT IGNORE to avoid overwriting the notification timestamp
 344                         // if there's already an entry for this page
 345                         $dbw->insert( 'watchlist', $toInsert, __METHOD__, 'IGNORE' );
 346                 }
 347
 348                 return true;
 349         }
 350
 351         /**
 352          * Given a title and user (assumes the object is setup), add the watch to the database.
 353          * @return bool
 354          */
 355         public function addWatch() {
 356                 return self::batchAddWatch( array( $this ) );
 357         }
 358
 359         /**
 360          * Same as addWatch, only the opposite.
 361          * @return bool
 362          */
 363         public function removeWatch() {
 364
 365                 // Only loggedin user can have a watchlist
 366                 if ( wfReadOnly() || $this->mUser->isAnon() || !$this->isAllowed( 'editmywatchlist' ) ) {
 367                         return false;
 368                 }
 369
 370                 $success = false;
 371                 $dbw = wfGetDB( DB_MASTER );
 372                 $dbw->delete( 'watchlist',
 373                         array(
 374                                 'wl_user' => $this->getUserId(),
 375                                 'wl_namespace' => MWNamespace::getSubject( $this->getTitleNs() ),
 376                                 'wl_title' => $this->getTitleDBkey(),
 377                         ), __METHOD__
 378                 );
 379                 if ( $dbw->affectedRows() ) {
 380                         $success = true;
 381                 }
 382
 383                 # the following code compensates the new behavior, introduced by the
 384                 # enotif patch, that every single watched page needs now to be listed
 385                 # in watchlist namespace:page and namespace_talk:page had separate
 386                 # entries: clear them
 387                 $dbw->delete( 'watchlist',
 388                         array(
 389                                 'wl_user' => $this->getUserId(),
 390                                 'wl_namespace' => MWNamespace::getTalk( $this->getTitleNs() ),
 391                                 'wl_title' => $this->getTitleDBkey(),
 392                         ), __METHOD__
 393                 );
 394
 395                 if ( $dbw->affectedRows() ) {
 396                         $success = true;
 397                 }
 398
 399                 $this->watched = false;
 400
 401                 return $success;
 402         }
 403
 404         /**
 405          * Check if the given title already is watched by the user, and if so
 406          * add watches on a new title. To be used for page renames and such.
 407          *
 408          * @param Title $ot Page title to duplicate entries from, if present
 409          * @param Title $nt Page title to add watches on
 410          */
 411         public static function duplicateEntries( $ot, $nt ) {
 412                 WatchedItem::doDuplicateEntries( $ot->getSubjectPage(), $nt->getSubjectPage() );
 413                 WatchedItem::doDuplicateEntries( $ot->getTalkPage(), $nt->getTalkPage() );
 414         }
 415
 416         /**
 417          * Handle duplicate entries. Backend for duplicateEntries().
 418          *
 419          * @param Title $ot
 420          * @param Title $nt
 421          *
 422          * @return bool
 423          */
 424         private static function doDuplicateEntries( $ot, $nt ) {
 425                 $oldnamespace = $ot->getNamespace();
 426                 $newnamespace = $nt->getNamespace();
 427                 $oldtitle = $ot->getDBkey();
 428                 $newtitle = $nt->getDBkey();
 429
 430                 $dbw = wfGetDB( DB_MASTER );
 431                 $res = $dbw->select( 'watchlist',
 432                         array( 'wl_user', 'wl_notificationtimestamp' ),
 433                         array( 'wl_namespace' => $oldnamespace, 'wl_title' => $oldtitle ),
 434                         __METHOD__, 'FOR UPDATE'
 435                 );
 436                 # Construct array to replace into the watchlist
 437                 $values = array();
 438                 foreach ( $res as $s ) {
 439                         $values[] = array(
 440                                 'wl_user' => $s->wl_user,
 441                                 'wl_namespace' => $newnamespace,
 442                                 'wl_title' => $newtitle,
 443                                 'wl_notificationtimestamp' => $s->wl_notificationtimestamp,
 444                         );
 445                 }
 446
 447                 if ( empty( $values ) ) {
 448                         // Nothing to do
 449                         return true;
 450                 }
 451
 452                 # Perform replace
 453                 # Note that multi-row replace is very efficient for MySQL but may be inefficient for
 454                 # some other DBMSes, mostly due to poor simulation by us
 455                 $dbw->replace(
 456                         'watchlist',
 457                         array( array( 'wl_user', 'wl_namespace', 'wl_title' ) ),
 458                         $values,
 459                         __METHOD__
 460                 );
 461
 462                 return true;
 463         }
 464 }