[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   *
   4   *
   5   * Created on Jan 4, 2008
   6   *
   7   * Copyright © 2008 Yuri Astrakhan "<Firstname><Lastname>@gmail.com",
   8   *
   9   * This program is free software; you can redistribute it and/or modify
  10   * it under the terms of the GNU General Public License as published by
  11   * the Free Software Foundation; either version 2 of the License, or
  12   * (at your option) any later version.
  13   *
  14   * This program is distributed in the hope that it will be useful,
  15   * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  17   * GNU General Public License for more details.
  18   *
  19   * You should have received a copy of the GNU General Public License along
  20   * with this program; if not, write to the Free Software Foundation, Inc.,
  21   * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  22   * http://www.gnu.org/copyleft/gpl.html
  23   *
  24   * @file
  25   */
  26  
  27  /**
  28   * API module to allow users to watch a page
  29   *
  30   * @ingroup API
  31   */
  32  class ApiWatch extends ApiBase {
  33      private $mPageSet = null;
  34  
  35  	public function execute() {
  36          $user = $this->getUser();
  37          if ( !$user->isLoggedIn() ) {
  38              $this->dieUsage( 'You must be logged-in to have a watchlist', 'notloggedin' );
  39          }
  40  
  41          if ( !$user->isAllowed( 'editmywatchlist' ) ) {
  42              $this->dieUsage( 'You don\'t have permission to edit your watchlist', 'permissiondenied' );
  43          }
  44  
  45          $params = $this->extractRequestParams();
  46  
  47          $this->getResult()->beginContinuation( $params['continue'], array(), array() );
  48  
  49          $pageSet = $this->getPageSet();
  50          // by default we use pageset to extract the page to work on.
  51          // title is still supported for backward compatibility
  52          if ( !isset( $params['title'] ) ) {
  53              $pageSet->execute();
  54              $res = $pageSet->getInvalidTitlesAndRevisions( array(
  55                  'invalidTitles',
  56                  'special',
  57                  'missingIds',
  58                  'missingRevIds',
  59                  'interwikiTitles'
  60              ) );
  61  
  62              foreach ( $pageSet->getMissingTitles() as $title ) {
  63                  $r = $this->watchTitle( $title, $user, $params );
  64                  $r['missing'] = 1;
  65                  $res[] = $r;
  66              }
  67  
  68              foreach ( $pageSet->getGoodTitles() as $title ) {
  69                  $r = $this->watchTitle( $title, $user, $params );
  70                  $res[] = $r;
  71              }
  72              $this->getResult()->setIndexedTagName( $res, 'w' );
  73          } else {
  74              // dont allow use of old title parameter with new pageset parameters.
  75              $extraParams = array_keys( array_filter( $pageSet->extractRequestParams(), function ( $x ) {
  76                  return $x !== null && $x !== false;
  77              } ) );
  78  
  79              if ( $extraParams ) {
  80                  $p = $this->getModulePrefix();
  81                  $this->dieUsage(
  82                      "The parameter {$p}title can not be used with " . implode( ", ", $extraParams ),
  83                      'invalidparammix'
  84                  );
  85              }
  86  
  87              $this->logFeatureUsage( 'action=watch&title' );
  88              $title = Title::newFromText( $params['title'] );
  89              if ( !$title || !$title->isWatchable() ) {
  90                  $this->dieUsageMsg( array( 'invalidtitle', $params['title'] ) );
  91              }
  92              $res = $this->watchTitle( $title, $user, $params, true );
  93          }
  94          $this->getResult()->addValue( null, $this->getModuleName(), $res );
  95          $this->getResult()->endContinuation();
  96      }
  97  
  98  	private function watchTitle( Title $title, User $user, array $params,
  99          $compatibilityMode = false
 100      ) {
 101          if ( !$title->isWatchable() ) {
 102              return array( 'title' => $title->getPrefixedText(), 'watchable' => 0 );
 103          }
 104  
 105          $res = array( 'title' => $title->getPrefixedText() );
 106  
 107          // Currently unnecessary, code to act as a safeguard against any change
 108          // in current behavior of uselang.
 109          // Copy from ApiParse
 110          $oldLang = null;
 111          if ( isset( $params['uselang'] ) &&
 112              $params['uselang'] != $this->getContext()->getLanguage()->getCode()
 113          ) {
 114              $oldLang = $this->getContext()->getLanguage(); // Backup language
 115              $this->getContext()->setLanguage( Language::factory( $params['uselang'] ) );
 116          }
 117  
 118          if ( $params['unwatch'] ) {
 119              $status = UnwatchAction::doUnwatch( $title, $user );
 120              if ( $status->isOK() ) {
 121                  $res['unwatched'] = '';
 122                  $res['message'] = $this->msg( 'removedwatchtext', $title->getPrefixedText() )
 123                      ->title( $title )->parseAsBlock();
 124              }
 125          } else {
 126              $status = WatchAction::doWatch( $title, $user );
 127              if ( $status->isOK() ) {
 128                  $res['watched'] = '';
 129                  $res['message'] = $this->msg( 'addedwatchtext', $title->getPrefixedText() )
 130                      ->title( $title )->parseAsBlock();
 131              }
 132          }
 133  
 134          if ( !is_null( $oldLang ) ) {
 135              $this->getContext()->setLanguage( $oldLang ); // Reset language to $oldLang
 136          }
 137  
 138          if ( !$status->isOK() ) {
 139              if ( $compatibilityMode ) {
 140                  $this->dieStatus( $status );
 141              }
 142              $res['error'] = $this->getErrorFromStatus( $status );
 143          }
 144  
 145          return $res;
 146      }
 147  
 148      /**
 149       * Get a cached instance of an ApiPageSet object
 150       * @return ApiPageSet
 151       */
 152  	private function getPageSet() {
 153          if ( $this->mPageSet === null ) {
 154              $this->mPageSet = new ApiPageSet( $this );
 155          }
 156  
 157          return $this->mPageSet;
 158      }
 159  
 160  	public function mustBePosted() {
 161          return true;
 162      }
 163  
 164  	public function isWriteMode() {
 165          return true;
 166      }
 167  
 168  	public function needsToken() {
 169          return 'watch';
 170      }
 171  
 172  	public function getAllowedParams( $flags = 0 ) {
 173          $result = array(
 174              'title' => array(
 175                  ApiBase::PARAM_TYPE => 'string',
 176                  ApiBase::PARAM_DEPRECATED => true
 177              ),
 178              'unwatch' => false,
 179              'uselang' => null,
 180              'continue' => '',
 181          );
 182          if ( $flags ) {
 183              $result += $this->getPageSet()->getFinalParams( $flags );
 184          }
 185  
 186          return $result;
 187      }
 188  
 189  	public function getParamDescription() {
 190          $psModule = $this->getPageSet();
 191  
 192          return $psModule->getParamDescription() + array(
 193              'title' => 'The page to (un)watch. use titles instead',
 194              'unwatch' => 'If set the page will be unwatched rather than watched',
 195              'uselang' => 'Language to show the message in',
 196              'continue' => 'When more results are available, use this to continue',
 197          );
 198      }
 199  
 200  	public function getDescription() {
 201          return 'Add or remove pages from/to the current user\'s watchlist.';
 202      }
 203  
 204  	public function getExamples() {
 205          return array(
 206              'api.php?action=watch&titles=Main_Page' => 'Watch the page "Main Page"',
 207              'api.php?action=watch&titles=Main_Page&unwatch=' => 'Unwatch the page "Main Page"',
 208          );
 209      }
 210  
 211  	public function getHelpUrls() {
 212          return 'https://www.mediawiki.org/wiki/API:Watch';
 213      }
 214  }