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 Wikimedia\Rdbms\IDatabase
;
27 * This is the main query class. It behaves similar to ApiMain: based on the
28 * parameters given, it will create a list of titles to work on (an ApiPageSet
29 * object), instantiate and execute various property/list/meta modules, and
30 * assemble all resulting data into a single ApiResult object.
32 * In generator mode, a generator will be executed first to populate a second
33 * ApiPageSet object, and that object will be used for all subsequent modules.
37 class ApiQuery
extends ApiBase
{
40 * List of Api Query prop modules
43 private static $QueryPropModules = [
44 'categories' => ApiQueryCategories
::class,
45 'categoryinfo' => ApiQueryCategoryInfo
::class,
46 'contributors' => ApiQueryContributors
::class,
47 'deletedrevisions' => ApiQueryDeletedRevisions
::class,
48 'duplicatefiles' => ApiQueryDuplicateFiles
::class,
49 'extlinks' => ApiQueryExternalLinks
::class,
50 'fileusage' => ApiQueryBacklinksprop
::class,
51 'images' => ApiQueryImages
::class,
52 'imageinfo' => ApiQueryImageInfo
::class,
53 'info' => ApiQueryInfo
::class,
54 'links' => ApiQueryLinks
::class,
55 'linkshere' => ApiQueryBacklinksprop
::class,
56 'iwlinks' => ApiQueryIWLinks
::class,
57 'langlinks' => ApiQueryLangLinks
::class,
58 'pageprops' => ApiQueryPageProps
::class,
59 'redirects' => ApiQueryBacklinksprop
::class,
60 'revisions' => ApiQueryRevisions
::class,
61 'stashimageinfo' => ApiQueryStashImageInfo
::class,
62 'templates' => ApiQueryLinks
::class,
63 'transcludedin' => ApiQueryBacklinksprop
::class,
67 * List of Api Query list modules
70 private static $QueryListModules = [
71 'allcategories' => ApiQueryAllCategories
::class,
72 'alldeletedrevisions' => ApiQueryAllDeletedRevisions
::class,
73 'allfileusages' => ApiQueryAllLinks
::class,
74 'allimages' => ApiQueryAllImages
::class,
75 'alllinks' => ApiQueryAllLinks
::class,
76 'allpages' => ApiQueryAllPages
::class,
77 'allredirects' => ApiQueryAllLinks
::class,
78 'allrevisions' => ApiQueryAllRevisions
::class,
79 'mystashedfiles' => ApiQueryMyStashedFiles
::class,
80 'alltransclusions' => ApiQueryAllLinks
::class,
81 'allusers' => ApiQueryAllUsers
::class,
82 'backlinks' => ApiQueryBacklinks
::class,
83 'blocks' => ApiQueryBlocks
::class,
84 'categorymembers' => ApiQueryCategoryMembers
::class,
85 'deletedrevs' => ApiQueryDeletedrevs
::class,
86 'embeddedin' => ApiQueryBacklinks
::class,
87 'exturlusage' => ApiQueryExtLinksUsage
::class,
88 'filearchive' => ApiQueryFilearchive
::class,
89 'imageusage' => ApiQueryBacklinks
::class,
90 'iwbacklinks' => ApiQueryIWBacklinks
::class,
91 'langbacklinks' => ApiQueryLangBacklinks
::class,
92 'logevents' => ApiQueryLogEvents
::class,
93 'pageswithprop' => ApiQueryPagesWithProp
::class,
94 'pagepropnames' => ApiQueryPagePropNames
::class,
95 'prefixsearch' => ApiQueryPrefixSearch
::class,
96 'protectedtitles' => ApiQueryProtectedTitles
::class,
97 'querypage' => ApiQueryQueryPage
::class,
98 'random' => ApiQueryRandom
::class,
99 'recentchanges' => ApiQueryRecentChanges
::class,
100 'search' => ApiQuerySearch
::class,
101 'tags' => ApiQueryTags
::class,
102 'usercontribs' => ApiQueryUserContribs
::class,
103 'users' => ApiQueryUsers
::class,
104 'watchlist' => ApiQueryWatchlist
::class,
105 'watchlistraw' => ApiQueryWatchlistRaw
::class,
109 * List of Api Query meta modules
112 private static $QueryMetaModules = [
113 'allmessages' => ApiQueryAllMessages
::class,
114 'authmanagerinfo' => ApiQueryAuthManagerInfo
::class,
115 'siteinfo' => ApiQuerySiteinfo
::class,
116 'userinfo' => ApiQueryUserInfo
::class,
117 'filerepoinfo' => ApiQueryFileRepoInfo
::class,
118 'tokens' => ApiQueryTokens
::class,
119 'languageinfo' => ApiQueryLanguageinfo
::class,
128 private $mNamedDB = [];
132 * @param ApiMain $main
133 * @param string $action
135 public function __construct( ApiMain
$main, $action ) {
136 parent
::__construct( $main, $action );
138 $this->mModuleMgr
= new ApiModuleManager(
140 MediaWikiServices
::getInstance()->getObjectFactory()
143 // Allow custom modules to be added in LocalSettings.php
144 $config = $this->getConfig();
145 $this->mModuleMgr
->addModules( self
::$QueryPropModules, 'prop' );
146 $this->mModuleMgr
->addModules( $config->get( 'APIPropModules' ), 'prop' );
147 $this->mModuleMgr
->addModules( self
::$QueryListModules, 'list' );
148 $this->mModuleMgr
->addModules( $config->get( 'APIListModules' ), 'list' );
149 $this->mModuleMgr
->addModules( self
::$QueryMetaModules, 'meta' );
150 $this->mModuleMgr
->addModules( $config->get( 'APIMetaModules' ), 'meta' );
152 Hooks
::run( 'ApiQuery::moduleManager', [ $this->mModuleMgr
] );
154 // Create PageSet that will process titles/pageids/revids/generator
155 $this->mPageSet
= new ApiPageSet( $this );
159 * Overrides to return this instance's module manager.
160 * @return ApiModuleManager
162 public function getModuleManager() {
163 return $this->mModuleMgr
;
167 * Get the query database connection with the given name.
168 * If no such connection has been requested before, it will be created.
169 * Subsequent calls with the same $name will return the same connection
170 * as the first, regardless of the values of $db and $groups
171 * @param string $name Name to assign to the database connection
172 * @param int $db One of the DB_* constants
173 * @param string|string[] $groups Query groups
176 public function getNamedDB( $name, $db, $groups ) {
177 if ( !array_key_exists( $name, $this->mNamedDB
) ) {
178 $this->mNamedDB
[$name] = wfGetDB( $db, $groups );
181 return $this->mNamedDB
[$name];
185 * Gets the set of pages the user has requested (or generated)
188 public function getPageSet() {
189 return $this->mPageSet
;
193 * @return ApiFormatRaw|null
195 public function getCustomPrinter() {
196 // If &exportnowrap is set, use the raw formatter
197 if ( $this->getParameter( 'export' ) &&
198 $this->getParameter( 'exportnowrap' )
200 return new ApiFormatRaw( $this->getMain(),
201 $this->getMain()->createPrinterByName( 'xml' ) );
208 * Query execution happens in the following steps:
209 * #1 Create a PageSet object with any pages requested by the user
210 * #2 If using a generator, execute it to get a new ApiPageSet object
211 * #3 Instantiate all requested modules.
212 * This way the PageSet object will know what shared data is required,
213 * and minimize DB calls.
214 * #4 Output all normalization and redirect resolution information
215 * #5 Execute all requested modules
217 public function execute() {
218 $this->mParams
= $this->extractRequestParams();
220 // Instantiate requested modules
222 $this->instantiateModules( $allModules, 'prop' );
223 $propModules = array_keys( $allModules );
224 $this->instantiateModules( $allModules, 'list' );
225 $this->instantiateModules( $allModules, 'meta' );
227 // Filter modules based on continue parameter
228 $continuationManager = new ApiContinuationManager( $this, $allModules, $propModules );
229 $this->setContinuationManager( $continuationManager );
230 /** @var ApiQueryBase[] $modules */
231 $modules = $continuationManager->getRunModules();
232 '@phan-var ApiQueryBase[] $modules';
234 if ( !$continuationManager->isGeneratorDone() ) {
235 // Query modules may optimize data requests through the $this->getPageSet()
236 // object by adding extra fields from the page table.
237 foreach ( $modules as $module ) {
238 $module->requestExtraData( $this->mPageSet
);
240 // Populate page/revision information
241 $this->mPageSet
->execute();
242 // Record page information (title, namespace, if exists, etc)
243 $this->outputGeneralPageInfo();
245 $this->mPageSet
->executeDryRun();
248 $cacheMode = $this->mPageSet
->getCacheMode();
250 // Execute all unfinished modules
251 foreach ( $modules as $module ) {
252 $params = $module->extractRequestParams();
253 $cacheMode = $this->mergeCacheMode(
254 $cacheMode, $module->getCacheMode( $params ) );
256 Hooks
::run( 'APIQueryAfterExecute', [ &$module ] );
259 // Set the cache mode
260 $this->getMain()->setCacheMode( $cacheMode );
262 // Write the continuation data into the result
263 $this->setContinuationManager( null );
264 if ( $this->mParams
['rawcontinue'] ) {
265 $data = $continuationManager->getRawNonContinuation();
267 $this->getResult()->addValue( null, 'query-noncontinue', $data,
268 ApiResult
::ADD_ON_TOP | ApiResult
::NO_SIZE_CHECK
);
270 $data = $continuationManager->getRawContinuation();
272 $this->getResult()->addValue( null, 'query-continue', $data,
273 ApiResult
::ADD_ON_TOP | ApiResult
::NO_SIZE_CHECK
);
276 $continuationManager->setContinuationIntoResult( $this->getResult() );
281 * Update a cache mode string, applying the cache mode of a new module to it.
282 * The cache mode may increase in the level of privacy, but public modules
283 * added to private data do not decrease the level of privacy.
285 * @param string $cacheMode
286 * @param string $modCacheMode
289 protected function mergeCacheMode( $cacheMode, $modCacheMode ) {
290 if ( $modCacheMode === 'anon-public-user-private' ) {
291 if ( $cacheMode !== 'private' ) {
292 $cacheMode = 'anon-public-user-private';
294 } elseif ( $modCacheMode === 'public' ) {
295 // do nothing, if it's public already it will stay public
297 $cacheMode = 'private';
304 * Create instances of all modules requested by the client
305 * @param array $modules To append instantiated modules to
306 * @param string $param Parameter name to read modules from
308 private function instantiateModules( &$modules, $param ) {
309 $wasPosted = $this->getRequest()->wasPosted();
310 if ( isset( $this->mParams
[$param] ) ) {
311 foreach ( $this->mParams
[$param] as $moduleName ) {
312 $instance = $this->mModuleMgr
->getModule( $moduleName, $param );
313 if ( $instance === null ) {
314 ApiBase
::dieDebug( __METHOD__
, 'Error instantiating module' );
316 if ( !$wasPosted && $instance->mustBePosted() ) {
317 $this->dieWithErrorOrDebug( [ 'apierror-mustbeposted', $moduleName ] );
319 // Ignore duplicates. TODO 2.0: die()?
320 if ( !array_key_exists( $moduleName, $modules ) ) {
321 $modules[$moduleName] = $instance;
328 * Appends an element for each page in the current pageSet with the
329 * most general information (id, title), plus any title normalizations
330 * and missing or invalid title/pageids/revids.
332 private function outputGeneralPageInfo() {
333 $pageSet = $this->getPageSet();
334 $result = $this->getResult();
336 // We can't really handle max-result-size failure here, but we need to
337 // check anyway in case someone set the limit stupidly low.
340 $values = $pageSet->getNormalizedTitlesAsResult( $result );
342 $fit = $fit && $result->addValue( 'query', 'normalized', $values );
344 $values = $pageSet->getConvertedTitlesAsResult( $result );
346 $fit = $fit && $result->addValue( 'query', 'converted', $values );
348 $values = $pageSet->getInterwikiTitlesAsResult( $result, $this->mParams
['iwurl'] );
350 $fit = $fit && $result->addValue( 'query', 'interwiki', $values );
352 $values = $pageSet->getRedirectTitlesAsResult( $result );
354 $fit = $fit && $result->addValue( 'query', 'redirects', $values );
356 $values = $pageSet->getMissingRevisionIDsAsResult( $result );
358 $fit = $fit && $result->addValue( 'query', 'badrevids', $values );
364 // Report any missing titles
365 foreach ( $pageSet->getMissingTitles() as $fakeId => $title ) {
367 ApiQueryBase
::addTitleInfo( $vals, $title );
368 $vals['missing'] = true;
369 if ( $title->isKnown() ) {
370 $vals['known'] = true;
372 $pages[$fakeId] = $vals;
374 // Report any invalid titles
375 foreach ( $pageSet->getInvalidTitlesAndReasons() as $fakeId => $data ) {
376 $pages[$fakeId] = $data +
[ 'invalid' => true ];
378 // Report any missing page ids
379 foreach ( $pageSet->getMissingPageIDs() as $pageid ) {
385 // Report special pages
386 /** @var Title $title */
387 foreach ( $pageSet->getSpecialTitles() as $fakeId => $title ) {
389 ApiQueryBase
::addTitleInfo( $vals, $title );
390 $vals['special'] = true;
391 if ( !$title->isKnown() ) {
392 $vals['missing'] = true;
394 $pages[$fakeId] = $vals;
397 // Output general page information for found titles
398 foreach ( $pageSet->getGoodTitles() as $pageid => $title ) {
400 $vals['pageid'] = $pageid;
401 ApiQueryBase
::addTitleInfo( $vals, $title );
402 $pages[$pageid] = $vals;
405 if ( count( $pages ) ) {
406 $pageSet->populateGeneratorData( $pages );
407 ApiResult
::setArrayType( $pages, 'BCarray' );
409 if ( $this->mParams
['indexpageids'] ) {
410 $pageIDs = array_keys( ApiResult
::stripMetadataNonRecursive( $pages ) );
411 // json treats all map keys as strings - converting to match
412 $pageIDs = array_map( 'strval', $pageIDs );
413 ApiResult
::setIndexedTagName( $pageIDs, 'id' );
414 $fit = $fit && $result->addValue( 'query', 'pageids', $pageIDs );
417 ApiResult
::setIndexedTagName( $pages, 'page' );
418 $fit = $fit && $result->addValue( 'query', 'pages', $pages );
422 $this->dieWithError( 'apierror-badconfig-resulttoosmall', 'badconfig' );
425 if ( $this->mParams
['export'] ) {
426 $this->doExport( $pageSet, $result );
431 * @param ApiPageSet $pageSet Pages to be exported
432 * @param ApiResult $result Result to output to
434 private function doExport( $pageSet, $result ) {
436 $titles = $pageSet->getGoodTitles();
437 if ( count( $titles ) ) {
438 /** @var Title $title */
439 foreach ( $titles as $title ) {
440 if ( $this->getPermissionManager()->userCan( 'read', $this->getUser(), $title ) ) {
441 $exportTitles[] = $title;
446 $exporter = new WikiExporter( $this->getDB() );
447 $sink = new DumpStringOutput
;
448 $exporter->setOutputSink( $sink );
449 $exporter->setSchemaVersion( $this->mParams
['exportschema'] );
450 $exporter->openStream();
451 foreach ( $exportTitles as $title ) {
452 $exporter->pageByTitle( $title );
454 $exporter->closeStream();
456 // Don't check the size of exported stuff
457 // It's not continuable, so it would cause more
458 // problems than it'd solve
459 if ( $this->mParams
['exportnowrap'] ) {
461 // Raw formatter will handle this
462 $result->addValue( null, 'text', $sink, ApiResult
::NO_SIZE_CHECK
);
463 $result->addValue( null, 'mime', 'text/xml', ApiResult
::NO_SIZE_CHECK
);
464 $result->addValue( null, 'filename', 'export.xml', ApiResult
::NO_SIZE_CHECK
);
466 $result->addValue( 'query', 'export', $sink, ApiResult
::NO_SIZE_CHECK
);
467 $result->addValue( 'query', ApiResult
::META_BC_SUBELEMENTS
, [ 'export' ] );
471 public function getAllowedParams( $flags = 0 ) {
474 ApiBase
::PARAM_ISMULTI
=> true,
475 ApiBase
::PARAM_TYPE
=> 'submodule',
478 ApiBase
::PARAM_ISMULTI
=> true,
479 ApiBase
::PARAM_TYPE
=> 'submodule',
482 ApiBase
::PARAM_ISMULTI
=> true,
483 ApiBase
::PARAM_TYPE
=> 'submodule',
485 'indexpageids' => false,
487 'exportnowrap' => false,
489 ApiBase
::PARAM_DFLT
=> WikiExporter
::schemaVersion(),
490 ApiBase
::PARAM_TYPE
=> XmlDumpWriter
::$supportedSchemas,
494 ApiBase
::PARAM_HELP_MSG
=> 'api-help-param-continue',
496 'rawcontinue' => false,
499 $result +
= $this->getPageSet()->getFinalParams( $flags );
505 public function isReadMode() {
506 // We need to make an exception for certain meta modules that should be
507 // accessible even without the 'read' right. Restrict the exception as
508 // much as possible: no other modules allowed, and no pageset
509 // parameters either. We do allow the 'rawcontinue' and 'indexpageids'
510 // parameters since frameworks might add these unconditionally and they
511 // can't expose anything here.
512 $this->mParams
= $this->extractRequestParams();
513 $params = array_filter(
515 $this->mParams +
$this->getPageSet()->extractRequestParams(),
516 [ 'rawcontinue' => 1, 'indexpageids' => 1 ]
519 if ( array_keys( $params ) !== [ 'meta' ] ) {
523 // Ask each module if it requires read mode. Any true => this returns
526 $this->instantiateModules( $modules, 'meta' );
527 foreach ( $modules as $module ) {
528 if ( $module->isReadMode() ) {
536 protected function getExamplesMessages() {
538 'action=query&prop=revisions&meta=siteinfo&' .
539 'titles=Main%20Page&rvprop=user|comment&continue='
540 => 'apihelp-query-example-revisions',
541 'action=query&generator=allpages&gapprefix=API/&prop=revisions&continue='
542 => 'apihelp-query-example-allpages',
546 public function getHelpUrls() {
548 'https://www.mediawiki.org/wiki/Special:MyLanguage/API:Query',
549 'https://www.mediawiki.org/wiki/Special:MyLanguage/API:Meta',
550 'https://www.mediawiki.org/wiki/Special:MyLanguage/API:Properties',
551 'https://www.mediawiki.org/wiki/Special:MyLanguage/API:Lists',