3 * Copyright © 2006 Yuri Astrakhan "<Firstname><Lastname>@gmail.com"
5 * This program is free software; you can redistribute it and/or modify
6 * it under the terms of the GNU General Public License as published by
7 * the Free Software Foundation; either version 2 of the License, or
8 * (at your option) any later version.
10 * This program is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 * GNU General Public License for more details.
15 * You should have received a copy of the GNU General Public License along
16 * with this program; if not, write to the Free Software Foundation, Inc.,
17 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
18 * http://www.gnu.org/copyleft/gpl.html
23 use MediaWiki\MediaWikiServices
;
24 use MediaWiki\Revision\RevisionRecord
;
27 * This query action allows clients to retrieve a list of recently modified pages
28 * that are part of the logged-in user's watchlist.
32 class ApiQueryWatchlist
extends ApiQueryGeneratorBase
{
34 /** @var CommentStore */
35 private $commentStore;
37 public function __construct( ApiQuery
$query, $moduleName ) {
38 parent
::__construct( $query, $moduleName, 'wl' );
41 public function execute() {
45 public function executeGenerator( $resultPageSet ) {
46 $this->run( $resultPageSet );
49 private $fld_ids = false, $fld_title = false, $fld_patrol = false,
50 $fld_flags = false, $fld_timestamp = false, $fld_user = false,
51 $fld_comment = false, $fld_parsedcomment = false, $fld_sizes = false,
52 $fld_notificationtimestamp = false, $fld_userid = false,
53 $fld_loginfo = false, $fld_tags;
56 * @param ApiPageSet $resultPageSet
59 private function run( $resultPageSet = null ) {
60 $this->selectNamedDB( 'watchlist', DB_REPLICA
, 'watchlist' );
62 $params = $this->extractRequestParams();
64 $user = $this->getUser();
65 $wlowner = $this->getWatchlistUser( $params );
67 if ( !is_null( $params['prop'] ) && is_null( $resultPageSet ) ) {
68 $prop = array_flip( $params['prop'] );
70 $this->fld_ids
= isset( $prop['ids'] );
71 $this->fld_title
= isset( $prop['title'] );
72 $this->fld_flags
= isset( $prop['flags'] );
73 $this->fld_user
= isset( $prop['user'] );
74 $this->fld_userid
= isset( $prop['userid'] );
75 $this->fld_comment
= isset( $prop['comment'] );
76 $this->fld_parsedcomment
= isset( $prop['parsedcomment'] );
77 $this->fld_timestamp
= isset( $prop['timestamp'] );
78 $this->fld_sizes
= isset( $prop['sizes'] );
79 $this->fld_patrol
= isset( $prop['patrol'] );
80 $this->fld_notificationtimestamp
= isset( $prop['notificationtimestamp'] );
81 $this->fld_loginfo
= isset( $prop['loginfo'] );
82 $this->fld_tags
= isset( $prop['tags'] );
84 if ( $this->fld_patrol
) {
85 if ( !$user->useRCPatrol() && !$user->useNPPatrol() ) {
86 $this->dieWithError( 'apierror-permissiondenied-patrolflag', 'patrol' );
90 if ( $this->fld_comment ||
$this->fld_parsedcomment
) {
91 $this->commentStore
= CommentStore
::getStore();
96 'dir' => $params['dir'] === 'older'
97 ? WatchedItemQueryService
::DIR_OLDER
98 : WatchedItemQueryService
::DIR_NEWER
,
101 if ( is_null( $resultPageSet ) ) {
102 $options['includeFields'] = $this->getFieldsToInclude();
104 $options['usedInGenerator'] = true;
107 if ( $params['start'] ) {
108 $options['start'] = $params['start'];
110 if ( $params['end'] ) {
111 $options['end'] = $params['end'];
115 if ( !is_null( $params['continue'] ) ) {
116 $cont = explode( '|', $params['continue'] );
117 $this->dieContinueUsageIf( count( $cont ) != 2 );
118 $continueTimestamp = $cont[0];
119 $continueId = (int)$cont[1];
120 $this->dieContinueUsageIf( $continueId != $cont[1] );
121 $startFrom = [ $continueTimestamp, $continueId ];
124 if ( $wlowner !== $user ) {
125 $options['watchlistOwner'] = $wlowner;
126 $options['watchlistOwnerToken'] = $params['token'];
129 if ( !is_null( $params['namespace'] ) ) {
130 $options['namespaceIds'] = $params['namespace'];
133 if ( $params['allrev'] ) {
134 $options['allRevisions'] = true;
137 if ( !is_null( $params['show'] ) ) {
138 $show = array_flip( $params['show'] );
140 /* Check for conflicting parameters. */
141 if ( $this->showParamsConflicting( $show ) ) {
142 $this->dieWithError( 'apierror-show' );
145 // Check permissions.
146 if ( isset( $show[WatchedItemQueryService
::FILTER_PATROLLED
] )
147 ||
isset( $show[WatchedItemQueryService
::FILTER_NOT_PATROLLED
] )
149 if ( !$user->useRCPatrol() && !$user->useNPPatrol() ) {
150 $this->dieWithError( 'apierror-permissiondenied-patrolflag', 'permissiondenied' );
154 $options['filters'] = array_keys( $show );
157 if ( !is_null( $params['type'] ) ) {
159 $rcTypes = RecentChange
::parseToRCType( $params['type'] );
161 $options['rcTypes'] = $rcTypes;
163 } catch ( Exception
$e ) {
164 ApiBase
::dieDebug( __METHOD__
, $e->getMessage() );
168 $this->requireMaxOneParameter( $params, 'user', 'excludeuser' );
169 if ( !is_null( $params['user'] ) ) {
170 $options['onlyByUser'] = $params['user'];
172 if ( !is_null( $params['excludeuser'] ) ) {
173 $options['notByUser'] = $params['excludeuser'];
176 $options['limit'] = $params['limit'];
178 Hooks
::run( 'ApiQueryWatchlistPrepareWatchedItemQueryServiceOptions', [
179 $this, $params, &$options
184 $watchedItemQuery = MediaWikiServices
::getInstance()->getWatchedItemQueryService();
185 $items = $watchedItemQuery->getWatchedItemsWithRecentChangeInfo( $wlowner, $options, $startFrom );
187 foreach ( $items as list( $watchedItem, $recentChangeInfo ) ) {
188 /** @var WatchedItem $watchedItem */
189 if ( is_null( $resultPageSet ) ) {
190 $vals = $this->extractOutputData( $watchedItem, $recentChangeInfo );
191 $fit = $this->getResult()->addValue( [ 'query', $this->getModuleName() ], null, $vals );
193 $startFrom = [ $recentChangeInfo['rc_timestamp'], $recentChangeInfo['rc_id'] ];
197 if ( $params['allrev'] ) {
198 $ids[] = intval( $recentChangeInfo['rc_this_oldid'] );
200 $ids[] = intval( $recentChangeInfo['rc_cur_id'] );
205 if ( $startFrom !== null ) {
206 $this->setContinueEnumParameter( 'continue', implode( '|', $startFrom ) );
209 if ( is_null( $resultPageSet ) ) {
210 $this->getResult()->addIndexedTagName(
211 [ 'query', $this->getModuleName() ],
214 } elseif ( $params['allrev'] ) {
215 $resultPageSet->populateFromRevisionIDs( $ids );
217 $resultPageSet->populateFromPageIDs( $ids );
221 private function getFieldsToInclude() {
223 if ( $this->fld_flags
) {
224 $includeFields[] = WatchedItemQueryService
::INCLUDE_FLAGS
;
226 if ( $this->fld_user ||
$this->fld_userid
) {
227 $includeFields[] = WatchedItemQueryService
::INCLUDE_USER_ID
;
229 if ( $this->fld_user
) {
230 $includeFields[] = WatchedItemQueryService
::INCLUDE_USER
;
232 if ( $this->fld_comment ||
$this->fld_parsedcomment
) {
233 $includeFields[] = WatchedItemQueryService
::INCLUDE_COMMENT
;
235 if ( $this->fld_patrol
) {
236 $includeFields[] = WatchedItemQueryService
::INCLUDE_PATROL_INFO
;
237 $includeFields[] = WatchedItemQueryService
::INCLUDE_AUTOPATROL_INFO
;
239 if ( $this->fld_sizes
) {
240 $includeFields[] = WatchedItemQueryService
::INCLUDE_SIZES
;
242 if ( $this->fld_loginfo
) {
243 $includeFields[] = WatchedItemQueryService
::INCLUDE_LOG_INFO
;
245 if ( $this->fld_tags
) {
246 $includeFields[] = WatchedItemQueryService
::INCLUDE_TAGS
;
248 return $includeFields;
251 private function showParamsConflicting( array $show ) {
252 return ( isset( $show[WatchedItemQueryService
::FILTER_MINOR
] )
253 && isset( $show[WatchedItemQueryService
::FILTER_NOT_MINOR
] ) )
254 ||
( isset( $show[WatchedItemQueryService
::FILTER_BOT
] )
255 && isset( $show[WatchedItemQueryService
::FILTER_NOT_BOT
] ) )
256 ||
( isset( $show[WatchedItemQueryService
::FILTER_ANON
] )
257 && isset( $show[WatchedItemQueryService
::FILTER_NOT_ANON
] ) )
258 ||
( isset( $show[WatchedItemQueryService
::FILTER_PATROLLED
] )
259 && isset( $show[WatchedItemQueryService
::FILTER_NOT_PATROLLED
] ) )
260 ||
( isset( $show[WatchedItemQueryService
::FILTER_AUTOPATROLLED
] )
261 && isset( $show[WatchedItemQueryService
::FILTER_NOT_AUTOPATROLLED
] ) )
262 ||
( isset( $show[WatchedItemQueryService
::FILTER_AUTOPATROLLED
] )
263 && isset( $show[WatchedItemQueryService
::FILTER_NOT_PATROLLED
] ) )
264 ||
( isset( $show[WatchedItemQueryService
::FILTER_UNREAD
] )
265 && isset( $show[WatchedItemQueryService
::FILTER_NOT_UNREAD
] ) );
268 private function extractOutputData( WatchedItem
$watchedItem, array $recentChangeInfo ) {
269 /* Determine the title of the page that has been changed. */
270 $title = Title
::newFromLinkTarget( $watchedItem->getLinkTarget() );
271 $user = $this->getUser();
273 /* Our output data. */
275 $type = intval( $recentChangeInfo['rc_type'] );
276 $vals['type'] = RecentChange
::parseFromRCType( $type );
279 /* Create a new entry in the result for the title. */
280 if ( $this->fld_title ||
$this->fld_ids
) {
281 // These should already have been filtered out of the query, but just in case.
282 if ( $type === RC_LOG
&& ( $recentChangeInfo['rc_deleted'] & LogPage
::DELETED_ACTION
) ) {
283 $vals['actionhidden'] = true;
286 if ( $type !== RC_LOG ||
287 LogEventsList
::userCanBitfield(
288 $recentChangeInfo['rc_deleted'],
289 LogPage
::DELETED_ACTION
,
293 if ( $this->fld_title
) {
294 ApiQueryBase
::addTitleInfo( $vals, $title );
296 if ( $this->fld_ids
) {
297 $vals['pageid'] = intval( $recentChangeInfo['rc_cur_id'] );
298 $vals['revid'] = intval( $recentChangeInfo['rc_this_oldid'] );
299 $vals['old_revid'] = intval( $recentChangeInfo['rc_last_oldid'] );
304 /* Add user data and 'anon' flag, if user is anonymous. */
305 if ( $this->fld_user ||
$this->fld_userid
) {
306 if ( $recentChangeInfo['rc_deleted'] & RevisionRecord
::DELETED_USER
) {
307 $vals['userhidden'] = true;
310 if ( RevisionRecord
::userCanBitfield(
311 $recentChangeInfo['rc_deleted'],
312 RevisionRecord
::DELETED_USER
,
315 if ( $this->fld_userid
) {
316 $vals['userid'] = (int)$recentChangeInfo['rc_user'];
317 // for backwards compatibility
318 $vals['user'] = (int)$recentChangeInfo['rc_user'];
321 if ( $this->fld_user
) {
322 $vals['user'] = $recentChangeInfo['rc_user_text'];
325 if ( !$recentChangeInfo['rc_user'] ) {
326 $vals['anon'] = true;
331 /* Add flags, such as new, minor, bot. */
332 if ( $this->fld_flags
) {
333 $vals['bot'] = (bool)$recentChangeInfo['rc_bot'];
334 $vals['new'] = $recentChangeInfo['rc_type'] == RC_NEW
;
335 $vals['minor'] = (bool)$recentChangeInfo['rc_minor'];
338 /* Add sizes of each revision. (Only available on 1.10+) */
339 if ( $this->fld_sizes
) {
340 $vals['oldlen'] = intval( $recentChangeInfo['rc_old_len'] );
341 $vals['newlen'] = intval( $recentChangeInfo['rc_new_len'] );
344 /* Add the timestamp. */
345 if ( $this->fld_timestamp
) {
346 $vals['timestamp'] = wfTimestamp( TS_ISO_8601
, $recentChangeInfo['rc_timestamp'] );
349 if ( $this->fld_notificationtimestamp
) {
350 $vals['notificationtimestamp'] = ( $watchedItem->getNotificationTimestamp() == null )
352 : wfTimestamp( TS_ISO_8601
, $watchedItem->getNotificationTimestamp() );
355 /* Add edit summary / log summary. */
356 if ( $this->fld_comment ||
$this->fld_parsedcomment
) {
357 if ( $recentChangeInfo['rc_deleted'] & RevisionRecord
::DELETED_COMMENT
) {
358 $vals['commenthidden'] = true;
361 if ( RevisionRecord
::userCanBitfield(
362 $recentChangeInfo['rc_deleted'],
363 RevisionRecord
::DELETED_COMMENT
,
366 $comment = $this->commentStore
->getComment( 'rc_comment', $recentChangeInfo )->text
;
367 if ( $this->fld_comment
) {
368 $vals['comment'] = $comment;
371 if ( $this->fld_parsedcomment
) {
372 $vals['parsedcomment'] = Linker
::formatComment( $comment, $title );
377 /* Add the patrolled flag */
378 if ( $this->fld_patrol
) {
379 $vals['patrolled'] = $recentChangeInfo['rc_patrolled'] != RecentChange
::PRC_UNPATROLLED
;
380 $vals['unpatrolled'] = ChangesList
::isUnpatrolled( (object)$recentChangeInfo, $user );
381 $vals['autopatrolled'] = $recentChangeInfo['rc_patrolled'] == RecentChange
::PRC_AUTOPATROLLED
;
384 if ( $this->fld_loginfo
&& $recentChangeInfo['rc_type'] == RC_LOG
) {
385 if ( $recentChangeInfo['rc_deleted'] & LogPage
::DELETED_ACTION
) {
386 $vals['actionhidden'] = true;
389 if ( LogEventsList
::userCanBitfield(
390 $recentChangeInfo['rc_deleted'],
391 LogPage
::DELETED_ACTION
,
394 $vals['logid'] = intval( $recentChangeInfo['rc_logid'] );
395 $vals['logtype'] = $recentChangeInfo['rc_log_type'];
396 $vals['logaction'] = $recentChangeInfo['rc_log_action'];
397 $vals['logparams'] = LogFormatter
::newFromRow( $recentChangeInfo )->formatParametersForApi();
401 if ( $this->fld_tags
) {
402 if ( $recentChangeInfo['rc_tags'] ) {
403 $tags = explode( ',', $recentChangeInfo['rc_tags'] );
404 ApiResult
::setIndexedTagName( $tags, 'tag' );
405 $vals['tags'] = $tags;
411 if ( $anyHidden && ( $recentChangeInfo['rc_deleted'] & RevisionRecord
::DELETED_RESTRICTED
) ) {
412 $vals['suppressed'] = true;
415 Hooks
::run( 'ApiQueryWatchlistExtractOutputData', [
416 $this, $watchedItem, $recentChangeInfo, &$vals
422 public function getAllowedParams() {
426 ApiBase
::PARAM_TYPE
=> 'timestamp'
429 ApiBase
::PARAM_TYPE
=> 'timestamp'
432 ApiBase
::PARAM_ISMULTI
=> true,
433 ApiBase
::PARAM_TYPE
=> 'namespace'
436 ApiBase
::PARAM_TYPE
=> 'user',
439 ApiBase
::PARAM_TYPE
=> 'user',
442 ApiBase
::PARAM_DFLT
=> 'older',
443 ApiBase
::PARAM_TYPE
=> [
447 ApiHelp
::PARAM_HELP_MSG
=> 'api-help-param-direction',
450 ApiBase
::PARAM_DFLT
=> 10,
451 ApiBase
::PARAM_TYPE
=> 'limit',
452 ApiBase
::PARAM_MIN
=> 1,
453 ApiBase
::PARAM_MAX
=> ApiBase
::LIMIT_BIG1
,
454 ApiBase
::PARAM_MAX2
=> ApiBase
::LIMIT_BIG2
457 ApiBase
::PARAM_ISMULTI
=> true,
458 ApiBase
::PARAM_DFLT
=> 'ids|title|flags',
459 ApiBase
::PARAM_HELP_MSG_PER_VALUE
=> [],
460 ApiBase
::PARAM_TYPE
=> [
471 'notificationtimestamp',
477 ApiBase
::PARAM_ISMULTI
=> true,
478 ApiBase
::PARAM_TYPE
=> [
479 WatchedItemQueryService
::FILTER_MINOR
,
480 WatchedItemQueryService
::FILTER_NOT_MINOR
,
481 WatchedItemQueryService
::FILTER_BOT
,
482 WatchedItemQueryService
::FILTER_NOT_BOT
,
483 WatchedItemQueryService
::FILTER_ANON
,
484 WatchedItemQueryService
::FILTER_NOT_ANON
,
485 WatchedItemQueryService
::FILTER_PATROLLED
,
486 WatchedItemQueryService
::FILTER_NOT_PATROLLED
,
487 WatchedItemQueryService
::FILTER_AUTOPATROLLED
,
488 WatchedItemQueryService
::FILTER_NOT_AUTOPATROLLED
,
489 WatchedItemQueryService
::FILTER_UNREAD
,
490 WatchedItemQueryService
::FILTER_NOT_UNREAD
,
494 ApiBase
::PARAM_DFLT
=> 'edit|new|log|categorize',
495 ApiBase
::PARAM_ISMULTI
=> true,
496 ApiBase
::PARAM_HELP_MSG_PER_VALUE
=> [],
497 ApiBase
::PARAM_TYPE
=> RecentChange
::getChangeTypes()
500 ApiBase
::PARAM_TYPE
=> 'user'
503 ApiBase
::PARAM_TYPE
=> 'string',
504 ApiBase
::PARAM_SENSITIVE
=> true,
507 ApiBase
::PARAM_HELP_MSG
=> 'api-help-param-continue',
512 protected function getExamplesMessages() {
514 'action=query&list=watchlist'
515 => 'apihelp-query+watchlist-example-simple',
516 'action=query&list=watchlist&wlprop=ids|title|timestamp|user|comment'
517 => 'apihelp-query+watchlist-example-props',
518 'action=query&list=watchlist&wlallrev=&wlprop=ids|title|timestamp|user|comment'
519 => 'apihelp-query+watchlist-example-allrev',
520 'action=query&generator=watchlist&prop=info'
521 => 'apihelp-query+watchlist-example-generator',
522 'action=query&generator=watchlist&gwlallrev=&prop=revisions&rvprop=timestamp|user'
523 => 'apihelp-query+watchlist-example-generator-rev',
524 'action=query&list=watchlist&wlowner=Example&wltoken=123ABC'
525 => 'apihelp-query+watchlist-example-wlowner',
529 public function getHelpUrls() {
530 return 'https://www.mediawiki.org/wiki/Special:MyLanguage/API:Watchlist';