includes/api/ApiQuery.php

   1 <?php
   2 /**
   3  * Copyright © 2006 Yuri Astrakhan "<Firstname><Lastname>@gmail.com"
   4  *
   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.
   9  *
  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.
  14  *
  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
  19  *
  20  * @file
  21  */
  22
  23 use Wikimedia\Rdbms\IDatabase;
  24
  25 /**
  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.
  30  *
  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.
  33  *
  34  * @ingroup API
  35  */
  36 class ApiQuery extends ApiBase {
  37
  38         /**
  39          * List of Api Query prop modules
  40          * @var array
  41          */
  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,
  63         ];
  64
  65         /**
  66          * List of Api Query list modules
  67          * @var array
  68          */
  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,
 105         ];
 106
 107         /**
 108          * List of Api Query meta modules
 109          * @var array
 110          */
 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,
 119         ];
 120
 121         /**
 122          * @var ApiPageSet
 123          */
 124         private $mPageSet;
 125
 126         private $mParams;
 127         private $mNamedDB = [];
 128         private $mModuleMgr;
 129
 130         /**
 131          * @param ApiMain $main
 132          * @param string $action
 133          */
 134         public function __construct( ApiMain $main, $action ) {
 135                 parent::__construct( $main, $action );
 136
 137                 $this->mModuleMgr = new ApiModuleManager( $this );
 138
 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' );
 147
 148                 Hooks::run( 'ApiQuery::moduleManager', [ $this->mModuleMgr ] );
 149
 150                 // Create PageSet that will process titles/pageids/revids/generator
 151                 $this->mPageSet = new ApiPageSet( $this );
 152         }
 153
 154         /**
 155          * Overrides to return this instance's module manager.
 156          * @return ApiModuleManager
 157          */
 158         public function getModuleManager() {
 159                 return $this->mModuleMgr;
 160         }
 161
 162         /**
 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
 170          * @return IDatabase
 171          */
 172         public function getNamedDB( $name, $db, $groups ) {
 173                 if ( !array_key_exists( $name, $this->mNamedDB ) ) {
 174                         $this->mNamedDB[$name] = wfGetDB( $db, $groups );
 175                 }
 176
 177                 return $this->mNamedDB[$name];
 178         }
 179
 180         /**
 181          * Gets the set of pages the user has requested (or generated)
 182          * @return ApiPageSet
 183          */
 184         public function getPageSet() {
 185                 return $this->mPageSet;
 186         }
 187
 188         /**
 189          * @return ApiFormatRaw|null
 190          */
 191         public function getCustomPrinter() {
 192                 // If &exportnowrap is set, use the raw formatter
 193                 if ( $this->getParameter( 'export' ) &&
 194                         $this->getParameter( 'exportnowrap' )
 195                 ) {
 196                         return new ApiFormatRaw( $this->getMain(),
 197                                 $this->getMain()->createPrinterByName( 'xml' ) );
 198                 } else {
 199                         return null;
 200                 }
 201         }
 202
 203         /**
 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
 212          */
 213         public function execute() {
 214                 $this->mParams = $this->extractRequestParams();
 215
 216                 // Instantiate requested modules
 217                 $allModules = [];
 218                 $this->instantiateModules( $allModules, 'prop' );
 219                 $propModules = array_keys( $allModules );
 220                 $this->instantiateModules( $allModules, 'list' );
 221                 $this->instantiateModules( $allModules, 'meta' );
 222
 223                 // Filter modules based on continue parameter
 224                 $continuationManager = new ApiContinuationManager( $this, $allModules, $propModules );
 225                 $this->setContinuationManager( $continuationManager );
 226                 $modules = $continuationManager->getRunModules();
 227
 228                 if ( !$continuationManager->isGeneratorDone() ) {
 229                         // Query modules may optimize data requests through the $this->getPageSet()
 230                         // object by adding extra fields from the page table.
 231                         foreach ( $modules as $module ) {
 232                                 $module->requestExtraData( $this->mPageSet );
 233                         }
 234                         // Populate page/revision information
 235                         $this->mPageSet->execute();
 236                         // Record page information (title, namespace, if exists, etc)
 237                         $this->outputGeneralPageInfo();
 238                 } else {
 239                         $this->mPageSet->executeDryRun();
 240                 }
 241
 242                 $cacheMode = $this->mPageSet->getCacheMode();
 243
 244                 // Execute all unfinished modules
 245                 /** @var ApiQueryBase $module */
 246                 foreach ( $modules as $module ) {
 247                         $params = $module->extractRequestParams();
 248                         $cacheMode = $this->mergeCacheMode(
 249                                 $cacheMode, $module->getCacheMode( $params ) );
 250                         $module->execute();
 251                         Hooks::run( 'APIQueryAfterExecute', [ &$module ] );
 252                 }
 253
 254                 // Set the cache mode
 255                 $this->getMain()->setCacheMode( $cacheMode );
 256
 257                 // Write the continuation data into the result
 258                 $this->setContinuationManager( null );
 259                 if ( $this->mParams['rawcontinue'] ) {
 260                         $data = $continuationManager->getRawNonContinuation();
 261                         if ( $data ) {
 262                                 $this->getResult()->addValue( null, 'query-noncontinue', $data,
 263                                         ApiResult::ADD_ON_TOP | ApiResult::NO_SIZE_CHECK );
 264                         }
 265                         $data = $continuationManager->getRawContinuation();
 266                         if ( $data ) {
 267                                 $this->getResult()->addValue( null, 'query-continue', $data,
 268                                         ApiResult::ADD_ON_TOP | ApiResult::NO_SIZE_CHECK );
 269                         }
 270                 } else {
 271                         $continuationManager->setContinuationIntoResult( $this->getResult() );
 272                 }
 273         }
 274
 275         /**
 276          * Update a cache mode string, applying the cache mode of a new module to it.
 277          * The cache mode may increase in the level of privacy, but public modules
 278          * added to private data do not decrease the level of privacy.
 279          *
 280          * @param string $cacheMode
 281          * @param string $modCacheMode
 282          * @return string
 283          */
 284         protected function mergeCacheMode( $cacheMode, $modCacheMode ) {
 285                 if ( $modCacheMode === 'anon-public-user-private' ) {
 286                         if ( $cacheMode !== 'private' ) {
 287                                 $cacheMode = 'anon-public-user-private';
 288                         }
 289                 } elseif ( $modCacheMode === 'public' ) {
 290                         // do nothing, if it's public already it will stay public
 291                 } else {
 292                         $cacheMode = 'private';
 293                 }
 294
 295                 return $cacheMode;
 296         }
 297
 298         /**
 299          * Create instances of all modules requested by the client
 300          * @param array $modules To append instantiated modules to
 301          * @param string $param Parameter name to read modules from
 302          */
 303         private function instantiateModules( &$modules, $param ) {
 304                 $wasPosted = $this->getRequest()->wasPosted();
 305                 if ( isset( $this->mParams[$param] ) ) {
 306                         foreach ( $this->mParams[$param] as $moduleName ) {
 307                                 $instance = $this->mModuleMgr->getModule( $moduleName, $param );
 308                                 if ( $instance === null ) {
 309                                         ApiBase::dieDebug( __METHOD__, 'Error instantiating module' );
 310                                 }
 311                                 if ( !$wasPosted && $instance->mustBePosted() ) {
 312                                         $this->dieWithErrorOrDebug( [ 'apierror-mustbeposted', $moduleName ] );
 313                                 }
 314                                 // Ignore duplicates. TODO 2.0: die()?
 315                                 if ( !array_key_exists( $moduleName, $modules ) ) {
 316                                         $modules[$moduleName] = $instance;
 317                                 }
 318                         }
 319                 }
 320         }
 321
 322         /**
 323          * Appends an element for each page in the current pageSet with the
 324          * most general information (id, title), plus any title normalizations
 325          * and missing or invalid title/pageids/revids.
 326          */
 327         private function outputGeneralPageInfo() {
 328                 $pageSet = $this->getPageSet();
 329                 $result = $this->getResult();
 330
 331                 // We can't really handle max-result-size failure here, but we need to
 332                 // check anyway in case someone set the limit stupidly low.
 333                 $fit = true;
 334
 335                 $values = $pageSet->getNormalizedTitlesAsResult( $result );
 336                 if ( $values ) {
 337                         $fit = $fit && $result->addValue( 'query', 'normalized', $values );
 338                 }
 339                 $values = $pageSet->getConvertedTitlesAsResult( $result );
 340                 if ( $values ) {
 341                         $fit = $fit && $result->addValue( 'query', 'converted', $values );
 342                 }
 343                 $values = $pageSet->getInterwikiTitlesAsResult( $result, $this->mParams['iwurl'] );
 344                 if ( $values ) {
 345                         $fit = $fit && $result->addValue( 'query', 'interwiki', $values );
 346                 }
 347                 $values = $pageSet->getRedirectTitlesAsResult( $result );
 348                 if ( $values ) {
 349                         $fit = $fit && $result->addValue( 'query', 'redirects', $values );
 350                 }
 351                 $values = $pageSet->getMissingRevisionIDsAsResult( $result );
 352                 if ( $values ) {
 353                         $fit = $fit && $result->addValue( 'query', 'badrevids', $values );
 354                 }
 355
 356                 // Page elements
 357                 $pages = [];
 358
 359                 // Report any missing titles
 360                 foreach ( $pageSet->getMissingTitles() as $fakeId => $title ) {
 361                         $vals = [];
 362                         ApiQueryBase::addTitleInfo( $vals, $title );
 363                         $vals['missing'] = true;
 364                         if ( $title->isKnown() ) {
 365                                 $vals['known'] = true;
 366                         }
 367                         $pages[$fakeId] = $vals;
 368                 }
 369                 // Report any invalid titles
 370                 foreach ( $pageSet->getInvalidTitlesAndReasons() as $fakeId => $data ) {
 371                         $pages[$fakeId] = $data + [ 'invalid' => true ];
 372                 }
 373                 // Report any missing page ids
 374                 foreach ( $pageSet->getMissingPageIDs() as $pageid ) {
 375                         $pages[$pageid] = [
 376                                 'pageid' => $pageid,
 377                                 'missing' => true,
 378                         ];
 379                 }
 380                 // Report special pages
 381                 /** @var Title $title */
 382                 foreach ( $pageSet->getSpecialTitles() as $fakeId => $title ) {
 383                         $vals = [];
 384                         ApiQueryBase::addTitleInfo( $vals, $title );
 385                         $vals['special'] = true;
 386                         if ( !$title->isKnown() ) {
 387                                 $vals['missing'] = true;
 388                         }
 389                         $pages[$fakeId] = $vals;
 390                 }
 391
 392                 // Output general page information for found titles
 393                 foreach ( $pageSet->getGoodTitles() as $pageid => $title ) {
 394                         $vals = [];
 395                         $vals['pageid'] = $pageid;
 396                         ApiQueryBase::addTitleInfo( $vals, $title );
 397                         $pages[$pageid] = $vals;
 398                 }
 399
 400                 if ( count( $pages ) ) {
 401                         $pageSet->populateGeneratorData( $pages );
 402                         ApiResult::setArrayType( $pages, 'BCarray' );
 403
 404                         if ( $this->mParams['indexpageids'] ) {
 405                                 $pageIDs = array_keys( ApiResult::stripMetadataNonRecursive( $pages ) );
 406                                 // json treats all map keys as strings - converting to match
 407                                 $pageIDs = array_map( 'strval', $pageIDs );
 408                                 ApiResult::setIndexedTagName( $pageIDs, 'id' );
 409                                 $fit = $fit && $result->addValue( 'query', 'pageids', $pageIDs );
 410                         }
 411
 412                         ApiResult::setIndexedTagName( $pages, 'page' );
 413                         $fit = $fit && $result->addValue( 'query', 'pages', $pages );
 414                 }
 415
 416                 if ( !$fit ) {
 417                         $this->dieWithError( 'apierror-badconfig-resulttoosmall', 'badconfig' );
 418                 }
 419
 420                 if ( $this->mParams['export'] ) {
 421                         $this->doExport( $pageSet, $result );
 422                 }
 423         }
 424
 425         /**
 426          * @param ApiPageSet $pageSet Pages to be exported
 427          * @param ApiResult $result Result to output to
 428          */
 429         private function doExport( $pageSet, $result ) {
 430                 $exportTitles = [];
 431                 $titles = $pageSet->getGoodTitles();
 432                 if ( count( $titles ) ) {
 433                         /** @var Title $title */
 434                         foreach ( $titles as $title ) {
 435                                 if ( $this->getPermissionManager()->userCan( 'read', $this->getUser(), $title ) ) {
 436                                         $exportTitles[] = $title;
 437                                 }
 438                         }
 439                 }
 440
 441                 $exporter = new WikiExporter( $this->getDB() );
 442                 $sink = new DumpStringOutput;
 443                 $exporter->setOutputSink( $sink );
 444                 $exporter->setSchemaVersion( $this->mParams['exportschema'] );
 445                 $exporter->openStream();
 446                 foreach ( $exportTitles as $title ) {
 447                         $exporter->pageByTitle( $title );
 448                 }
 449                 $exporter->closeStream();
 450
 451                 // Don't check the size of exported stuff
 452                 // It's not continuable, so it would cause more
 453                 // problems than it'd solve
 454                 if ( $this->mParams['exportnowrap'] ) {
 455                         $result->reset();
 456                         // Raw formatter will handle this
 457                         $result->addValue( null, 'text', $sink, ApiResult::NO_SIZE_CHECK );
 458                         $result->addValue( null, 'mime', 'text/xml', ApiResult::NO_SIZE_CHECK );
 459                         $result->addValue( null, 'filename', 'export.xml', ApiResult::NO_SIZE_CHECK );
 460                 } else {
 461                         $result->addValue( 'query', 'export', $sink, ApiResult::NO_SIZE_CHECK );
 462                         $result->addValue( 'query', ApiResult::META_BC_SUBELEMENTS, [ 'export' ] );
 463                 }
 464         }
 465
 466         public function getAllowedParams( $flags = 0 ) {
 467                 $result = [
 468                         'prop' => [
 469                                 ApiBase::PARAM_ISMULTI => true,
 470                                 ApiBase::PARAM_TYPE => 'submodule',
 471                         ],
 472                         'list' => [
 473                                 ApiBase::PARAM_ISMULTI => true,
 474                                 ApiBase::PARAM_TYPE => 'submodule',
 475                         ],
 476                         'meta' => [
 477                                 ApiBase::PARAM_ISMULTI => true,
 478                                 ApiBase::PARAM_TYPE => 'submodule',
 479                         ],
 480                         'indexpageids' => false,
 481                         'export' => false,
 482                         'exportnowrap' => false,
 483                         'exportschema' => [
 484                                 ApiBase::PARAM_DFLT => WikiExporter::schemaVersion(),
 485                                 ApiBase::PARAM_TYPE => XmlDumpWriter::$supportedSchemas,
 486                         ],
 487                         'iwurl' => false,
 488                         'continue' => [
 489                                 ApiBase::PARAM_HELP_MSG => 'api-help-param-continue',
 490                         ],
 491                         'rawcontinue' => false,
 492                 ];
 493                 if ( $flags ) {
 494                         $result += $this->getPageSet()->getFinalParams( $flags );
 495                 }
 496
 497                 return $result;
 498         }
 499
 500         public function isReadMode() {
 501                 // We need to make an exception for certain meta modules that should be
 502                 // accessible even without the 'read' right. Restrict the exception as
 503                 // much as possible: no other modules allowed, and no pageset
 504                 // parameters either. We do allow the 'rawcontinue' and 'indexpageids'
 505                 // parameters since frameworks might add these unconditionally and they
 506                 // can't expose anything here.
 507                 $this->mParams = $this->extractRequestParams();
 508                 $params = array_filter(
 509                         array_diff_key(
 510                                 $this->mParams + $this->getPageSet()->extractRequestParams(),
 511                                 [ 'rawcontinue' => 1, 'indexpageids' => 1 ]
 512                         )
 513                 );
 514                 if ( array_keys( $params ) !== [ 'meta' ] ) {
 515                         return true;
 516                 }
 517
 518                 // Ask each module if it requires read mode. Any true => this returns
 519                 // true.
 520                 $modules = [];
 521                 $this->instantiateModules( $modules, 'meta' );
 522                 foreach ( $modules as $module ) {
 523                         if ( $module->isReadMode() ) {
 524                                 return true;
 525                         }
 526                 }
 527
 528                 return false;
 529         }
 530
 531         protected function getExamplesMessages() {
 532                 return [
 533                         'action=query&prop=revisions&meta=siteinfo&' .
 534                                 'titles=Main%20Page&rvprop=user|comment&continue='
 535                                 => 'apihelp-query-example-revisions',
 536                         'action=query&generator=allpages&gapprefix=API/&prop=revisions&continue='
 537                                 => 'apihelp-query-example-allpages',
 538                 ];
 539         }
 540
 541         public function getHelpUrls() {
 542                 return [
 543                         'https://www.mediawiki.org/wiki/Special:MyLanguage/API:Query',
 544                         'https://www.mediawiki.org/wiki/Special:MyLanguage/API:Meta',
 545                         'https://www.mediawiki.org/wiki/Special:MyLanguage/API:Properties',
 546                         'https://www.mediawiki.org/wiki/Special:MyLanguage/API:Lists',
 547                 ];
 548         }
 549 }