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         /** Helper to retrieve the title namespace */
  74         protected function getTitleNs() {
  75                 return $this->getTitle()->getNamespace();
  76         }
  77
  78         /** Helper to retrieve the title DBkey */
  79         protected function getTitleDBkey() {
  80                 return $this->getTitle()->getDBkey();
  81         }
  82         /** Helper to retrieve the user id */
  83         protected function getUserId() {
  84                 return $this->mUser->getId();
  85         }
  86
  87         /**
  88          * Return an array of conditions to select or update the appropriate database
  89          * row.
  90          *
  91          * @return array
  92          */
  93         private function dbCond() {
  94                 return array(
  95                         'wl_user' => $this->getUserId(),
  96                         'wl_namespace' => $this->getTitleNs(),
  97                         'wl_title' => $this->getTitleDBkey(),
  98                 );
  99         }
 100
 101         /**
 102          * Load the object from the database
 103          */
 104         private function load() {
 105                 if ( $this->loaded ) {
 106                         return;
 107                 }
 108                 $this->loaded = true;
 109
 110                 // Only loggedin user can have a watchlist
 111                 if ( $this->mUser->isAnon() ) {
 112                         $this->watched = false;
 113                         return;
 114                 }
 115
 116                 # Pages and their talk pages are considered equivalent for watching;
 117                 # remember that talk namespaces are numbered as page namespace+1.
 118
 119                 $dbr = wfGetDB( DB_SLAVE );
 120                 $row = $dbr->selectRow( 'watchlist', 'wl_notificationtimestamp',
 121                         $this->dbCond(), __METHOD__ );
 122
 123                 if ( $row === false ) {
 124                         $this->watched = false;
 125                 } else {
 126                         $this->watched = true;
 127                         $this->timestamp = $row->wl_notificationtimestamp;
 128                 }
 129         }
 130
 131         /**
 132          * Check permissions
 133          * @param $what string: 'viewmywatchlist' or 'editmywatchlist'
 134          */
 135         private function isAllowed( $what ) {
 136                 return !$this->mCheckRights || $this->mUser->isAllowed( $what );
 137         }
 138
 139         /**
 140          * Is mTitle being watched by mUser?
 141          * @return bool
 142          */
 143         public function isWatched() {
 144                 if ( !$this->isAllowed( 'viewmywatchlist' ) ) {
 145                         return false;
 146                 }
 147
 148                 $this->load();
 149                 return $this->watched;
 150         }
 151
 152         /**
 153          * Get the notification timestamp of this entry.
 154          *
 155          * @return false|null|string: false if the page is not watched, the value of
 156          *         the wl_notificationtimestamp field otherwise
 157          */
 158         public function getNotificationTimestamp() {
 159                 if ( !$this->isAllowed( 'viewmywatchlist' ) ) {
 160                         return false;
 161                 }
 162
 163                 $this->load();
 164                 if ( $this->watched ) {
 165                         return $this->timestamp;
 166                 } else {
 167                         return false;
 168                 }
 169         }
 170
 171         /**
 172          * Reset the notification timestamp of this entry
 173          *
 174          * @param $force Whether to force the write query to be executed even if the
 175          *        page is not watched or the notification timestamp is already NULL.
 176          */
 177         public function resetNotificationTimestamp( $force = '' ) {
 178                 // Only loggedin user can have a watchlist
 179                 if ( wfReadOnly() || $this->mUser->isAnon() || !$this->isAllowed( 'editmywatchlist' ) ) {
 180                         return;
 181                 }
 182
 183                 if ( $force != 'force' ) {
 184                         $this->load();
 185                         if ( !$this->watched || $this->timestamp === null ) {
 186                                 return;
 187                         }
 188                 }
 189
 190                 // If the page is watched by the user (or may be watched), update the timestamp on any
 191                 // any matching rows
 192                 $dbw = wfGetDB( DB_MASTER );
 193                 $dbw->update( 'watchlist', array( 'wl_notificationtimestamp' => null ),
 194                         $this->dbCond(), __METHOD__ );
 195                 $this->timestamp = null;
 196         }
 197
 198         /**
 199          * Given a title and user (assumes the object is setup), add the watch to the
 200          * database.
 201          * @return bool
 202          */
 203         public function addWatch() {
 204                 wfProfileIn( __METHOD__ );
 205
 206                 // Only loggedin user can have a watchlist
 207                 if ( wfReadOnly() || $this->mUser->isAnon() || !$this->isAllowed( 'editmywatchlist' ) ) {
 208                         wfProfileOut( __METHOD__ );
 209                         return false;
 210                 }
 211
 212                 // Use INSERT IGNORE to avoid overwriting the notification timestamp
 213                 // if there's already an entry for this page
 214                 $dbw = wfGetDB( DB_MASTER );
 215                 $dbw->insert( 'watchlist',
 216                         array(
 217                                 'wl_user' => $this->getUserId(),
 218                                 'wl_namespace' => MWNamespace::getSubject( $this->getTitleNs() ),
 219                                 'wl_title' => $this->getTitleDBkey(),
 220                                 'wl_notificationtimestamp' => null
 221                         ), __METHOD__, 'IGNORE' );
 222
 223                 // Every single watched page needs now to be listed in watchlist;
 224                 // namespace:page and namespace_talk:page need separate entries:
 225                 $dbw->insert( 'watchlist',
 226                         array(
 227                                 'wl_user' => $this->getUserId(),
 228                                 'wl_namespace' => MWNamespace::getTalk( $this->getTitleNs() ),
 229                                 'wl_title' => $this->getTitleDBkey(),
 230                                 'wl_notificationtimestamp' => null
 231                         ), __METHOD__, 'IGNORE' );
 232
 233                 $this->watched = true;
 234
 235                 wfProfileOut( __METHOD__ );
 236                 return true;
 237         }
 238
 239         /**
 240          * Same as addWatch, only the opposite.
 241          * @return bool
 242          */
 243         public function removeWatch() {
 244                 wfProfileIn( __METHOD__ );
 245
 246                 // Only loggedin user can have a watchlist
 247                 if ( wfReadOnly() || $this->mUser->isAnon() || !$this->isAllowed( 'editmywatchlist' ) ) {
 248                         wfProfileOut( __METHOD__ );
 249                         return false;
 250                 }
 251
 252                 $success = false;
 253                 $dbw = wfGetDB( DB_MASTER );
 254                 $dbw->delete( 'watchlist',
 255                         array(
 256                                 'wl_user' => $this->getUserId(),
 257                                 'wl_namespace' => MWNamespace::getSubject( $this->getTitleNs() ),
 258                                 'wl_title' => $this->getTitleDBkey(),
 259                         ), __METHOD__
 260                 );
 261                 if ( $dbw->affectedRows() ) {
 262                         $success = true;
 263                 }
 264
 265                 # the following code compensates the new behavior, introduced by the
 266                 # enotif patch, that every single watched page needs now to be listed
 267                 # in watchlist namespace:page and namespace_talk:page had separate
 268                 # entries: clear them
 269                 $dbw->delete( 'watchlist',
 270                         array(
 271                                 'wl_user' => $this->getUserId(),
 272                                 'wl_namespace' => MWNamespace::getTalk( $this->getTitleNs() ),
 273                                 'wl_title' => $this->getTitleDBkey(),
 274                         ), __METHOD__
 275                 );
 276
 277                 if ( $dbw->affectedRows() ) {
 278                         $success = true;
 279                 }
 280
 281                 $this->watched = false;
 282
 283                 wfProfileOut( __METHOD__ );
 284                 return $success;
 285         }
 286
 287         /**
 288          * Check if the given title already is watched by the user, and if so
 289          * add watches on a new title. To be used for page renames and such.
 290          *
 291          * @param $ot Title: page title to duplicate entries from, if present
 292          * @param $nt Title: page title to add watches on
 293          */
 294         public static function duplicateEntries( $ot, $nt ) {
 295                 WatchedItem::doDuplicateEntries( $ot->getSubjectPage(), $nt->getSubjectPage() );
 296                 WatchedItem::doDuplicateEntries( $ot->getTalkPage(), $nt->getTalkPage() );
 297         }
 298
 299         /**
 300          * Handle duplicate entries. Backend for duplicateEntries().
 301          *
 302          * @param $ot Title
 303          * @param $nt Title
 304          *
 305          * @return bool
 306          */
 307         private static function doDuplicateEntries( $ot, $nt ) {
 308                 $oldnamespace = $ot->getNamespace();
 309                 $newnamespace = $nt->getNamespace();
 310                 $oldtitle = $ot->getDBkey();
 311                 $newtitle = $nt->getDBkey();
 312
 313                 $dbw = wfGetDB( DB_MASTER );
 314                 $res = $dbw->select( 'watchlist', 'wl_user',
 315                         array( 'wl_namespace' => $oldnamespace, 'wl_title' => $oldtitle ),
 316                         __METHOD__, 'FOR UPDATE'
 317                 );
 318                 # Construct array to replace into the watchlist
 319                 $values = array();
 320                 foreach ( $res as $s ) {
 321                         $values[] = array(
 322                                 'wl_user' => $s->wl_user,
 323                                 'wl_namespace' => $newnamespace,
 324                                 'wl_title' => $newtitle
 325                         );
 326                 }
 327
 328                 if ( empty( $values ) ) {
 329                         // Nothing to do
 330                         return true;
 331                 }
 332
 333                 # Perform replace
 334                 # Note that multi-row replace is very efficient for MySQL but may be inefficient for
 335                 # some other DBMSes, mostly due to poor simulation by us
 336                 $dbw->replace( 'watchlist', array( array( 'wl_user', 'wl_namespace', 'wl_title' ) ), $values, __METHOD__ );
 337                 return true;
 338         }
 339 }