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