includes/api/ApiSetNotificationTimestamp.php

   1 <?php
   2
   3 /**
   4  * API for MediaWiki 1.14+
   5  *
   6  * Created on Jun 18, 2012
   7  *
   8  * Copyright © 2012 Brad Jorsch
   9  *
  10  * This program is free software; you can redistribute it and/or modify
  11  * it under the terms of the GNU General Public License as published by
  12  * the Free Software Foundation; either version 2 of the License, or
  13  * (at your option) any later version.
  14  *
  15  * This program is distributed in the hope that it will be useful,
  16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  18  * GNU General Public License for more details.
  19  *
  20  * You should have received a copy of the GNU General Public License along
  21  * with this program; if not, write to the Free Software Foundation, Inc.,
  22  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  23  * http://www.gnu.org/copyleft/gpl.html
  24  *
  25  * @file
  26  */
  27
  28 /**
  29  * API interface for setting the wl_notificationtimestamp field
  30  * @ingroup API
  31  */
  32 class ApiSetNotificationTimestamp extends ApiBase {
  33
  34         private $mPageSet;
  35
  36         public function execute() {
  37                 $user = $this->getUser();
  38
  39                 if ( $user->isAnon() ) {
  40                         $this->dieUsage( 'Anonymous users cannot use watchlist change notifications', 'notloggedin' );
  41                 }
  42                 if ( !$user->isAllowed( 'editmywatchlist' ) ) {
  43                         $this->dieUsage( 'You don\'t have permission to edit your watchlist', 'permissiondenied' );
  44                 }
  45
  46                 $params = $this->extractRequestParams();
  47                 $this->requireMaxOneParameter( $params, 'timestamp', 'torevid', 'newerthanrevid' );
  48
  49                 $this->getResult()->beginContinuation( $params['continue'], array(), array() );
  50
  51                 $pageSet = $this->getPageSet();
  52                 if ( $params['entirewatchlist'] && $pageSet->getDataSource() !== null ) {
  53                         $this->dieUsage(
  54                                 "Cannot use 'entirewatchlist' at the same time as '{$pageSet->getDataSource()}'",
  55                                 'multisource'
  56                         );
  57                 }
  58
  59                 $dbw = wfGetDB( DB_MASTER, 'api' );
  60
  61                 $timestamp = null;
  62                 if ( isset( $params['timestamp'] ) ) {
  63                         $timestamp = $dbw->timestamp( $params['timestamp'] );
  64                 }
  65
  66                 if ( !$params['entirewatchlist'] ) {
  67                         $pageSet->execute();
  68                 }
  69
  70                 if ( isset( $params['torevid'] ) ) {
  71                         if ( $params['entirewatchlist'] || $pageSet->getGoodTitleCount() > 1 ) {
  72                                 $this->dieUsage( 'torevid may only be used with a single page', 'multpages' );
  73                         }
  74                         $title = reset( $pageSet->getGoodTitles() );
  75                         if ( $title ) {
  76                                 $timestamp = Revision::getTimestampFromId( $title, $params['torevid'] );
  77                                 if ( $timestamp ) {
  78                                         $timestamp = $dbw->timestamp( $timestamp );
  79                                 } else {
  80                                         $timestamp = null;
  81                                 }
  82                         }
  83                 } elseif ( isset( $params['newerthanrevid'] ) ) {
  84                         if ( $params['entirewatchlist'] || $pageSet->getGoodTitleCount() > 1 ) {
  85                                 $this->dieUsage( 'newerthanrevid may only be used with a single page', 'multpages' );
  86                         }
  87                         $title = reset( $pageSet->getGoodTitles() );
  88                         if ( $title ) {
  89                                 $revid = $title->getNextRevisionID( $params['newerthanrevid'] );
  90                                 if ( $revid ) {
  91                                         $timestamp = $dbw->timestamp( Revision::getTimestampFromId( $title, $revid ) );
  92                                 } else {
  93                                         $timestamp = null;
  94                                 }
  95                         }
  96                 }
  97
  98                 $apiResult = $this->getResult();
  99                 $result = array();
 100                 if ( $params['entirewatchlist'] ) {
 101                         // Entire watchlist mode: Just update the thing and return a success indicator
 102                         $dbw->update( 'watchlist', array( 'wl_notificationtimestamp' => $timestamp ),
 103                                 array( 'wl_user' => $user->getID() ),
 104                                 __METHOD__
 105                         );
 106
 107                         $result['notificationtimestamp'] = is_null( $timestamp )
 108                                 ? ''
 109                                 : wfTimestamp( TS_ISO_8601, $timestamp );
 110                 } else {
 111                         // First, log the invalid titles
 112                         foreach ( $pageSet->getInvalidTitles() as $title ) {
 113                                 $r = array();
 114                                 $r['title'] = $title;
 115                                 $r['invalid'] = '';
 116                                 $result[] = $r;
 117                         }
 118                         foreach ( $pageSet->getMissingPageIDs() as $p ) {
 119                                 $page = array();
 120                                 $page['pageid'] = $p;
 121                                 $page['missing'] = '';
 122                                 $page['notwatched'] = '';
 123                                 $result[] = $page;
 124                         }
 125                         foreach ( $pageSet->getMissingRevisionIDs() as $r ) {
 126                                 $rev = array();
 127                                 $rev['revid'] = $r;
 128                                 $rev['missing'] = '';
 129                                 $rev['notwatched'] = '';
 130                                 $result[] = $rev;
 131                         }
 132
 133                         if ( $pageSet->getTitles() ) {
 134                                 // Now process the valid titles
 135                                 $lb = new LinkBatch( $pageSet->getTitles() );
 136                                 $dbw->update( 'watchlist', array( 'wl_notificationtimestamp' => $timestamp ),
 137                                         array( 'wl_user' => $user->getID(), $lb->constructSet( 'wl', $dbw ) ),
 138                                         __METHOD__
 139                                 );
 140
 141                                 // Query the results of our update
 142                                 $timestamps = array();
 143                                 $res = $dbw->select(
 144                                         'watchlist',
 145                                         array( 'wl_namespace', 'wl_title', 'wl_notificationtimestamp' ),
 146                                         array( 'wl_user' => $user->getID(), $lb->constructSet( 'wl', $dbw ) ),
 147                                         __METHOD__
 148                                 );
 149                                 foreach ( $res as $row ) {
 150                                         $timestamps[$row->wl_namespace][$row->wl_title] = $row->wl_notificationtimestamp;
 151                                 }
 152
 153                                 // Now, put the valid titles into the result
 154                                 /** @var $title Title */
 155                                 foreach ( $pageSet->getTitles() as $title ) {
 156                                         $ns = $title->getNamespace();
 157                                         $dbkey = $title->getDBkey();
 158                                         $r = array(
 159                                                 'ns' => intval( $ns ),
 160                                                 'title' => $title->getPrefixedText(),
 161                                         );
 162                                         if ( !$title->exists() ) {
 163                                                 $r['missing'] = '';
 164                                         }
 165                                         if ( isset( $timestamps[$ns] ) && array_key_exists( $dbkey, $timestamps[$ns] ) ) {
 166                                                 $r['notificationtimestamp'] = '';
 167                                                 if ( $timestamps[$ns][$dbkey] !== null ) {
 168                                                         $r['notificationtimestamp'] = wfTimestamp( TS_ISO_8601, $timestamps[$ns][$dbkey] );
 169                                                 }
 170                                         } else {
 171                                                 $r['notwatched'] = '';
 172                                         }
 173                                         $result[] = $r;
 174                                 }
 175                         }
 176
 177                         $apiResult->setIndexedTagName( $result, 'page' );
 178                 }
 179                 $apiResult->addValue( null, $this->getModuleName(), $result );
 180
 181                 $apiResult->endContinuation();
 182         }
 183
 184         /**
 185          * Get a cached instance of an ApiPageSet object
 186          * @return ApiPageSet
 187          */
 188         private function getPageSet() {
 189                 if ( !isset( $this->mPageSet ) ) {
 190                         $this->mPageSet = new ApiPageSet( $this );
 191                 }
 192
 193                 return $this->mPageSet;
 194         }
 195
 196         public function mustBePosted() {
 197                 return true;
 198         }
 199
 200         public function isWriteMode() {
 201                 return true;
 202         }
 203
 204         public function needsToken() {
 205                 return 'csrf';
 206         }
 207
 208         public function getAllowedParams( $flags = 0 ) {
 209                 $result = array(
 210                         'entirewatchlist' => array(
 211                                 ApiBase::PARAM_TYPE => 'boolean'
 212                         ),
 213                         'timestamp' => array(
 214                                 ApiBase::PARAM_TYPE => 'timestamp'
 215                         ),
 216                         'torevid' => array(
 217                                 ApiBase::PARAM_TYPE => 'integer'
 218                         ),
 219                         'newerthanrevid' => array(
 220                                 ApiBase::PARAM_TYPE => 'integer'
 221                         ),
 222                         'continue' => '',
 223                 );
 224                 if ( $flags ) {
 225                         $result += $this->getPageSet()->getFinalParams( $flags );
 226                 }
 227
 228                 return $result;
 229         }
 230
 231         public function getParamDescription() {
 232                 return $this->getPageSet()->getFinalParamDescription() + array(
 233                         'entirewatchlist' => 'Work on all watched pages',
 234                         'timestamp' => 'Timestamp to which to set the notification timestamp',
 235                         'torevid' => 'Revision to set the notification timestamp to (one page only)',
 236                         'newerthanrevid' => 'Revision to set the notification timestamp newer than (one page only)',
 237                         'continue' => 'When more results are available, use this to continue',
 238                 );
 239         }
 240
 241         public function getDescription() {
 242                 return array( 'Update the notification timestamp for watched pages.',
 243                         'This affects the highlighting of changed pages in the watchlist and history,',
 244                         'and the sending of email when the "Email me when a page on my watchlist is',
 245                         'changed" preference is enabled.'
 246                 );
 247         }
 248
 249         public function getExamples() {
 250                 return array(
 251                         'api.php?action=setnotificationtimestamp&entirewatchlist=&token=123ABC'
 252                                 => 'Reset the notification status for the entire watchlist',
 253                         'api.php?action=setnotificationtimestamp&titles=Main_page&token=123ABC'
 254                                 => 'Reset the notification status for "Main page"',
 255                         'api.php?action=setnotificationtimestamp&titles=Main_page&' .
 256                                 'timestamp=2012-01-01T00:00:00Z&token=123ABC'
 257                                 => 'Set the notification timestamp for "Main page" so all edits ' .
 258                                         'since 1 January 2012 are unviewed',
 259                 );
 260         }
 261
 262         public function getHelpUrls() {
 263                 return 'https://www.mediawiki.org/wiki/API:SetNotificationTimestamp';
 264         }
 265 }