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