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