5 * Created on Jan 4, 2008
7 * Copyright © 2008 Yuri Astrakhan "<Firstname><Lastname>@gmail.com",
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.
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.
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
28 * API module to allow users to watch a page
32 class ApiWatch
extends ApiBase
{
33 private $mPageSet = null;
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' );
41 if ( !$user->isAllowed( 'editmywatchlist' ) ) {
42 $this->dieUsage( 'You don\'t have permission to edit your watchlist', 'permissiondenied' );
45 $params = $this->extractRequestParams();
46 $pageSet = $this->getPageSet();
47 // by default we use pageset to extract the page to work on.
48 // title is still supported for backward compatibility
49 if ( !isset( $params['title'] ) ) {
51 $res = $pageSet->getInvalidTitlesAndRevisions( array( 'invalidTitles', 'special', 'missingIds', 'missingRevIds', 'interwikiTitles' ) );
52 foreach ( $pageSet->getMissingTitles() as $title ) {
53 $r = $this->watchTitle( $title, $user, $params );
57 foreach ( $pageSet->getGoodTitles() as $title ) {
58 $r = $this->watchTitle( $title, $user, $params );
61 $this->getResult()->setIndexedTagName( $res, 'w' );
63 // dont allow use of old title parameter with new pageset parameters.
64 $extraParams = array_keys( array_filter( $pageSet->extractRequestParams(), function ( $x ) {
65 return $x !== null && $x !== false;
68 $p = $this->getModulePrefix();
69 $this->dieUsage( "The parameter {$p}title can not be used with ". implode( ", ", $extraParams ), 'invalidparammix' );
72 $title = Title
::newFromText( $params['title'] );
73 if ( !$title ||
!$title->isWatchable() ) {
74 $this->dieUsageMsg( array( 'invalidtitle', $params['title'] ) );
76 $res = $this->watchTitle( $title, $user, $params, true );
78 $this->getResult()->addValue( null, $this->getModuleName(), $res );
81 private function watchTitle( Title
$title, User
$user, array $params, $compatibilityMode = false ) {
82 if ( !$title->isWatchable() ) {
83 return array( 'title' => $title->getPrefixedText(), 'watchable' => 0 );
86 $res = array( 'title' => $title->getPrefixedText() );
88 // Currently unnecessary, code to act as a safeguard against any change
89 // in current behavior of uselang.
92 if ( isset( $params['uselang'] ) &&
93 $params['uselang'] != $this->getContext()->getLanguage()->getCode()
95 $oldLang = $this->getContext()->getLanguage(); // Backup language
96 $this->getContext()->setLanguage( Language
::factory( $params['uselang'] ) );
99 if ( $params['unwatch'] ) {
100 $status = UnwatchAction
::doUnwatch( $title, $user );
101 if ( $status->isOK() ) {
102 $res['unwatched'] = '';
103 $res['message'] = $this->msg( 'removedwatchtext', $title->getPrefixedText() )
104 ->title( $title )->parseAsBlock();
107 $status = WatchAction
::doWatch( $title, $user );
108 if ( $status->isOK() ) {
109 $res['watched'] = '';
110 $res['message'] = $this->msg( 'addedwatchtext', $title->getPrefixedText() )
111 ->title( $title )->parseAsBlock();
115 if ( !is_null( $oldLang ) ) {
116 $this->getContext()->setLanguage( $oldLang ); // Reset language to $oldLang
120 if ( !$status->isOK() ) {
121 if ( $compatibilityMode ) {
122 $this->dieStatus( $status );
124 $res['error'] = $this->getErrorFromStatus( $status );
131 * Get a cached instance of an ApiPageSet object
134 private function getPageSet() {
135 if ( $this->mPageSet
=== null ) {
136 $this->mPageSet
= new ApiPageSet( $this );
138 return $this->mPageSet
;
141 public function mustBePosted() {
145 public function isWriteMode() {
149 public function needsToken() {
153 public function getTokenSalt() {
157 public function getAllowedParams( $flags = 0 ) {
160 ApiBase
::PARAM_TYPE
=> 'string',
161 ApiBase
::PARAM_DEPRECATED
=> true
166 ApiBase
::PARAM_TYPE
=> 'string',
167 ApiBase
::PARAM_REQUIRED
=> true
171 $result +
= $this->getPageSet()->getFinalParams( $flags );
176 public function getParamDescription() {
177 $psModule = $this->getPageSet();
178 return $psModule->getParamDescription() +
array(
179 'title' => 'The page to (un)watch. use titles instead',
180 'unwatch' => 'If set the page will be unwatched rather than watched',
181 'uselang' => 'Language to show the message in',
182 'token' => 'A token previously acquired via prop=info',
186 public function getResultProperties() {
190 'unwatched' => 'boolean',
191 'watched' => 'boolean',
192 'message' => 'string'
197 public function getDescription() {
198 return 'Add or remove pages from/to the current user\'s watchlist';
201 public function getPossibleErrors() {
202 return array_merge( parent
::getPossibleErrors(), array(
203 array( 'code' => 'notloggedin', 'info' => 'You must be logged-in to have a watchlist' ),
204 array( 'invalidtitle', 'title' ),
205 array( 'hookaborted' ),
209 public function getExamples() {
211 'api.php?action=watch&titles=Main_Page' => 'Watch the page "Main Page"',
212 'api.php?action=watch&titles=Main_Page&unwatch=' => 'Unwatch the page "Main Page"',
216 public function getHelpUrls() {
217 return 'https://www.mediawiki.org/wiki/API:Watch';