[Summary view] [Print] [Text view]

   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  }