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         /**
  31          * Constant to specify that user rights 'editmywatchlist' and
  32          * 'viewmywatchlist' should not be checked.
  33          * @since 1.22
  34          */
  35         const IGNORE_USER_RIGHTS = 0;
  36
  37         /**
  38          * Constant to specify that user rights 'editmywatchlist' and
  39          * 'viewmywatchlist' should be checked.
  40          * @since 1.22
  41          */
  42         const CHECK_USER_RIGHTS = 1;
  43
  44         var $mTitle, $mUser, $mCheckRights;
  45         private $loaded = false, $watched, $timestamp;
  46
  47         /**
  48          * Create a WatchedItem object with the given user and title
  49          * @since 1.22 $checkRights parameter added
  50          * @param $user User: the user to use for (un)watching
  51          * @param $title Title: the title we're going to (un)watch
  52          * @param $checkRights int: Whether to check the 'viewmywatchlist' and 'editmywatchlist' rights.
  53          *     Pass either WatchedItem::IGNORE_USER_RIGHTS or WatchedItem::CHECK_USER_RIGHTS.
  54          * @return WatchedItem object
  55          */
  56         public static function fromUserTitle( $user, $title, $checkRights = WatchedItem::CHECK_USER_RIGHTS ) {
  57                 $wl = new WatchedItem;
  58                 $wl->mUser = $user;
  59                 $wl->mTitle = $title;
  60                 $wl->mCheckRights = $checkRights;
  61
  62                 return $wl;
  63         }
  64
  65         /**
  66          * Title being watched
  67          * @return Title
  68          */
  69         protected function getTitle() {
  70                 return $this->mTitle;
  71         }
  72
  73         /**
  74          * Helper to retrieve the title namespace
  75          * @return int
  76          */
  77         protected function getTitleNs() {
  78                 return $this->getTitle()->getNamespace();
  79         }
  80
  81         /**
  82          * Helper to retrieve the title DBkey
  83          * @return string
  84          */
  85         protected function getTitleDBkey() {
  86                 return $this->getTitle()->getDBkey();
  87         }
  88
  89         /**
  90          * Helper to retrieve the user id
  91          * @return int
  92          */
  93         protected function getUserId() {
  94                 return $this->mUser->getId();
  95         }
  96
  97         /**
  98          * Return an array of conditions to select or update the appropriate database
  99          * row.
 100          *
 101          * @return array
 102          */
 103         private function dbCond() {
 104                 return array(
 105                         'wl_user' => $this->getUserId(),
 106                         'wl_namespace' => $this->getTitleNs(),
 107                         'wl_title' => $this->getTitleDBkey(),
 108                 );
 109         }
 110
 111         /**
 112          * Load the object from the database
 113          */
 114         private function load() {
 115                 if ( $this->loaded ) {
 116                         return;
 117                 }
 118                 $this->loaded = true;
 119
 120                 // Only loggedin user can have a watchlist
 121                 if ( $this->mUser->isAnon() ) {
 122                         $this->watched = false;
 123                         return;
 124                 }
 125
 126                 // some pages cannot be watched
 127                 if ( !$this->getTitle()->isWatchable() ) {
 128                         $this->watched = false;
 129                         return;
 130                 }
 131
 132                 # Pages and their talk pages are considered equivalent for watching;
 133                 # remember that talk namespaces are numbered as page namespace+1.
 134
 135                 $dbr = wfGetDB( DB_SLAVE );
 136                 $row = $dbr->selectRow( 'watchlist', 'wl_notificationtimestamp',
 137                         $this->dbCond(), __METHOD__ );
 138
 139                 if ( $row === false ) {
 140                         $this->watched = false;
 141                 } else {
 142                         $this->watched = true;
 143                         $this->timestamp = $row->wl_notificationtimestamp;
 144                 }
 145         }
 146
 147         /**
 148          * Check permissions
 149          * @param $what string: 'viewmywatchlist' or 'editmywatchlist'
 150          */
 151         private function isAllowed( $what ) {
 152                 return !$this->mCheckRights || $this->mUser->isAllowed( $what );
 153         }
 154
 155         /**
 156          * Is mTitle being watched by mUser?
 157          * @return bool
 158          */
 159         public function isWatched() {
 160                 if ( !$this->isAllowed( 'viewmywatchlist' ) ) {
 161                         return false;
 162                 }
 163
 164                 $this->load();
 165                 return $this->watched;
 166         }
 167
 168         /**
 169          * Get the notification timestamp of this entry.
 170          *
 171          * @return false|null|string: false if the page is not watched, the value of
 172          *         the wl_notificationtimestamp field otherwise
 173          */
 174         public function getNotificationTimestamp() {
 175                 if ( !$this->isAllowed( 'viewmywatchlist' ) ) {
 176                         return false;
 177                 }
 178
 179                 $this->load();
 180                 if ( $this->watched ) {
 181                         return $this->timestamp;
 182                 } else {
 183                         return false;
 184                 }
 185         }
 186
 187         /**
 188          * Reset the notification timestamp of this entry
 189          *
 190          * @param $force Whether to force the write query to be executed even if the
 191          *        page is not watched or the notification timestamp is already NULL.
 192          * @param int $oldid The revision id being viewed. If not given or 0, latest revision is assumed.
 193          */
 194         public function resetNotificationTimestamp( $force = '', $oldid = 0 ) {
 195                 // Only loggedin user can have a watchlist
 196                 if ( wfReadOnly() || $this->mUser->isAnon() || !$this->isAllowed( 'editmywatchlist' ) ) {
 197                         return;
 198                 }
 199
 200                 if ( $force != 'force' ) {
 201                         $this->load();
 202                         if ( !$this->watched || $this->timestamp === null ) {
 203                                 return;
 204                         }
 205                 }
 206
 207                 $title = $this->getTitle();
 208                 if ( !$oldid ) {
 209                         // No oldid given, assuming latest revision; clear the timestamp.
 210                         $notificationTimestamp = null;
 211                 } elseif ( !$title->getNextRevisionID( $oldid ) ) {
 212                         // Oldid given and is the latest revision for this title; clear the timestamp.
 213                         $notificationTimestamp = null;
 214                 } else {
 215                         // See if the version marked as read is more recent than the one we're viewing.
 216                         // Call load() if it wasn't called before due to $force.
 217                         $this->load();
 218
 219                         if ( $this->timestamp === null ) {
 220                                 // This can only happen if $force is enabled.
 221                                 $notificationTimestamp = null;
 222                         } else {
 223                                 // Oldid given and isn't the latest; update the timestamp.
 224                                 // This will result in no further notification emails being sent!
 225                                 $dbr = wfGetDB( DB_SLAVE );
 226                                 $notificationTimestamp = $dbr->selectField(
 227                                         'revision', 'rev_timestamp',
 228                                         array( 'rev_page' => $title->getArticleID(), 'rev_id' => $oldid )
 229                                 );
 230                                 // We need to go one second to the future because of various strict comparisons
 231                                 // throughout the codebase
 232                                 $ts = new MWTimestamp( $notificationTimestamp );
 233                                 $ts->timestamp->add( new DateInterval( 'PT1S' ) );
 234                                 $notificationTimestamp = $ts->getTimestamp( TS_MW );
 235
 236                                 if ( $notificationTimestamp < $this->timestamp ) {
 237                                         if ( $force != 'force' ) {
 238                                                 return;
 239                                         } else {
 240                                                 // This is a little silly…
 241                                                 $notificationTimestamp = $this->timestamp;
 242                                         }
 243                                 }
 244                         }
 245                 }
 246
 247                 // If the page is watched by the user (or may be watched), update the timestamp on any
 248                 // any matching rows
 249                 $dbw = wfGetDB( DB_MASTER );
 250                 $dbw->update( 'watchlist', array( 'wl_notificationtimestamp' => $notificationTimestamp ),
 251                         $this->dbCond(), __METHOD__ );
 252                 $this->timestamp = null;
 253         }
 254
 255         /**
 256          * Given a title and user (assumes the object is setup), add the watch to the
 257          * database.
 258          * @return bool
 259          */
 260         public function addWatch() {
 261                 wfProfileIn( __METHOD__ );
 262
 263                 // Only loggedin user can have a watchlist
 264                 if ( wfReadOnly() || $this->mUser->isAnon() || !$this->isAllowed( 'editmywatchlist' ) ) {
 265                         wfProfileOut( __METHOD__ );
 266                         return false;
 267                 }
 268
 269                 // Use INSERT IGNORE to avoid overwriting the notification timestamp
 270                 // if there's already an entry for this page
 271                 $dbw = wfGetDB( DB_MASTER );
 272                 $dbw->insert( 'watchlist',
 273                         array(
 274                                 'wl_user' => $this->getUserId(),
 275                                 'wl_namespace' => MWNamespace::getSubject( $this->getTitleNs() ),
 276                                 'wl_title' => $this->getTitleDBkey(),
 277                                 'wl_notificationtimestamp' => null
 278                         ), __METHOD__, 'IGNORE' );
 279
 280                 // Every single watched page needs now to be listed in watchlist;
 281                 // namespace:page and namespace_talk:page need separate entries:
 282                 $dbw->insert( 'watchlist',
 283                         array(
 284                                 'wl_user' => $this->getUserId(),
 285                                 'wl_namespace' => MWNamespace::getTalk( $this->getTitleNs() ),
 286                                 'wl_title' => $this->getTitleDBkey(),
 287                                 'wl_notificationtimestamp' => null
 288                         ), __METHOD__, 'IGNORE' );
 289
 290                 $this->watched = true;
 291
 292                 wfProfileOut( __METHOD__ );
 293                 return true;
 294         }
 295
 296         /**
 297          * Same as addWatch, only the opposite.
 298          * @return bool
 299          */
 300         public function removeWatch() {
 301                 wfProfileIn( __METHOD__ );
 302
 303                 // Only loggedin user can have a watchlist
 304                 if ( wfReadOnly() || $this->mUser->isAnon() || !$this->isAllowed( 'editmywatchlist' ) ) {
 305                         wfProfileOut( __METHOD__ );
 306                         return false;
 307                 }
 308
 309                 $success = false;
 310                 $dbw = wfGetDB( DB_MASTER );
 311                 $dbw->delete( 'watchlist',
 312                         array(
 313                                 'wl_user' => $this->getUserId(),
 314                                 'wl_namespace' => MWNamespace::getSubject( $this->getTitleNs() ),
 315                                 'wl_title' => $this->getTitleDBkey(),
 316                         ), __METHOD__
 317                 );
 318                 if ( $dbw->affectedRows() ) {
 319                         $success = true;
 320                 }
 321
 322                 # the following code compensates the new behavior, introduced by the
 323                 # enotif patch, that every single watched page needs now to be listed
 324                 # in watchlist namespace:page and namespace_talk:page had separate
 325                 # entries: clear them
 326                 $dbw->delete( 'watchlist',
 327                         array(
 328                                 'wl_user' => $this->getUserId(),
 329                                 'wl_namespace' => MWNamespace::getTalk( $this->getTitleNs() ),
 330                                 'wl_title' => $this->getTitleDBkey(),
 331                         ), __METHOD__
 332                 );
 333
 334                 if ( $dbw->affectedRows() ) {
 335                         $success = true;
 336                 }
 337
 338                 $this->watched = false;
 339
 340                 wfProfileOut( __METHOD__ );
 341                 return $success;
 342         }
 343
 344         /**
 345          * Check if the given title already is watched by the user, and if so
 346          * add watches on a new title. To be used for page renames and such.
 347          *
 348          * @param $ot Title: page title to duplicate entries from, if present
 349          * @param $nt Title: page title to add watches on
 350          */
 351         public static function duplicateEntries( $ot, $nt ) {
 352                 WatchedItem::doDuplicateEntries( $ot->getSubjectPage(), $nt->getSubjectPage() );
 353                 WatchedItem::doDuplicateEntries( $ot->getTalkPage(), $nt->getTalkPage() );
 354         }
 355
 356         /**
 357          * Handle duplicate entries. Backend for duplicateEntries().
 358          *
 359          * @param $ot Title
 360          * @param $nt Title
 361          *
 362          * @return bool
 363          */
 364         private static function doDuplicateEntries( $ot, $nt ) {
 365                 $oldnamespace = $ot->getNamespace();
 366                 $newnamespace = $nt->getNamespace();
 367                 $oldtitle = $ot->getDBkey();
 368                 $newtitle = $nt->getDBkey();
 369
 370                 $dbw = wfGetDB( DB_MASTER );
 371                 $res = $dbw->select( 'watchlist', 'wl_user',
 372                         array( 'wl_namespace' => $oldnamespace, 'wl_title' => $oldtitle ),
 373                         __METHOD__, 'FOR UPDATE'
 374                 );
 375                 # Construct array to replace into the watchlist
 376                 $values = array();
 377                 foreach ( $res as $s ) {
 378                         $values[] = array(
 379                                 'wl_user' => $s->wl_user,
 380                                 'wl_namespace' => $newnamespace,
 381                                 'wl_title' => $newtitle
 382                         );
 383                 }
 384
 385                 if ( empty( $values ) ) {
 386                         // Nothing to do
 387                         return true;
 388                 }
 389
 390                 # Perform replace
 391                 # Note that multi-row replace is very efficient for MySQL but may be inefficient for
 392                 # some other DBMSes, mostly due to poor simulation by us
 393                 $dbw->replace( 'watchlist', array( array( 'wl_user', 'wl_namespace', 'wl_title' ) ), $values, __METHOD__ );
 394                 return true;
 395         }
 396 }