MediaWiki  master
ApiQueryRevisions.php
Go to the documentation of this file.
1 <?php
33 
43 
45  private $revisionStore;
46 
48  private $changeTagDefStore;
49 
51  private $actorMigration;
52 
65  public function __construct(
66  ApiQuery $query,
67  $moduleName,
68  RevisionStore $revisionStore,
69  IContentHandlerFactory $contentHandlerFactory,
70  ParserFactory $parserFactory,
71  SlotRoleRegistry $slotRoleRegistry,
72  NameTableStore $changeTagDefStore,
73  ActorMigration $actorMigration,
74  ContentRenderer $contentRenderer,
75  ContentTransformer $contentTransformer
76  ) {
77  parent::__construct(
78  $query,
79  $moduleName,
80  'rv',
81  $revisionStore,
82  $contentHandlerFactory,
83  $parserFactory,
84  $slotRoleRegistry,
85  $contentRenderer,
86  $contentTransformer
87  );
88  $this->revisionStore = $revisionStore;
89  $this->changeTagDefStore = $changeTagDefStore;
90  $this->actorMigration = $actorMigration;
91  }
92 
93  protected function run( ApiPageSet $resultPageSet = null ) {
94  $params = $this->extractRequestParams( false );
95 
96  // If any of those parameters are used, work in 'enumeration' mode.
97  // Enum mode can only be used when exactly one page is provided.
98  // Enumerating revisions on multiple pages make it extremely
99  // difficult to manage continuations and require additional SQL indexes
100  $enumRevMode = ( $params['user'] !== null || $params['excludeuser'] !== null ||
101  $params['limit'] !== null || $params['startid'] !== null ||
102  $params['endid'] !== null || $params['dir'] === 'newer' ||
103  $params['start'] !== null || $params['end'] !== null );
104 
105  $pageSet = $this->getPageSet();
106  $pageCount = $pageSet->getGoodTitleCount();
107  $revCount = $pageSet->getRevisionCount();
108 
109  // Optimization -- nothing to do
110  if ( $revCount === 0 && $pageCount === 0 ) {
111  // Nothing to do
112  return;
113  }
114  if ( $revCount > 0 && count( $pageSet->getLiveRevisionIDs() ) === 0 ) {
115  // We're in revisions mode but all given revisions are deleted
116  return;
117  }
118 
119  if ( $revCount > 0 && $enumRevMode ) {
120  $this->dieWithError(
121  [ 'apierror-revisions-norevids', $this->getModulePrefix() ], 'invalidparammix'
122  );
123  }
124 
125  if ( $pageCount > 1 && $enumRevMode ) {
126  $this->dieWithError(
127  [ 'apierror-revisions-singlepage', $this->getModulePrefix() ], 'invalidparammix'
128  );
129  }
130 
131  // In non-enum mode, rvlimit can't be directly used. Use the maximum
132  // allowed value.
133  if ( !$enumRevMode ) {
134  $this->setParsedLimit = false;
135  $params['limit'] = 'max';
136  }
137 
138  $db = $this->getDB();
139 
140  $idField = 'rev_id';
141  $tsField = 'rev_timestamp';
142  $pageField = 'rev_page';
143 
144  $ignoreIndex = [
145  // T224017: `rev_timestamp` is never the correct index to use for this module, but
146  // MariaDB sometimes insists on trying to use it anyway. Tell it not to.
147  // Last checked with MariaDB 10.4.13
148  'revision' => 'rev_timestamp',
149  ];
150  $useIndex = [];
151  if ( $resultPageSet === null ) {
152  $this->parseParameters( $params );
153  $opts = [ 'page' ];
154  if ( $this->fld_user ) {
155  $opts[] = 'user';
156  }
157  $revQuery = $this->revisionStore->getQueryInfo( $opts );
158  $this->addTables( $revQuery['tables'] );
159  $this->addFields( $revQuery['fields'] );
160  $this->addJoinConds( $revQuery['joins'] );
161  } else {
162  $this->limit = $this->getParameter( 'limit' ) ?: 10;
163  // Always join 'page' so orphaned revisions are filtered out
164  $this->addTables( [ 'revision', 'page' ] );
165  $this->addJoinConds(
166  [ 'page' => [ 'JOIN', [ 'page_id = rev_page' ] ] ]
167  );
168  $this->addFields( [
169  'rev_id' => $idField, 'rev_timestamp' => $tsField, 'rev_page' => $pageField
170  ] );
171  }
172 
173  if ( $this->fld_tags ) {
174  $this->addFields( [ 'ts_tags' => ChangeTags::makeTagSummarySubquery( 'revision' ) ] );
175  }
176 
177  if ( $params['tag'] !== null ) {
178  $this->addTables( 'change_tag' );
179  $this->addJoinConds(
180  [ 'change_tag' => [ 'JOIN', [ 'rev_id=ct_rev_id' ] ] ]
181  );
182  try {
183  $this->addWhereFld( 'ct_tag_id', $this->changeTagDefStore->getId( $params['tag'] ) );
184  } catch ( NameTableAccessException $exception ) {
185  // Return nothing.
186  $this->addWhere( '1=0' );
187  }
188  }
189 
190  if ( $resultPageSet === null && $this->fetchContent ) {
191  // For each page we will request, the user must have read rights for that page
192  $status = Status::newGood();
193 
195  foreach ( $pageSet->getGoodTitles() as $title ) {
196  if ( !$this->getAuthority()->authorizeRead( 'read', $title ) ) {
197  $status->fatal( ApiMessage::create(
198  [ 'apierror-cannotviewtitle', wfEscapeWikiText( $title->getPrefixedText() ) ],
199  'accessdenied'
200  ) );
201  }
202  }
203  if ( !$status->isGood() ) {
204  $this->dieStatus( $status );
205  }
206  }
207 
208  if ( $enumRevMode ) {
209  // Indexes targeted:
210  // page_timestamp if we don't have rvuser
211  // page_actor_timestamp (on revision_actor_temp) if we have rvuser in READ_NEW mode
212  // page_user_timestamp if we have a logged-in rvuser
213  // page_timestamp or usertext_timestamp if we have an IP rvuser
214 
215  // This is mostly to prevent parameter errors (and optimize SQL?)
216  $this->requireMaxOneParameter( $params, 'startid', 'start' );
217  $this->requireMaxOneParameter( $params, 'endid', 'end' );
218  $this->requireMaxOneParameter( $params, 'user', 'excludeuser' );
219 
220  if ( $params['continue'] !== null ) {
221  $cont = $this->parseContinueParamOrDie( $params['continue'], [ 'timestamp', 'int' ] );
222  $op = ( $params['dir'] === 'newer' ? '>=' : '<=' );
223  $continueTimestamp = $db->timestamp( $cont[0] );
224  $continueId = (int)$cont[1];
225  $this->addWhere( $db->buildComparison( $op, [
226  $tsField => $continueTimestamp,
227  $idField => $continueId,
228  ] ) );
229  }
230 
231  // Convert startid/endid to timestamps (T163532)
232  $revids = [];
233  if ( $params['startid'] !== null ) {
234  $revids[] = (int)$params['startid'];
235  }
236  if ( $params['endid'] !== null ) {
237  $revids[] = (int)$params['endid'];
238  }
239  if ( $revids ) {
240  $db = $this->getDB();
241  $sql = $db->unionQueries( [
242  $db->selectSQLText(
243  'revision',
244  [ 'id' => 'rev_id', 'ts' => 'rev_timestamp' ],
245  [ 'rev_id' => $revids ],
246  __METHOD__
247  ),
248  $db->selectSQLText(
249  'archive',
250  [ 'id' => 'ar_rev_id', 'ts' => 'ar_timestamp' ],
251  [ 'ar_rev_id' => $revids ],
252  __METHOD__
253  ),
254  ], $db::UNION_DISTINCT );
255  $res = $db->query( $sql, __METHOD__ );
256  foreach ( $res as $row ) {
257  if ( (int)$row->id === (int)$params['startid'] ) {
258  $params['start'] = $row->ts;
259  }
260  if ( (int)$row->id === (int)$params['endid'] ) {
261  $params['end'] = $row->ts;
262  }
263  }
264  // @phan-suppress-next-line PhanTypePossiblyInvalidDimOffset False positive
265  if ( $params['startid'] !== null && $params['start'] === null ) {
266  $p = $this->encodeParamName( 'startid' );
267  $this->dieWithError( [ 'apierror-revisions-badid', $p ], "badid_$p" );
268  }
269  // @phan-suppress-next-line PhanTypePossiblyInvalidDimOffset False positive
270  if ( $params['endid'] !== null && $params['end'] === null ) {
271  $p = $this->encodeParamName( 'endid' );
272  $this->dieWithError( [ 'apierror-revisions-badid', $p ], "badid_$p" );
273  }
274 
275  // @phan-suppress-next-line PhanTypePossiblyInvalidDimOffset False positive
276  if ( $params['start'] !== null ) {
277  $op = ( $params['dir'] === 'newer' ? '>=' : '<=' );
278  // @phan-suppress-next-line PhanTypePossiblyInvalidDimOffset False positive
279  $ts = $db->timestampOrNull( $params['start'] );
280  if ( $params['startid'] !== null ) {
281  $this->addWhere( $db->buildComparison( $op, [
282  $tsField => $ts,
283  $idField => (int)$params['startid'],
284  ] ) );
285  } else {
286  $this->addWhere( $db->buildComparison( $op, [ $tsField => $ts ] ) );
287  }
288  }
289  // @phan-suppress-next-line PhanTypePossiblyInvalidDimOffset False positive
290  if ( $params['end'] !== null ) {
291  $op = ( $params['dir'] === 'newer' ? '<=' : '>=' ); // Yes, opposite of the above
292  // @phan-suppress-next-line PhanTypePossiblyInvalidDimOffset False positive
293  $ts = $db->timestampOrNull( $params['end'] );
294  if ( $params['endid'] !== null ) {
295  $this->addWhere( $db->buildComparison( $op, [
296  $tsField => $ts,
297  $idField => (int)$params['endid'],
298  ] ) );
299  } else {
300  $this->addWhere( $db->buildComparison( $op, [ $tsField => $ts ] ) );
301  }
302  }
303  } else {
304  $this->addTimestampWhereRange( $tsField, $params['dir'],
305  $params['start'], $params['end'] );
306  }
307 
308  $sort = ( $params['dir'] === 'newer' ? '' : 'DESC' );
309  $this->addOption( 'ORDER BY', [ "rev_timestamp $sort", "rev_id $sort" ] );
310 
311  // There is only one ID, use it
312  $ids = array_keys( $pageSet->getGoodPages() );
313  $this->addWhereFld( $pageField, reset( $ids ) );
314 
315  if ( $params['user'] !== null ) {
316  $actorQuery = $this->actorMigration->getWhere( $db, 'rev_user', $params['user'] );
317  $this->addTables( $actorQuery['tables'] );
318  $this->addJoinConds( $actorQuery['joins'] );
319  $this->addWhere( $actorQuery['conds'] );
320  } elseif ( $params['excludeuser'] !== null ) {
321  $actorQuery = $this->actorMigration->getWhere( $db, 'rev_user', $params['excludeuser'] );
322  $this->addTables( $actorQuery['tables'] );
323  $this->addJoinConds( $actorQuery['joins'] );
324  $this->addWhere( 'NOT(' . $actorQuery['conds'] . ')' );
325  } else {
326  // T258480: MariaDB ends up using rev_page_actor_timestamp in some cases here.
327  // Last checked with MariaDB 10.4.13
328  // Unless we are filtering by user (see above), we always want to use the
329  // "history" index on the revision table, namely page_timestamp.
330  $useIndex['revision'] = 'rev_page_timestamp';
331  }
332 
333  if ( $params['user'] !== null || $params['excludeuser'] !== null ) {
334  // Paranoia: avoid brute force searches (T19342)
335  if ( !$this->getAuthority()->isAllowed( 'deletedhistory' ) ) {
336  $bitmask = RevisionRecord::DELETED_USER;
337  } elseif ( !$this->getAuthority()->isAllowedAny( 'suppressrevision', 'viewsuppressed' )
338  ) {
339  $bitmask = RevisionRecord::DELETED_USER | RevisionRecord::DELETED_RESTRICTED;
340  } else {
341  $bitmask = 0;
342  }
343  if ( $bitmask ) {
344  $this->addWhere( $db->bitAnd( 'rev_deleted', $bitmask ) . " != $bitmask" );
345  }
346  }
347  } elseif ( $revCount > 0 ) {
348  // Always targets the PRIMARY index
349 
350  $revs = $pageSet->getLiveRevisionIDs();
351 
352  // Get all revision IDs
353  $this->addWhereFld( 'rev_id', array_keys( $revs ) );
354 
355  if ( $params['continue'] !== null ) {
356  $this->addWhere( 'rev_id >= ' . (int)$params['continue'] );
357  }
358  $this->addOption( 'ORDER BY', 'rev_id' );
359  } elseif ( $pageCount > 0 ) {
360  // Always targets the rev_page_id index
361 
362  $pageids = array_keys( $pageSet->getGoodPages() );
363 
364  // When working in multi-page non-enumeration mode,
365  // limit to the latest revision only
366  $this->addWhere( 'page_latest=rev_id' );
367 
368  // Get all page IDs
369  $this->addWhereFld( 'page_id', $pageids );
370  // Every time someone relies on equality propagation, god kills a kitten :)
371  $this->addWhereFld( 'rev_page', $pageids );
372 
373  if ( $params['continue'] !== null ) {
374  $cont = $this->parseContinueParamOrDie( $params['continue'], [ 'int', 'int' ] );
375  $this->addWhere( $db->buildComparison( '>=', [
376  'rev_page' => $cont[0],
377  'rev_id' => $cont[1],
378  ] ) );
379  }
380  $this->addOption( 'ORDER BY', [
381  'rev_page',
382  'rev_id'
383  ] );
384  } else {
385  ApiBase::dieDebug( __METHOD__, 'param validation?' );
386  }
387 
388  $this->addOption( 'LIMIT', $this->limit + 1 );
389 
390  $this->addOption( 'IGNORE INDEX', $ignoreIndex );
391 
392  if ( $useIndex ) {
393  $this->addOption( 'USE INDEX', $useIndex );
394  }
395 
396  $count = 0;
397  $generated = [];
398  $hookData = [];
399  $res = $this->select( __METHOD__, [], $hookData );
400 
401  foreach ( $res as $row ) {
402  if ( ++$count > $this->limit ) {
403  // We've reached the one extra which shows that there are
404  // additional pages to be had. Stop here...
405  if ( $enumRevMode ) {
406  $this->setContinueEnumParameter( 'continue',
407  $row->rev_timestamp . '|' . (int)$row->rev_id );
408  } elseif ( $revCount > 0 ) {
409  $this->setContinueEnumParameter( 'continue', (int)$row->rev_id );
410  } else {
411  $this->setContinueEnumParameter( 'continue', (int)$row->rev_page .
412  '|' . (int)$row->rev_id );
413  }
414  break;
415  }
416 
417  if ( $resultPageSet !== null ) {
418  $generated[] = $row->rev_id;
419  } else {
420  $revision = $this->revisionStore->newRevisionFromRow( $row, 0, Title::newFromRow( $row ) );
421  $rev = $this->extractRevisionInfo( $revision, $row );
422  $fit = $this->processRow( $row, $rev, $hookData ) &&
423  $this->addPageSubItem( $row->rev_page, $rev, 'rev' );
424  if ( !$fit ) {
425  if ( $enumRevMode ) {
426  $this->setContinueEnumParameter( 'continue',
427  $row->rev_timestamp . '|' . (int)$row->rev_id );
428  } elseif ( $revCount > 0 ) {
429  $this->setContinueEnumParameter( 'continue', (int)$row->rev_id );
430  } else {
431  $this->setContinueEnumParameter( 'continue', (int)$row->rev_page .
432  '|' . (int)$row->rev_id );
433  }
434  break;
435  }
436  }
437  }
438 
439  if ( $resultPageSet !== null ) {
440  $resultPageSet->populateFromRevisionIDs( $generated );
441  }
442  }
443 
444  public function getAllowedParams() {
445  $ret = parent::getAllowedParams() + [
446  'startid' => [
447  ParamValidator::PARAM_TYPE => 'integer',
448  ApiBase::PARAM_HELP_MSG_INFO => [ [ 'singlepageonly' ] ],
449  ],
450  'endid' => [
451  ParamValidator::PARAM_TYPE => 'integer',
452  ApiBase::PARAM_HELP_MSG_INFO => [ [ 'singlepageonly' ] ],
453  ],
454  'start' => [
455  ParamValidator::PARAM_TYPE => 'timestamp',
456  ApiBase::PARAM_HELP_MSG_INFO => [ [ 'singlepageonly' ] ],
457  ],
458  'end' => [
459  ParamValidator::PARAM_TYPE => 'timestamp',
460  ApiBase::PARAM_HELP_MSG_INFO => [ [ 'singlepageonly' ] ],
461  ],
462  'dir' => [
463  ParamValidator::PARAM_DEFAULT => 'older',
464  ParamValidator::PARAM_TYPE => [
465  'newer',
466  'older'
467  ],
468  ApiBase::PARAM_HELP_MSG => 'api-help-param-direction',
469  ApiBase::PARAM_HELP_MSG_INFO => [ [ 'singlepageonly' ] ],
470  ],
471  'user' => [
472  ParamValidator::PARAM_TYPE => 'user',
473  UserDef::PARAM_ALLOWED_USER_TYPES => [ 'name', 'ip', 'id', 'interwiki' ],
474  UserDef::PARAM_RETURN_OBJECT => true,
475  ApiBase::PARAM_HELP_MSG_INFO => [ [ 'singlepageonly' ] ],
476  ],
477  'excludeuser' => [
478  ParamValidator::PARAM_TYPE => 'user',
479  UserDef::PARAM_ALLOWED_USER_TYPES => [ 'name', 'ip', 'id', 'interwiki' ],
480  UserDef::PARAM_RETURN_OBJECT => true,
481  ApiBase::PARAM_HELP_MSG_INFO => [ [ 'singlepageonly' ] ],
482  ],
483  'tag' => null,
484  'continue' => [
485  ApiBase::PARAM_HELP_MSG => 'api-help-param-continue',
486  ],
487  ];
488 
489  $ret['limit'][ApiBase::PARAM_HELP_MSG_INFO] = [ [ 'singlepageonly' ] ];
490 
491  return $ret;
492  }
493 
494  protected function getExamplesMessages() {
495  return [
496  'action=query&prop=revisions&titles=API|Main%20Page&' .
497  'rvslots=*&rvprop=timestamp|user|comment|content'
498  => 'apihelp-query+revisions-example-content',
499  'action=query&prop=revisions&titles=Main%20Page&rvlimit=5&' .
500  'rvprop=timestamp|user|comment'
501  => 'apihelp-query+revisions-example-last5',
502  'action=query&prop=revisions&titles=Main%20Page&rvlimit=5&' .
503  'rvprop=timestamp|user|comment&rvdir=newer'
504  => 'apihelp-query+revisions-example-first5',
505  'action=query&prop=revisions&titles=Main%20Page&rvlimit=5&' .
506  'rvprop=timestamp|user|comment&rvdir=newer&rvstart=2006-05-01T00:00:00Z'
507  => 'apihelp-query+revisions-example-first5-after',
508  'action=query&prop=revisions&titles=Main%20Page&rvlimit=5&' .
509  'rvprop=timestamp|user|comment&rvexcludeuser=127.0.0.1'
510  => 'apihelp-query+revisions-example-first5-not-localhost',
511  'action=query&prop=revisions&titles=Main%20Page&rvlimit=5&' .
512  'rvprop=timestamp|user|comment&rvuser=MediaWiki%20default'
513  => 'apihelp-query+revisions-example-first5-user',
514  ];
515  }
516 
517  public function getHelpUrls() {
518  return 'https://www.mediawiki.org/wiki/Special:MyLanguage/API:Revisions';
519  }
520 }
wfEscapeWikiText( $text)
Escapes the given text so that it may be output using addWikiText() without any linking,...
This is not intended to be a long-term part of MediaWiki; it will be deprecated and removed once acto...
dieWithError( $msg, $code=null, $data=null, $httpCode=0)
Abort execution with an error.
Definition: ApiBase.php:1455
getModulePrefix()
Get parameter prefix (usually two letters or an empty string).
Definition: ApiBase.php:507
getParameter( $paramName, $parseLimit=true)
Get a value for the given parameter.
Definition: ApiBase.php:887
static dieDebug( $method, $message)
Internal code errors should be reported with this method.
Definition: ApiBase.php:1696
const PARAM_HELP_MSG_INFO
(array) Specify additional information tags for the parameter.
Definition: ApiBase.php:181
parseContinueParamOrDie(string $continue, array $types)
Parse the 'continue' parameter in the usual format and validate the types of each part,...
Definition: ApiBase.php:1644
requireMaxOneParameter( $params,... $required)
Die if more than one of a certain set of parameters is set and not false.
Definition: ApiBase.php:939
extractRequestParams( $options=[])
Using getAllowedParams(), this function makes an array of the values provided by the user,...
Definition: ApiBase.php:766
const PARAM_HELP_MSG
(string|array|Message) Specify an alternative i18n documentation message for this parameter.
Definition: ApiBase.php:164
dieStatus(StatusValue $status)
Throw an ApiUsageException based on the Status object.
Definition: ApiBase.php:1516
static create( $msg, $code=null, array $data=null)
Create an IApiMessage for the message.
Definition: ApiMessage.php:43
This class contains a list of pages that the client has requested.
Definition: ApiPageSet.php:52
processRow( $row, array &$data, array &$hookData)
Call the ApiQueryBaseProcessRow hook.
addFields( $value)
Add a set of fields to select to the internal array.
addPageSubItem( $pageId, $item, $elemname=null)
Same as addPageSubItems(), but one element of $data at a time.
addOption( $name, $value=null)
Add an option such as LIMIT or USE INDEX.
addTables( $tables, $alias=null)
Add a set of tables to the internal array.
addTimestampWhereRange( $field, $dir, $start, $end, $sort=true)
Add a WHERE clause corresponding to a range, similar to addWhereRange, but converts $start and $end t...
getDB()
Get the Query database connection (read-only)
select( $method, $extraQuery=[], array &$hookData=null)
Execute a SELECT query based on the values in the internal arrays.
addJoinConds( $join_conds)
Add a set of JOIN conditions to the internal array.
addWhereFld( $field, $value)
Equivalent to addWhere( [ $field => $value ] )
addWhere( $value)
Add a set of WHERE clauses to the internal array.
setContinueEnumParameter( $paramName, $paramValue)
Overridden to set the generator param if in generator mode.
getPageSet()
Get the PageSet object to work on.
encodeParamName( $paramName)
Overrides ApiBase to prepend 'g' to every generator parameter.
A base class for functions common to producing a list of revisions.
parseParameters( $params)
Parse the parameters into the various instance fields.
extractRevisionInfo(RevisionRecord $revision, $row)
Extract information from the RevisionRecord.
A query action to enumerate revisions of a given page, or show top revisions of multiple pages.
__construct(ApiQuery $query, $moduleName, RevisionStore $revisionStore, IContentHandlerFactory $contentHandlerFactory, ParserFactory $parserFactory, SlotRoleRegistry $slotRoleRegistry, NameTableStore $changeTagDefStore, ActorMigration $actorMigration, ContentRenderer $contentRenderer, ContentTransformer $contentTransformer)
getHelpUrls()
Return links to more detailed help pages about the module.
run(ApiPageSet $resultPageSet=null)
getAllowedParams()
@stable to override
getExamplesMessages()
Returns usage examples for this module.
This is the main query class.
Definition: ApiQuery.php:41
static makeTagSummarySubquery( $tables)
Make the tag summary subquery based on the given tables and return it.
Page revision base class.
Service for looking up page revisions.
A registry service for SlotRoleHandlers, used to define which slot roles are available on which page.
Exception representing a failure to look up a row from a name table.
static newGood( $value=null)
Factory function for good results.
Definition: StatusValue.php:85
static newFromRow( $row)
Make a Title object from a DB row.
Definition: Title.php:576
Service for formatting and validating API parameters.
$revQuery