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