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 Wikimedia\Rdbms\IDatabase
;
26 * This is the main query class. It behaves similar to ApiMain: based on the
27 * parameters given, it will create a list of titles to work on (an ApiPageSet
28 * object), instantiate and execute various property/list/meta modules, and
29 * assemble all resulting data into a single ApiResult object.
31 * In generator mode, a generator will be executed first to populate a second
32 * ApiPageSet object, and that object will be used for all subsequent modules.
36 class ApiQuery
extends ApiBase
{
39 * List of Api Query prop modules
42 private static $QueryPropModules = [
43 'categories' => ApiQueryCategories
::class,
44 'categoryinfo' => ApiQueryCategoryInfo
::class,
45 'contributors' => ApiQueryContributors
::class,
46 'deletedrevisions' => ApiQueryDeletedRevisions
::class,
47 'duplicatefiles' => ApiQueryDuplicateFiles
::class,
48 'extlinks' => ApiQueryExternalLinks
::class,
49 'fileusage' => ApiQueryBacklinksprop
::class,
50 'images' => ApiQueryImages
::class,
51 'imageinfo' => ApiQueryImageInfo
::class,
52 'info' => ApiQueryInfo
::class,
53 'links' => ApiQueryLinks
::class,
54 'linkshere' => ApiQueryBacklinksprop
::class,
55 'iwlinks' => ApiQueryIWLinks
::class,
56 'langlinks' => ApiQueryLangLinks
::class,
57 'pageprops' => ApiQueryPageProps
::class,
58 'redirects' => ApiQueryBacklinksprop
::class,
59 'revisions' => ApiQueryRevisions
::class,
60 'stashimageinfo' => ApiQueryStashImageInfo
::class,
61 'templates' => ApiQueryLinks
::class,
62 'transcludedin' => ApiQueryBacklinksprop
::class,
66 * List of Api Query list modules
69 private static $QueryListModules = [
70 'allcategories' => ApiQueryAllCategories
::class,
71 'alldeletedrevisions' => ApiQueryAllDeletedRevisions
::class,
72 'allfileusages' => ApiQueryAllLinks
::class,
73 'allimages' => ApiQueryAllImages
::class,
74 'alllinks' => ApiQueryAllLinks
::class,
75 'allpages' => ApiQueryAllPages
::class,
76 'allredirects' => ApiQueryAllLinks
::class,
77 'allrevisions' => ApiQueryAllRevisions
::class,
78 'mystashedfiles' => ApiQueryMyStashedFiles
::class,
79 'alltransclusions' => ApiQueryAllLinks
::class,
80 'allusers' => ApiQueryAllUsers
::class,
81 'backlinks' => ApiQueryBacklinks
::class,
82 'blocks' => ApiQueryBlocks
::class,
83 'categorymembers' => ApiQueryCategoryMembers
::class,
84 'deletedrevs' => ApiQueryDeletedrevs
::class,
85 'embeddedin' => ApiQueryBacklinks
::class,
86 'exturlusage' => ApiQueryExtLinksUsage
::class,
87 'filearchive' => ApiQueryFilearchive
::class,
88 'imageusage' => ApiQueryBacklinks
::class,
89 'iwbacklinks' => ApiQueryIWBacklinks
::class,
90 'langbacklinks' => ApiQueryLangBacklinks
::class,
91 'logevents' => ApiQueryLogEvents
::class,
92 'pageswithprop' => ApiQueryPagesWithProp
::class,
93 'pagepropnames' => ApiQueryPagePropNames
::class,
94 'prefixsearch' => ApiQueryPrefixSearch
::class,
95 'protectedtitles' => ApiQueryProtectedTitles
::class,
96 'querypage' => ApiQueryQueryPage
::class,
97 'random' => ApiQueryRandom
::class,
98 'recentchanges' => ApiQueryRecentChanges
::class,
99 'search' => ApiQuerySearch
::class,
100 'tags' => ApiQueryTags
::class,
101 'usercontribs' => ApiQueryUserContribs
::class,
102 'users' => ApiQueryUsers
::class,
103 'watchlist' => ApiQueryWatchlist
::class,
104 'watchlistraw' => ApiQueryWatchlistRaw
::class,
108 * List of Api Query meta modules
111 private static $QueryMetaModules = [
112 'allmessages' => ApiQueryAllMessages
::class,
113 'authmanagerinfo' => ApiQueryAuthManagerInfo
::class,
114 'siteinfo' => ApiQuerySiteinfo
::class,
115 'userinfo' => ApiQueryUserInfo
::class,
116 'filerepoinfo' => ApiQueryFileRepoInfo
::class,
117 'tokens' => ApiQueryTokens
::class,
118 'languageinfo' => ApiQueryLanguageinfo
::class,
127 private $mNamedDB = [];
131 * @param ApiMain $main
132 * @param string $action
134 public function __construct( ApiMain
$main, $action ) {
135 parent
::__construct( $main, $action );
137 $this->mModuleMgr
= new ApiModuleManager( $this );
139 // Allow custom modules to be added in LocalSettings.php
140 $config = $this->getConfig();
141 $this->mModuleMgr
->addModules( self
::$QueryPropModules, 'prop' );
142 $this->mModuleMgr
->addModules( $config->get( 'APIPropModules' ), 'prop' );
143 $this->mModuleMgr
->addModules( self
::$QueryListModules, 'list' );
144 $this->mModuleMgr
->addModules( $config->get( 'APIListModules' ), 'list' );
145 $this->mModuleMgr
->addModules( self
::$QueryMetaModules, 'meta' );
146 $this->mModuleMgr
->addModules( $config->get( 'APIMetaModules' ), 'meta' );
148 Hooks
::run( 'ApiQuery::moduleManager', [ $this->mModuleMgr
] );
150 // Create PageSet that will process titles/pageids/revids/generator
151 $this->mPageSet
= new ApiPageSet( $this );
155 * Overrides to return this instance's module manager.
156 * @return ApiModuleManager
158 public function getModuleManager() {
159 return $this->mModuleMgr
;
163 * Get the query database connection with the given name.
164 * If no such connection has been requested before, it will be created.
165 * Subsequent calls with the same $name will return the same connection
166 * as the first, regardless of the values of $db and $groups
167 * @param string $name Name to assign to the database connection
168 * @param int $db One of the DB_* constants
169 * @param string|string[] $groups Query groups
172 public function getNamedDB( $name, $db, $groups ) {
173 if ( !array_key_exists( $name, $this->mNamedDB
) ) {
174 $this->mNamedDB
[$name] = wfGetDB( $db, $groups );
177 return $this->mNamedDB
[$name];
181 * Gets the set of pages the user has requested (or generated)
184 public function getPageSet() {
185 return $this->mPageSet
;
189 * @return ApiFormatRaw|null
191 public function getCustomPrinter() {
192 // If &exportnowrap is set, use the raw formatter
193 if ( $this->getParameter( 'export' ) &&
194 $this->getParameter( 'exportnowrap' )
196 return new ApiFormatRaw( $this->getMain(),
197 $this->getMain()->createPrinterByName( 'xml' ) );
204 * Query execution happens in the following steps:
205 * #1 Create a PageSet object with any pages requested by the user
206 * #2 If using a generator, execute it to get a new ApiPageSet object
207 * #3 Instantiate all requested modules.
208 * This way the PageSet object will know what shared data is required,
209 * and minimize DB calls.
210 * #4 Output all normalization and redirect resolution information
211 * #5 Execute all requested modules
213 public function execute() {
214 $this->mParams
= $this->extractRequestParams();
216 // Instantiate requested modules
218 $this->instantiateModules( $allModules, 'prop' );
219 $propModules = array_keys( $allModules );
220 $this->instantiateModules( $allModules, 'list' );
221 $this->instantiateModules( $allModules, 'meta' );
223 // Filter modules based on continue parameter
224 $continuationManager = new ApiContinuationManager( $this, $allModules, $propModules );
225 $this->setContinuationManager( $continuationManager );
226 /** @var ApiQueryBase[] $modules */
227 $modules = $continuationManager->getRunModules();
228 '@phan-var ApiQueryBase[] $modules';
230 if ( !$continuationManager->isGeneratorDone() ) {
231 // Query modules may optimize data requests through the $this->getPageSet()
232 // object by adding extra fields from the page table.
233 foreach ( $modules as $module ) {
234 $module->requestExtraData( $this->mPageSet
);
236 // Populate page/revision information
237 $this->mPageSet
->execute();
238 // Record page information (title, namespace, if exists, etc)
239 $this->outputGeneralPageInfo();
241 $this->mPageSet
->executeDryRun();
244 $cacheMode = $this->mPageSet
->getCacheMode();
246 // Execute all unfinished modules
247 foreach ( $modules as $module ) {
248 $params = $module->extractRequestParams();
249 $cacheMode = $this->mergeCacheMode(
250 $cacheMode, $module->getCacheMode( $params ) );
252 Hooks
::run( 'APIQueryAfterExecute', [ &$module ] );
255 // Set the cache mode
256 $this->getMain()->setCacheMode( $cacheMode );
258 // Write the continuation data into the result
259 $this->setContinuationManager( null );
260 if ( $this->mParams
['rawcontinue'] ) {
261 $data = $continuationManager->getRawNonContinuation();
263 $this->getResult()->addValue( null, 'query-noncontinue', $data,
264 ApiResult
::ADD_ON_TOP | ApiResult
::NO_SIZE_CHECK
);
266 $data = $continuationManager->getRawContinuation();
268 $this->getResult()->addValue( null, 'query-continue', $data,
269 ApiResult
::ADD_ON_TOP | ApiResult
::NO_SIZE_CHECK
);
272 $continuationManager->setContinuationIntoResult( $this->getResult() );
277 * Update a cache mode string, applying the cache mode of a new module to it.
278 * The cache mode may increase in the level of privacy, but public modules
279 * added to private data do not decrease the level of privacy.
281 * @param string $cacheMode
282 * @param string $modCacheMode
285 protected function mergeCacheMode( $cacheMode, $modCacheMode ) {
286 if ( $modCacheMode === 'anon-public-user-private' ) {
287 if ( $cacheMode !== 'private' ) {
288 $cacheMode = 'anon-public-user-private';
290 } elseif ( $modCacheMode === 'public' ) {
291 // do nothing, if it's public already it will stay public
293 $cacheMode = 'private';
300 * Create instances of all modules requested by the client
301 * @param array $modules To append instantiated modules to
302 * @param string $param Parameter name to read modules from
304 private function instantiateModules( &$modules, $param ) {
305 $wasPosted = $this->getRequest()->wasPosted();
306 if ( isset( $this->mParams
[$param] ) ) {
307 foreach ( $this->mParams
[$param] as $moduleName ) {
308 $instance = $this->mModuleMgr
->getModule( $moduleName, $param );
309 if ( $instance === null ) {
310 ApiBase
::dieDebug( __METHOD__
, 'Error instantiating module' );
312 if ( !$wasPosted && $instance->mustBePosted() ) {
313 $this->dieWithErrorOrDebug( [ 'apierror-mustbeposted', $moduleName ] );
315 // Ignore duplicates. TODO 2.0: die()?
316 if ( !array_key_exists( $moduleName, $modules ) ) {
317 $modules[$moduleName] = $instance;
324 * Appends an element for each page in the current pageSet with the
325 * most general information (id, title), plus any title normalizations
326 * and missing or invalid title/pageids/revids.
328 private function outputGeneralPageInfo() {
329 $pageSet = $this->getPageSet();
330 $result = $this->getResult();
332 // We can't really handle max-result-size failure here, but we need to
333 // check anyway in case someone set the limit stupidly low.
336 $values = $pageSet->getNormalizedTitlesAsResult( $result );
338 $fit = $fit && $result->addValue( 'query', 'normalized', $values );
340 $values = $pageSet->getConvertedTitlesAsResult( $result );
342 $fit = $fit && $result->addValue( 'query', 'converted', $values );
344 $values = $pageSet->getInterwikiTitlesAsResult( $result, $this->mParams
['iwurl'] );
346 $fit = $fit && $result->addValue( 'query', 'interwiki', $values );
348 $values = $pageSet->getRedirectTitlesAsResult( $result );
350 $fit = $fit && $result->addValue( 'query', 'redirects', $values );
352 $values = $pageSet->getMissingRevisionIDsAsResult( $result );
354 $fit = $fit && $result->addValue( 'query', 'badrevids', $values );
360 // Report any missing titles
361 foreach ( $pageSet->getMissingTitles() as $fakeId => $title ) {
363 ApiQueryBase
::addTitleInfo( $vals, $title );
364 $vals['missing'] = true;
365 if ( $title->isKnown() ) {
366 $vals['known'] = true;
368 $pages[$fakeId] = $vals;
370 // Report any invalid titles
371 foreach ( $pageSet->getInvalidTitlesAndReasons() as $fakeId => $data ) {
372 $pages[$fakeId] = $data +
[ 'invalid' => true ];
374 // Report any missing page ids
375 foreach ( $pageSet->getMissingPageIDs() as $pageid ) {
381 // Report special pages
382 /** @var Title $title */
383 foreach ( $pageSet->getSpecialTitles() as $fakeId => $title ) {
385 ApiQueryBase
::addTitleInfo( $vals, $title );
386 $vals['special'] = true;
387 if ( !$title->isKnown() ) {
388 $vals['missing'] = true;
390 $pages[$fakeId] = $vals;
393 // Output general page information for found titles
394 foreach ( $pageSet->getGoodTitles() as $pageid => $title ) {
396 $vals['pageid'] = $pageid;
397 ApiQueryBase
::addTitleInfo( $vals, $title );
398 $pages[$pageid] = $vals;
401 if ( count( $pages ) ) {
402 $pageSet->populateGeneratorData( $pages );
403 ApiResult
::setArrayType( $pages, 'BCarray' );
405 if ( $this->mParams
['indexpageids'] ) {
406 $pageIDs = array_keys( ApiResult
::stripMetadataNonRecursive( $pages ) );
407 // json treats all map keys as strings - converting to match
408 $pageIDs = array_map( 'strval', $pageIDs );
409 ApiResult
::setIndexedTagName( $pageIDs, 'id' );
410 $fit = $fit && $result->addValue( 'query', 'pageids', $pageIDs );
413 ApiResult
::setIndexedTagName( $pages, 'page' );
414 $fit = $fit && $result->addValue( 'query', 'pages', $pages );
418 $this->dieWithError( 'apierror-badconfig-resulttoosmall', 'badconfig' );
421 if ( $this->mParams
['export'] ) {
422 $this->doExport( $pageSet, $result );
427 * @param ApiPageSet $pageSet Pages to be exported
428 * @param ApiResult $result Result to output to
430 private function doExport( $pageSet, $result ) {
432 $titles = $pageSet->getGoodTitles();
433 if ( count( $titles ) ) {
434 /** @var Title $title */
435 foreach ( $titles as $title ) {
436 if ( $this->getPermissionManager()->userCan( 'read', $this->getUser(), $title ) ) {
437 $exportTitles[] = $title;
442 $exporter = new WikiExporter( $this->getDB() );
443 $sink = new DumpStringOutput
;
444 $exporter->setOutputSink( $sink );
445 $exporter->setSchemaVersion( $this->mParams
['exportschema'] );
446 $exporter->openStream();
447 foreach ( $exportTitles as $title ) {
448 $exporter->pageByTitle( $title );
450 $exporter->closeStream();
452 // Don't check the size of exported stuff
453 // It's not continuable, so it would cause more
454 // problems than it'd solve
455 if ( $this->mParams
['exportnowrap'] ) {
457 // Raw formatter will handle this
458 $result->addValue( null, 'text', $sink, ApiResult
::NO_SIZE_CHECK
);
459 $result->addValue( null, 'mime', 'text/xml', ApiResult
::NO_SIZE_CHECK
);
460 $result->addValue( null, 'filename', 'export.xml', ApiResult
::NO_SIZE_CHECK
);
462 $result->addValue( 'query', 'export', $sink, ApiResult
::NO_SIZE_CHECK
);
463 $result->addValue( 'query', ApiResult
::META_BC_SUBELEMENTS
, [ 'export' ] );
467 public function getAllowedParams( $flags = 0 ) {
470 ApiBase
::PARAM_ISMULTI
=> true,
471 ApiBase
::PARAM_TYPE
=> 'submodule',
474 ApiBase
::PARAM_ISMULTI
=> true,
475 ApiBase
::PARAM_TYPE
=> 'submodule',
478 ApiBase
::PARAM_ISMULTI
=> true,
479 ApiBase
::PARAM_TYPE
=> 'submodule',
481 'indexpageids' => false,
483 'exportnowrap' => false,
485 ApiBase
::PARAM_DFLT
=> WikiExporter
::schemaVersion(),
486 ApiBase
::PARAM_TYPE
=> XmlDumpWriter
::$supportedSchemas,
490 ApiBase
::PARAM_HELP_MSG
=> 'api-help-param-continue',
492 'rawcontinue' => false,
495 $result +
= $this->getPageSet()->getFinalParams( $flags );
501 public function isReadMode() {
502 // We need to make an exception for certain meta modules that should be
503 // accessible even without the 'read' right. Restrict the exception as
504 // much as possible: no other modules allowed, and no pageset
505 // parameters either. We do allow the 'rawcontinue' and 'indexpageids'
506 // parameters since frameworks might add these unconditionally and they
507 // can't expose anything here.
508 $this->mParams
= $this->extractRequestParams();
509 $params = array_filter(
511 $this->mParams +
$this->getPageSet()->extractRequestParams(),
512 [ 'rawcontinue' => 1, 'indexpageids' => 1 ]
515 if ( array_keys( $params ) !== [ 'meta' ] ) {
519 // Ask each module if it requires read mode. Any true => this returns
522 $this->instantiateModules( $modules, 'meta' );
523 foreach ( $modules as $module ) {
524 if ( $module->isReadMode() ) {
532 protected function getExamplesMessages() {
534 'action=query&prop=revisions&meta=siteinfo&' .
535 'titles=Main%20Page&rvprop=user|comment&continue='
536 => 'apihelp-query-example-revisions',
537 'action=query&generator=allpages&gapprefix=API/&prop=revisions&continue='
538 => 'apihelp-query-example-allpages',
542 public function getHelpUrls() {
544 'https://www.mediawiki.org/wiki/Special:MyLanguage/API:Query',
545 'https://www.mediawiki.org/wiki/Special:MyLanguage/API:Meta',
546 'https://www.mediawiki.org/wiki/Special:MyLanguage/API:Properties',
547 'https://www.mediawiki.org/wiki/Special:MyLanguage/API:Lists',