MediaWiki  master
ApiWatch.php
Go to the documentation of this file.
1 <?php
26 
32 class ApiWatch extends ApiBase {
33  private $mPageSet = null;
34 
36  private $expiryEnabled;
37 
39  private $maxDuration;
40 
42  protected $watchlistManager;
43 
44  public function __construct( ApiMain $mainModule, $moduleName, WatchlistManager $watchlistManager ) {
45  parent::__construct( $mainModule, $moduleName );
46 
47  $this->watchlistManager = $watchlistManager;
48  $this->expiryEnabled = $this->getConfig()->get( 'WatchlistExpiry' );
49  $this->maxDuration = $this->getConfig()->get( 'WatchlistExpiryMaxDuration' );
50  }
51 
52  public function execute() {
53  $user = $this->getUser();
54  if ( !$user->isRegistered() ) {
55  $this->dieWithError( 'watchlistanontext', 'notloggedin' );
56  }
57 
58  $this->checkUserRightsAny( 'editmywatchlist' );
59 
60  $params = $this->extractRequestParams();
61 
62  $continuationManager = new ApiContinuationManager( $this, [], [] );
63  $this->setContinuationManager( $continuationManager );
64 
65  $pageSet = $this->getPageSet();
66  // by default we use pageset to extract the page to work on.
67  // title is still supported for backward compatibility
68  if ( !isset( $params['title'] ) ) {
69  $pageSet->execute();
70  $res = $pageSet->getInvalidTitlesAndRevisions( [
71  'invalidTitles',
72  'special',
73  'missingIds',
74  'missingRevIds',
75  'interwikiTitles'
76  ] );
77 
78  foreach ( $pageSet->getMissingTitles() as $title ) {
79  $r = $this->watchTitle( $title, $user, $params );
80  $r['missing'] = true;
81  $res[] = $r;
82  }
83 
84  foreach ( $pageSet->getGoodTitles() as $title ) {
85  $r = $this->watchTitle( $title, $user, $params );
86  $res[] = $r;
87  }
89  } else {
90  // dont allow use of old title parameter with new pageset parameters.
91  $extraParams = array_keys( array_filter( $pageSet->extractRequestParams(), static function ( $x ) {
92  return $x !== null && $x !== false;
93  } ) );
94 
95  if ( $extraParams ) {
96  $this->dieWithError(
97  [
98  'apierror-invalidparammix-cannotusewith',
99  $this->encodeParamName( 'title' ),
100  $pageSet->encodeParamName( $extraParams[0] )
101  ],
102  'invalidparammix'
103  );
104  }
105 
106  $title = Title::newFromText( $params['title'] );
107  if ( !$title || !$this->watchlistManager->isWatchable( $title ) ) {
108  $this->dieWithError( [ 'invalidtitle', $params['title'] ] );
109  }
110  $res = $this->watchTitle( $title, $user, $params, true );
111  }
112  $this->getResult()->addValue( null, $this->getModuleName(), $res );
113 
114  $this->setContinuationManager( null );
115  $continuationManager->setContinuationIntoResult( $this->getResult() );
116  }
117 
118  private function watchTitle( Title $title, User $user, array $params,
119  $compatibilityMode = false
120  ) {
121  $res = [ 'title' => $title->getPrefixedText(), 'ns' => $title->getNamespace() ];
122 
123  if ( !$this->watchlistManager->isWatchable( $title ) ) {
124  $res['watchable'] = 0;
125  return $res;
126  }
127 
128  if ( $params['unwatch'] ) {
129  $status = $this->watchlistManager->removeWatch( $user, $title );
130  $res['unwatched'] = $status->isOK();
131  } else {
132  $expiry = null;
133 
134  // NOTE: If an expiry parameter isn't given, any existing expiries remain unchanged.
135  if ( $this->expiryEnabled && isset( $params['expiry'] ) ) {
136  $expiry = $params['expiry'];
137  $res['expiry'] = ApiResult::formatExpiry( $expiry );
138  }
139 
140  $status = $this->watchlistManager->addWatch( $user, $title, $expiry );
141  $res['watched'] = $status->isOK();
142  }
143 
144  if ( !$status->isOK() ) {
145  if ( $compatibilityMode ) {
146  $this->dieStatus( $status );
147  }
148  $res['errors'] = $this->getErrorFormatter()->arrayFromStatus( $status, 'error' );
149  $res['warnings'] = $this->getErrorFormatter()->arrayFromStatus( $status, 'warning' );
150  if ( !$res['warnings'] ) {
151  unset( $res['warnings'] );
152  }
153  }
154 
155  return $res;
156  }
157 
162  private function getPageSet() {
163  if ( $this->mPageSet === null ) {
164  $this->mPageSet = new ApiPageSet( $this );
165  }
166 
167  return $this->mPageSet;
168  }
169 
170  public function mustBePosted() {
171  return true;
172  }
173 
174  public function isWriteMode() {
175  return true;
176  }
177 
178  public function needsToken() {
179  return 'watch';
180  }
181 
182  public function getAllowedParams( $flags = 0 ) {
183  $result = [
184  'title' => [
185  ParamValidator::PARAM_TYPE => 'string',
186  ParamValidator::PARAM_DEPRECATED => true,
187  ],
188  'expiry' => [
189  ParamValidator::PARAM_TYPE => 'expiry',
190  ExpiryDef::PARAM_MAX => $this->maxDuration,
191  ExpiryDef::PARAM_USE_MAX => true,
192  ],
193  'unwatch' => false,
194  'continue' => [
195  ApiBase::PARAM_HELP_MSG => 'api-help-param-continue',
196  ],
197  ];
198 
199  // If expiry is not enabled, don't accept the parameter.
200  if ( !$this->expiryEnabled ) {
201  unset( $result['expiry'] );
202  }
203 
204  if ( $flags ) {
205  $result += $this->getPageSet()->getFinalParams( $flags );
206  }
207 
208  return $result;
209  }
210 
211  protected function getExamplesMessages() {
212  // Logically expiry example should go before unwatch examples.
213  $examples = [
214  'action=watch&titles=Main_Page&token=123ABC'
215  => 'apihelp-watch-example-watch',
216  ];
217  if ( $this->expiryEnabled ) {
218  $examples['action=watch&titles=Main_Page|Foo|Bar&expiry=1%20month&token=123ABC']
219  = 'apihelp-watch-example-watch-expiry';
220  }
221 
222  return array_merge( $examples, [
223  'action=watch&titles=Main_Page&unwatch=&token=123ABC'
224  => 'apihelp-watch-example-unwatch',
225  'action=watch&generator=allpages&gapnamespace=0&token=123ABC'
226  => 'apihelp-watch-example-generator',
227  ] );
228  }
229 
230  public function getHelpUrls() {
231  return 'https://www.mediawiki.org/wiki/Special:MyLanguage/API:Watch';
232  }
233 }
ApiWatch\$watchlistManager
WatchlistManager $watchlistManager
Definition: ApiWatch.php:42
ApiMain
This is the main API class, used for both external and internal processing.
Definition: ApiMain.php:49
ContextSource\getConfig
getConfig()
Definition: ContextSource.php:72
ApiWatch\__construct
__construct(ApiMain $mainModule, $moduleName, WatchlistManager $watchlistManager)
Definition: ApiWatch.php:44
Title\newFromText
static newFromText( $text, $defaultNamespace=NS_MAIN)
Create a new Title from text, such as what one would find in a link.
Definition: Title.php:395
ApiWatch\getPageSet
getPageSet()
Get a cached instance of an ApiPageSet object.
Definition: ApiWatch.php:162
ApiWatch\getHelpUrls
getHelpUrls()
Return links to more detailed help pages about the module.
Definition: ApiWatch.php:230
ApiWatch
API module to allow users to watch a page.
Definition: ApiWatch.php:32
ApiContinuationManager
This manages continuation state.
Definition: ApiContinuationManager.php:26
ApiBase\dieWithError
dieWithError( $msg, $code=null, $data=null, $httpCode=null)
Abort execution with an error.
Definition: ApiBase.php:1436
ApiBase\PARAM_HELP_MSG
const PARAM_HELP_MSG
(string|array|Message) Specify an alternative i18n documentation message for this parameter.
Definition: ApiBase.php:162
ApiWatch\$mPageSet
$mPageSet
Definition: ApiWatch.php:33
ApiBase\getResult
getResult()
Get the result object.
Definition: ApiBase.php:628
ApiBase\checkUserRightsAny
checkUserRightsAny( $rights, $user=null)
Helper function for permission-denied errors.
Definition: ApiBase.php:1545
ApiBase\setContinuationManager
setContinuationManager(ApiContinuationManager $manager=null)
Definition: ApiBase.php:672
$res
$res
Definition: testCompression.php:57
ContextSource\getUser
getUser()
Definition: ContextSource.php:136
ApiWatch\getAllowedParams
getAllowedParams( $flags=0)
Definition: ApiWatch.php:182
ApiPageSet
This class contains a list of pages that the client has requested.
Definition: ApiPageSet.php:45
ApiBase
This abstract class implements many basic API functions, and is the base of all API classes.
Definition: ApiBase.php:55
Wikimedia\ParamValidator\TypeDef\ExpiryDef
Type definition for expiry timestamps.
Definition: ExpiryDef.php:17
MediaWiki\Watchlist\WatchlistManager
WatchlistManager service.
Definition: WatchlistManager.php:52
ApiWatch\mustBePosted
mustBePosted()
Indicates whether this module must be called with a POST request.
Definition: ApiWatch.php:170
ApiWatch\execute
execute()
Evaluates the parameters, performs the requested query, and sets up the result.
Definition: ApiWatch.php:52
ApiBase\extractRequestParams
extractRequestParams( $options=[])
Using getAllowedParams(), this function makes an array of the values provided by the user,...
Definition: ApiBase.php:764
$title
$title
Definition: testCompression.php:38
ApiWatch\watchTitle
watchTitle(Title $title, User $user, array $params, $compatibilityMode=false)
Definition: ApiWatch.php:118
ApiWatch\$expiryEnabled
bool $expiryEnabled
Whether watchlist expiries are enabled.
Definition: ApiWatch.php:36
ApiResult\setIndexedTagName
static setIndexedTagName(array &$arr, $tag)
Set the tag name for numeric-keyed values in XML format.
Definition: ApiResult.php:603
ApiBase\encodeParamName
encodeParamName( $paramName)
This method mangles parameter name based on the prefix supplied to the constructor.
Definition: ApiBase.php:742
Title
Represents a title within MediaWiki.
Definition: Title.php:47
ApiWatch\isWriteMode
isWriteMode()
Indicates whether this module requires write mode.
Definition: ApiWatch.php:174
ApiWatch\needsToken
needsToken()
Returns the token type this module requires in order to execute.
Definition: ApiWatch.php:178
ApiBase\dieStatus
dieStatus(StatusValue $status)
Throw an ApiUsageException based on the Status object.
Definition: ApiBase.php:1499
ApiBase\getModuleName
getModuleName()
Get the name of the module being executed by this instance.
Definition: ApiBase.php:497
ApiResult\formatExpiry
static formatExpiry( $expiry, $infinity='infinity')
Format an expiry timestamp for API output.
Definition: ApiResult.php:1194
ApiWatch\$maxDuration
string $maxDuration
Relative maximum expiry.
Definition: ApiWatch.php:39
User
The User object encapsulates all of the user-specific settings (user_id, name, rights,...
Definition: User.php:67
ApiWatch\getExamplesMessages
getExamplesMessages()
Returns usage examples for this module.
Definition: ApiWatch.php:211
ApiBase\getErrorFormatter
getErrorFormatter()
Definition: ApiBase.php:639
Wikimedia\ParamValidator\ParamValidator
Service for formatting and validating API parameters.
Definition: ParamValidator.php:42