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 = explode( '|', $params['continue'] );
222  $this->dieContinueUsageIf( count( $cont ) != 2 );
223  $op = ( $params['dir'] === 'newer' ? '>' : '<' );
224  $continueTimestamp = $db->addQuotes( $db->timestamp( $cont[0] ) );
225  $continueId = (int)$cont[1];
226  $this->dieContinueUsageIf( $continueId != $cont[1] );
227  $this->addWhere( "$tsField $op $continueTimestamp OR " .
228  "($tsField = $continueTimestamp AND " .
229  "$idField $op= $continueId)"
230  );
231  }
232 
233  // Convert startid/endid to timestamps (T163532)
234  $revids = [];
235  if ( $params['startid'] !== null ) {
236  $revids[] = (int)$params['startid'];
237  }
238  if ( $params['endid'] !== null ) {
239  $revids[] = (int)$params['endid'];
240  }
241  if ( $revids ) {
242  $db = $this->getDB();
243  $sql = $db->unionQueries( [
244  $db->selectSQLText(
245  'revision',
246  [ 'id' => 'rev_id', 'ts' => 'rev_timestamp' ],
247  [ 'rev_id' => $revids ],
248  __METHOD__
249  ),
250  $db->selectSQLText(
251  'archive',
252  [ 'id' => 'ar_rev_id', 'ts' => 'ar_timestamp' ],
253  [ 'ar_rev_id' => $revids ],
254  __METHOD__
255  ),
256  ], $db::UNION_DISTINCT );
257  $res = $db->query( $sql, __METHOD__ );
258  foreach ( $res as $row ) {
259  if ( (int)$row->id === (int)$params['startid'] ) {
260  $params['start'] = $row->ts;
261  }
262  if ( (int)$row->id === (int)$params['endid'] ) {
263  $params['end'] = $row->ts;
264  }
265  }
266  // @phan-suppress-next-line PhanTypePossiblyInvalidDimOffset False positive
267  if ( $params['startid'] !== null && $params['start'] === null ) {
268  $p = $this->encodeParamName( 'startid' );
269  $this->dieWithError( [ 'apierror-revisions-badid', $p ], "badid_$p" );
270  }
271  // @phan-suppress-next-line PhanTypePossiblyInvalidDimOffset False positive
272  if ( $params['endid'] !== null && $params['end'] === null ) {
273  $p = $this->encodeParamName( 'endid' );
274  $this->dieWithError( [ 'apierror-revisions-badid', $p ], "badid_$p" );
275  }
276 
277  // @phan-suppress-next-line PhanTypePossiblyInvalidDimOffset False positive
278  if ( $params['start'] !== null ) {
279  $op = ( $params['dir'] === 'newer' ? '>' : '<' );
280  // @phan-suppress-next-line PhanTypePossiblyInvalidDimOffset False positive
281  $ts = $db->addQuotes( $db->timestampOrNull( $params['start'] ) );
282  if ( $params['startid'] !== null ) {
283  $this->addWhere( "$tsField $op $ts OR "
284  . "$tsField = $ts AND $idField $op= " . (int)$params['startid'] );
285  } else {
286  $this->addWhere( "$tsField $op= $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->addQuotes( $db->timestampOrNull( $params['end'] ) );
294  if ( $params['endid'] !== null ) {
295  $this->addWhere( "$tsField $op $ts OR "
296  . "$tsField = $ts AND $idField $op= " . (int)$params['endid'] );
297  } else {
298  $this->addWhere( "$tsField $op= $ts" );
299  }
300  }
301  } else {
302  $this->addTimestampWhereRange( $tsField, $params['dir'],
303  $params['start'], $params['end'] );
304  }
305 
306  $sort = ( $params['dir'] === 'newer' ? '' : 'DESC' );
307  $this->addOption( 'ORDER BY', [ "rev_timestamp $sort", "rev_id $sort" ] );
308 
309  // There is only one ID, use it
310  $ids = array_keys( $pageSet->getGoodPages() );
311  $this->addWhereFld( $pageField, reset( $ids ) );
312 
313  if ( $params['user'] !== null ) {
314  $actorQuery = $this->actorMigration->getWhere( $db, 'rev_user', $params['user'] );
315  $this->addTables( $actorQuery['tables'] );
316  $this->addJoinConds( $actorQuery['joins'] );
317  $this->addWhere( $actorQuery['conds'] );
318  } elseif ( $params['excludeuser'] !== null ) {
319  $actorQuery = $this->actorMigration->getWhere( $db, 'rev_user', $params['excludeuser'] );
320  $this->addTables( $actorQuery['tables'] );
321  $this->addJoinConds( $actorQuery['joins'] );
322  $this->addWhere( 'NOT(' . $actorQuery['conds'] . ')' );
323  } else {
324  // T258480: MariaDB ends up using rev_page_actor_timestamp in some cases here.
325  // Last checked with MariaDB 10.4.13
326  // Unless we are filtering by user (see above), we always want to use the
327  // "history" index on the revision table, namely page_timestamp.
328  $useIndex['revision'] = 'rev_page_timestamp';
329  }
330 
331  if ( $params['user'] !== null || $params['excludeuser'] !== null ) {
332  // Paranoia: avoid brute force searches (T19342)
333  if ( !$this->getAuthority()->isAllowed( 'deletedhistory' ) ) {
334  $bitmask = RevisionRecord::DELETED_USER;
335  } elseif ( !$this->getAuthority()->isAllowedAny( 'suppressrevision', 'viewsuppressed' )
336  ) {
337  $bitmask = RevisionRecord::DELETED_USER | RevisionRecord::DELETED_RESTRICTED;
338  } else {
339  $bitmask = 0;
340  }
341  if ( $bitmask ) {
342  $this->addWhere( $db->bitAnd( 'rev_deleted', $bitmask ) . " != $bitmask" );
343  }
344  }
345  } elseif ( $revCount > 0 ) {
346  // Always targets the PRIMARY index
347 
348  $revs = $pageSet->getLiveRevisionIDs();
349 
350  // Get all revision IDs
351  $this->addWhereFld( 'rev_id', array_keys( $revs ) );
352 
353  if ( $params['continue'] !== null ) {
354  $this->addWhere( 'rev_id >= ' . (int)$params['continue'] );
355  }
356  $this->addOption( 'ORDER BY', 'rev_id' );
357  } elseif ( $pageCount > 0 ) {
358  // Always targets the rev_page_id index
359 
360  $pageids = array_keys( $pageSet->getGoodPages() );
361 
362  // When working in multi-page non-enumeration mode,
363  // limit to the latest revision only
364  $this->addWhere( 'page_latest=rev_id' );
365 
366  // Get all page IDs
367  $this->addWhereFld( 'page_id', $pageids );
368  // Every time someone relies on equality propagation, god kills a kitten :)
369  $this->addWhereFld( 'rev_page', $pageids );
370 
371  if ( $params['continue'] !== null ) {
372  $cont = explode( '|', $params['continue'] );
373  $this->dieContinueUsageIf( count( $cont ) != 2 );
374  $pageid = (int)$cont[0];
375  $revid = (int)$cont[1];
376  $this->addWhere(
377  "rev_page > $pageid OR " .
378  "(rev_page = $pageid AND " .
379  "rev_id >= $revid)"
380  );
381  }
382  $this->addOption( 'ORDER BY', [
383  'rev_page',
384  'rev_id'
385  ] );
386  } else {
387  ApiBase::dieDebug( __METHOD__, 'param validation?' );
388  }
389 
390  $this->addOption( 'LIMIT', $this->limit + 1 );
391 
392  $this->addOption( 'IGNORE INDEX', $ignoreIndex );
393 
394  if ( $useIndex ) {
395  $this->addOption( 'USE INDEX', $useIndex );
396  }
397 
398  $count = 0;
399  $generated = [];
400  $hookData = [];
401  $res = $this->select( __METHOD__, [], $hookData );
402 
403  foreach ( $res as $row ) {
404  if ( ++$count > $this->limit ) {
405  // We've reached the one extra which shows that there are
406  // additional pages to be had. Stop here...
407  if ( $enumRevMode ) {
408  $this->setContinueEnumParameter( 'continue',
409  $row->rev_timestamp . '|' . (int)$row->rev_id );
410  } elseif ( $revCount > 0 ) {
411  $this->setContinueEnumParameter( 'continue', (int)$row->rev_id );
412  } else {
413  $this->setContinueEnumParameter( 'continue', (int)$row->rev_page .
414  '|' . (int)$row->rev_id );
415  }
416  break;
417  }
418 
419  if ( $resultPageSet !== null ) {
420  $generated[] = $row->rev_id;
421  } else {
422  $revision = $this->revisionStore->newRevisionFromRow( $row, 0, Title::newFromRow( $row ) );
423  $rev = $this->extractRevisionInfo( $revision, $row );
424  $fit = $this->processRow( $row, $rev, $hookData ) &&
425  $this->addPageSubItem( $row->rev_page, $rev, 'rev' );
426  if ( !$fit ) {
427  if ( $enumRevMode ) {
428  $this->setContinueEnumParameter( 'continue',
429  $row->rev_timestamp . '|' . (int)$row->rev_id );
430  } elseif ( $revCount > 0 ) {
431  $this->setContinueEnumParameter( 'continue', (int)$row->rev_id );
432  } else {
433  $this->setContinueEnumParameter( 'continue', (int)$row->rev_page .
434  '|' . (int)$row->rev_id );
435  }
436  break;
437  }
438  }
439  }
440 
441  if ( $resultPageSet !== null ) {
442  $resultPageSet->populateFromRevisionIDs( $generated );
443  }
444  }
445 
446  public function getAllowedParams() {
447  $ret = parent::getAllowedParams() + [
448  'startid' => [
449  ParamValidator::PARAM_TYPE => 'integer',
450  ApiBase::PARAM_HELP_MSG_INFO => [ [ 'singlepageonly' ] ],
451  ],
452  'endid' => [
453  ParamValidator::PARAM_TYPE => 'integer',
454  ApiBase::PARAM_HELP_MSG_INFO => [ [ 'singlepageonly' ] ],
455  ],
456  'start' => [
457  ParamValidator::PARAM_TYPE => 'timestamp',
458  ApiBase::PARAM_HELP_MSG_INFO => [ [ 'singlepageonly' ] ],
459  ],
460  'end' => [
461  ParamValidator::PARAM_TYPE => 'timestamp',
462  ApiBase::PARAM_HELP_MSG_INFO => [ [ 'singlepageonly' ] ],
463  ],
464  'dir' => [
465  ParamValidator::PARAM_DEFAULT => 'older',
466  ParamValidator::PARAM_TYPE => [
467  'newer',
468  'older'
469  ],
470  ApiBase::PARAM_HELP_MSG => 'api-help-param-direction',
471  ApiBase::PARAM_HELP_MSG_INFO => [ [ 'singlepageonly' ] ],
472  ],
473  'user' => [
474  ParamValidator::PARAM_TYPE => 'user',
475  UserDef::PARAM_ALLOWED_USER_TYPES => [ 'name', 'ip', 'id', 'interwiki' ],
476  UserDef::PARAM_RETURN_OBJECT => true,
477  ApiBase::PARAM_HELP_MSG_INFO => [ [ 'singlepageonly' ] ],
478  ],
479  'excludeuser' => [
480  ParamValidator::PARAM_TYPE => 'user',
481  UserDef::PARAM_ALLOWED_USER_TYPES => [ 'name', 'ip', 'id', 'interwiki' ],
482  UserDef::PARAM_RETURN_OBJECT => true,
483  ApiBase::PARAM_HELP_MSG_INFO => [ [ 'singlepageonly' ] ],
484  ],
485  'tag' => null,
486  'continue' => [
487  ApiBase::PARAM_HELP_MSG => 'api-help-param-continue',
488  ],
489  ];
490 
491  $ret['limit'][ApiBase::PARAM_HELP_MSG_INFO] = [ [ 'singlepageonly' ] ];
492 
493  return $ret;
494  }
495 
496  protected function getExamplesMessages() {
497  return [
498  'action=query&prop=revisions&titles=API|Main%20Page&' .
499  'rvslots=*&rvprop=timestamp|user|comment|content'
500  => 'apihelp-query+revisions-example-content',
501  'action=query&prop=revisions&titles=Main%20Page&rvlimit=5&' .
502  'rvprop=timestamp|user|comment'
503  => 'apihelp-query+revisions-example-last5',
504  'action=query&prop=revisions&titles=Main%20Page&rvlimit=5&' .
505  'rvprop=timestamp|user|comment&rvdir=newer'
506  => 'apihelp-query+revisions-example-first5',
507  'action=query&prop=revisions&titles=Main%20Page&rvlimit=5&' .
508  'rvprop=timestamp|user|comment&rvdir=newer&rvstart=2006-05-01T00:00:00Z'
509  => 'apihelp-query+revisions-example-first5-after',
510  'action=query&prop=revisions&titles=Main%20Page&rvlimit=5&' .
511  'rvprop=timestamp|user|comment&rvexcludeuser=127.0.0.1'
512  => 'apihelp-query+revisions-example-first5-not-localhost',
513  'action=query&prop=revisions&titles=Main%20Page&rvlimit=5&' .
514  'rvprop=timestamp|user|comment&rvuser=MediaWiki%20default'
515  => 'apihelp-query+revisions-example-first5-user',
516  ];
517  }
518 
519  public function getHelpUrls() {
520  return 'https://www.mediawiki.org/wiki/Special:MyLanguage/API:Revisions';
521  }
522 }
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:1453
getModulePrefix()
Get parameter prefix (usually two letters or an empty string).
Definition: ApiBase.php:506
getParameter( $paramName, $parseLimit=true)
Get a value for the given parameter.
Definition: ApiBase.php:886
dieContinueUsageIf( $condition)
Die with the 'badcontinue' error.
Definition: ApiBase.php:1645
static dieDebug( $method, $message)
Internal code errors should be reported with this method.
Definition: ApiBase.php:1658
const PARAM_HELP_MSG_INFO
(array) Specify additional information tags for the parameter.
Definition: ApiBase.php:180
requireMaxOneParameter( $params,... $required)
Die if more than one of a certain set of parameters is set and not false.
Definition: ApiBase.php:938
extractRequestParams( $options=[])
Using getAllowedParams(), this function makes an array of the values provided by the user,...
Definition: ApiBase.php:765
const PARAM_HELP_MSG
(string|array|Message) Specify an alternative i18n documentation message for this parameter.
Definition: ApiBase.php:163
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:50
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)
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:82
static newFromRow( $row)
Make a Title object from a DB row.
Definition: Title.php:573
Service for formatting and validating API parameters.
$revQuery