includes/api/ApiQuery.php

   1 <?php
   2 /**
   3  *
   4  *
   5  * Created on Sep 7, 2006
   6  *
   7  * Copyright © 2006 Yuri Astrakhan "<Firstname><Lastname>@gmail.com"
   8  *
   9  * This program is free software; you can redistribute it and/or modify
  10  * it under the terms of the GNU General Public License as published by
  11  * the Free Software Foundation; either version 2 of the License, or
  12  * (at your option) any later version.
  13  *
  14  * This program is distributed in the hope that it will be useful,
  15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  17  * GNU General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU General Public License along
  20  * with this program; if not, write to the Free Software Foundation, Inc.,
  21  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  22  * http://www.gnu.org/copyleft/gpl.html
  23  *
  24  * @file
  25  */
  26
  27 use Wikimedia\Rdbms\IDatabase;
  28
  29 /**
  30  * This is the main query class. It behaves similar to ApiMain: based on the
  31  * parameters given, it will create a list of titles to work on (an ApiPageSet
  32  * object), instantiate and execute various property/list/meta modules, and
  33  * assemble all resulting data into a single ApiResult object.
  34  *
  35  * In generator mode, a generator will be executed first to populate a second
  36  * ApiPageSet object, and that object will be used for all subsequent modules.
  37  *
  38  * @ingroup API
  39  */
  40 class ApiQuery extends ApiBase {
  41
  42         /**
  43          * List of Api Query prop modules
  44          * @var array
  45          */
  46         private static $QueryPropModules = [
  47                 'categories' => 'ApiQueryCategories',
  48                 'categoryinfo' => 'ApiQueryCategoryInfo',
  49                 'contributors' => 'ApiQueryContributors',
  50                 'deletedrevisions' => 'ApiQueryDeletedRevisions',
  51                 'duplicatefiles' => 'ApiQueryDuplicateFiles',
  52                 'extlinks' => 'ApiQueryExternalLinks',
  53                 'fileusage' => 'ApiQueryBacklinksprop',
  54                 'images' => 'ApiQueryImages',
  55                 'imageinfo' => 'ApiQueryImageInfo',
  56                 'info' => 'ApiQueryInfo',
  57                 'links' => 'ApiQueryLinks',
  58                 'linkshere' => 'ApiQueryBacklinksprop',
  59                 'iwlinks' => 'ApiQueryIWLinks',
  60                 'langlinks' => 'ApiQueryLangLinks',
  61                 'pageprops' => 'ApiQueryPageProps',
  62                 'redirects' => 'ApiQueryBacklinksprop',
  63                 'revisions' => 'ApiQueryRevisions',
  64                 'stashimageinfo' => 'ApiQueryStashImageInfo',
  65                 'templates' => 'ApiQueryLinks',
  66                 'transcludedin' => 'ApiQueryBacklinksprop',
  67         ];
  68
  69         /**
  70          * List of Api Query list modules
  71          * @var array
  72          */
  73         private static $QueryListModules = [
  74                 'allcategories' => 'ApiQueryAllCategories',
  75                 'alldeletedrevisions' => 'ApiQueryAllDeletedRevisions',
  76                 'allfileusages' => 'ApiQueryAllLinks',
  77                 'allimages' => 'ApiQueryAllImages',
  78                 'alllinks' => 'ApiQueryAllLinks',
  79                 'allpages' => 'ApiQueryAllPages',
  80                 'allredirects' => 'ApiQueryAllLinks',
  81                 'allrevisions' => 'ApiQueryAllRevisions',
  82                 'mystashedfiles' => 'ApiQueryMyStashedFiles',
  83                 'alltransclusions' => 'ApiQueryAllLinks',
  84                 'allusers' => 'ApiQueryAllUsers',
  85                 'backlinks' => 'ApiQueryBacklinks',
  86                 'blocks' => 'ApiQueryBlocks',
  87                 'categorymembers' => 'ApiQueryCategoryMembers',
  88                 'deletedrevs' => 'ApiQueryDeletedrevs',
  89                 'embeddedin' => 'ApiQueryBacklinks',
  90                 'exturlusage' => 'ApiQueryExtLinksUsage',
  91                 'filearchive' => 'ApiQueryFilearchive',
  92                 'imageusage' => 'ApiQueryBacklinks',
  93                 'iwbacklinks' => 'ApiQueryIWBacklinks',
  94                 'langbacklinks' => 'ApiQueryLangBacklinks',
  95                 'logevents' => 'ApiQueryLogEvents',
  96                 'pageswithprop' => 'ApiQueryPagesWithProp',
  97                 'pagepropnames' => 'ApiQueryPagePropNames',
  98                 'prefixsearch' => 'ApiQueryPrefixSearch',
  99                 'protectedtitles' => 'ApiQueryProtectedTitles',
 100                 'querypage' => 'ApiQueryQueryPage',
 101                 'random' => 'ApiQueryRandom',
 102                 'recentchanges' => 'ApiQueryRecentChanges',
 103                 'search' => 'ApiQuerySearch',
 104                 'tags' => 'ApiQueryTags',
 105                 'usercontribs' => 'ApiQueryContributions',
 106                 'users' => 'ApiQueryUsers',
 107                 'watchlist' => 'ApiQueryWatchlist',
 108                 'watchlistraw' => 'ApiQueryWatchlistRaw',
 109         ];
 110
 111         /**
 112          * List of Api Query meta modules
 113          * @var array
 114          */
 115         private static $QueryMetaModules = [
 116                 'allmessages' => 'ApiQueryAllMessages',
 117                 'authmanagerinfo' => 'ApiQueryAuthManagerInfo',
 118                 'siteinfo' => 'ApiQuerySiteinfo',
 119                 'userinfo' => 'ApiQueryUserInfo',
 120                 'filerepoinfo' => 'ApiQueryFileRepoInfo',
 121                 'tokens' => 'ApiQueryTokens',
 122         ];
 123
 124         /**
 125          * @var ApiPageSet
 126          */
 127         private $mPageSet;
 128
 129         private $mParams;
 130         private $mNamedDB = [];
 131         private $mModuleMgr;
 132
 133         /**
 134          * @param ApiMain $main
 135          * @param string $action
 136          */
 137         public function __construct( ApiMain $main, $action ) {
 138                 parent::__construct( $main, $action );
 139
 140                 $this->mModuleMgr = new ApiModuleManager( $this );
 141
 142                 // Allow custom modules to be added in LocalSettings.php
 143                 $config = $this->getConfig();
 144                 $this->mModuleMgr->addModules( self::$QueryPropModules, 'prop' );
 145                 $this->mModuleMgr->addModules( $config->get( 'APIPropModules' ), 'prop' );
 146                 $this->mModuleMgr->addModules( self::$QueryListModules, 'list' );
 147                 $this->mModuleMgr->addModules( $config->get( 'APIListModules' ), 'list' );
 148                 $this->mModuleMgr->addModules( self::$QueryMetaModules, 'meta' );
 149                 $this->mModuleMgr->addModules( $config->get( 'APIMetaModules' ), 'meta' );
 150
 151                 Hooks::run( 'ApiQuery::moduleManager', [ $this->mModuleMgr ] );
 152
 153                 // Create PageSet that will process titles/pageids/revids/generator
 154                 $this->mPageSet = new ApiPageSet( $this );
 155         }
 156
 157         /**
 158          * Overrides to return this instance's module manager.
 159          * @return ApiModuleManager
 160          */
 161         public function getModuleManager() {
 162                 return $this->mModuleMgr;
 163         }
 164
 165         /**
 166          * Get the query database connection with the given name.
 167          * If no such connection has been requested before, it will be created.
 168          * Subsequent calls with the same $name will return the same connection
 169          * as the first, regardless of the values of $db and $groups
 170          * @param string $name Name to assign to the database connection
 171          * @param int $db One of the DB_* constants
 172          * @param string|string[] $groups Query groups
 173          * @return IDatabase
 174          */
 175         public function getNamedDB( $name, $db, $groups ) {
 176                 if ( !array_key_exists( $name, $this->mNamedDB ) ) {
 177                         $this->mNamedDB[$name] = wfGetDB( $db, $groups );
 178                 }
 179
 180                 return $this->mNamedDB[$name];
 181         }
 182
 183         /**
 184          * Gets the set of pages the user has requested (or generated)
 185          * @return ApiPageSet
 186          */
 187         public function getPageSet() {
 188                 return $this->mPageSet;
 189         }
 190
 191         /**
 192          * @return ApiFormatRaw|null
 193          */
 194         public function getCustomPrinter() {
 195                 // If &exportnowrap is set, use the raw formatter
 196                 if ( $this->getParameter( 'export' ) &&
 197                         $this->getParameter( 'exportnowrap' )
 198                 ) {
 199                         return new ApiFormatRaw( $this->getMain(),
 200                                 $this->getMain()->createPrinterByName( 'xml' ) );
 201                 } else {
 202                         return null;
 203                 }
 204         }
 205
 206         /**
 207          * Query execution happens in the following steps:
 208          * #1 Create a PageSet object with any pages requested by the user
 209          * #2 If using a generator, execute it to get a new ApiPageSet object
 210          * #3 Instantiate all requested modules.
 211          *    This way the PageSet object will know what shared data is required,
 212          *    and minimize DB calls.
 213          * #4 Output all normalization and redirect resolution information
 214          * #5 Execute all requested modules
 215          */
 216         public function execute() {
 217                 $this->mParams = $this->extractRequestParams();
 218
 219                 // Instantiate requested modules
 220                 $allModules = [];
 221                 $this->instantiateModules( $allModules, 'prop' );
 222                 $propModules = array_keys( $allModules );
 223                 $this->instantiateModules( $allModules, 'list' );
 224                 $this->instantiateModules( $allModules, 'meta' );
 225
 226                 // Filter modules based on continue parameter
 227                 $continuationManager = new ApiContinuationManager( $this, $allModules, $propModules );
 228                 $this->setContinuationManager( $continuationManager );
 229                 $modules = $continuationManager->getRunModules();
 230
 231                 if ( !$continuationManager->isGeneratorDone() ) {
 232                         // Query modules may optimize data requests through the $this->getPageSet()
 233                         // object by adding extra fields from the page table.
 234                         foreach ( $modules as $module ) {
 235                                 $module->requestExtraData( $this->mPageSet );
 236                         }
 237                         // Populate page/revision information
 238                         $this->mPageSet->execute();
 239                         // Record page information (title, namespace, if exists, etc)
 240                         $this->outputGeneralPageInfo();
 241                 } else {
 242                         $this->mPageSet->executeDryRun();
 243                 }
 244
 245                 $cacheMode = $this->mPageSet->getCacheMode();
 246
 247                 // Execute all unfinished modules
 248                 /** @var ApiQueryBase $module */
 249                 foreach ( $modules as $module ) {
 250                         $params = $module->extractRequestParams();
 251                         $cacheMode = $this->mergeCacheMode(
 252                                 $cacheMode, $module->getCacheMode( $params ) );
 253                         $module->execute();
 254                         Hooks::run( 'APIQueryAfterExecute', [ &$module ] );
 255                 }
 256
 257                 // Set the cache mode
 258                 $this->getMain()->setCacheMode( $cacheMode );
 259
 260                 // Write the continuation data into the result
 261                 $this->setContinuationManager( null );
 262                 if ( $this->mParams['rawcontinue'] ) {
 263                         $data = $continuationManager->getRawNonContinuation();
 264                         if ( $data ) {
 265                                 $this->getResult()->addValue( null, 'query-noncontinue', $data,
 266                                         ApiResult::ADD_ON_TOP | ApiResult::NO_SIZE_CHECK );
 267                         }
 268                         $data = $continuationManager->getRawContinuation();
 269                         if ( $data ) {
 270                                 $this->getResult()->addValue( null, 'query-continue', $data,
 271                                         ApiResult::ADD_ON_TOP | ApiResult::NO_SIZE_CHECK );
 272                         }
 273                 } else {
 274                         $continuationManager->setContinuationIntoResult( $this->getResult() );
 275                 }
 276         }
 277
 278         /**
 279          * Update a cache mode string, applying the cache mode of a new module to it.
 280          * The cache mode may increase in the level of privacy, but public modules
 281          * added to private data do not decrease the level of privacy.
 282          *
 283          * @param string $cacheMode
 284          * @param string $modCacheMode
 285          * @return string
 286          */
 287         protected function mergeCacheMode( $cacheMode, $modCacheMode ) {
 288                 if ( $modCacheMode === 'anon-public-user-private' ) {
 289                         if ( $cacheMode !== 'private' ) {
 290                                 $cacheMode = 'anon-public-user-private';
 291                         }
 292                 } elseif ( $modCacheMode === 'public' ) {
 293                         // do nothing, if it's public already it will stay public
 294                 } else { // private
 295                         $cacheMode = 'private';
 296                 }
 297
 298                 return $cacheMode;
 299         }
 300
 301         /**
 302          * Create instances of all modules requested by the client
 303          * @param array $modules To append instantiated modules to
 304          * @param string $param Parameter name to read modules from
 305          */
 306         private function instantiateModules( &$modules, $param ) {
 307                 $wasPosted = $this->getRequest()->wasPosted();
 308                 if ( isset( $this->mParams[$param] ) ) {
 309                         foreach ( $this->mParams[$param] as $moduleName ) {
 310                                 $instance = $this->mModuleMgr->getModule( $moduleName, $param );
 311                                 if ( $instance === null ) {
 312                                         ApiBase::dieDebug( __METHOD__, 'Error instantiating module' );
 313                                 }
 314                                 if ( !$wasPosted && $instance->mustBePosted() ) {
 315                                         $this->dieWithErrorOrDebug( [ 'apierror-mustbeposted', $moduleName ] );
 316                                 }
 317                                 // Ignore duplicates. TODO 2.0: die()?
 318                                 if ( !array_key_exists( $moduleName, $modules ) ) {
 319                                         $modules[$moduleName] = $instance;
 320                                 }
 321                         }
 322                 }
 323         }
 324
 325         /**
 326          * Appends an element for each page in the current pageSet with the
 327          * most general information (id, title), plus any title normalizations
 328          * and missing or invalid title/pageids/revids.
 329          */
 330         private function outputGeneralPageInfo() {
 331                 $pageSet = $this->getPageSet();
 332                 $result = $this->getResult();
 333
 334                 // We can't really handle max-result-size failure here, but we need to
 335                 // check anyway in case someone set the limit stupidly low.
 336                 $fit = true;
 337
 338                 $values = $pageSet->getNormalizedTitlesAsResult( $result );
 339                 if ( $values ) {
 340                         $fit = $fit && $result->addValue( 'query', 'normalized', $values );
 341                 }
 342                 $values = $pageSet->getConvertedTitlesAsResult( $result );
 343                 if ( $values ) {
 344                         $fit = $fit && $result->addValue( 'query', 'converted', $values );
 345                 }
 346                 $values = $pageSet->getInterwikiTitlesAsResult( $result, $this->mParams['iwurl'] );
 347                 if ( $values ) {
 348                         $fit = $fit && $result->addValue( 'query', 'interwiki', $values );
 349                 }
 350                 $values = $pageSet->getRedirectTitlesAsResult( $result );
 351                 if ( $values ) {
 352                         $fit = $fit && $result->addValue( 'query', 'redirects', $values );
 353                 }
 354                 $values = $pageSet->getMissingRevisionIDsAsResult( $result );
 355                 if ( $values ) {
 356                         $fit = $fit && $result->addValue( 'query', 'badrevids', $values );
 357                 }
 358
 359                 // Page elements
 360                 $pages = [];
 361
 362                 // Report any missing titles
 363                 foreach ( $pageSet->getMissingTitles() as $fakeId => $title ) {
 364                         $vals = [];
 365                         ApiQueryBase::addTitleInfo( $vals, $title );
 366                         $vals['missing'] = true;
 367                         if ( $title->isKnown() ) {
 368                                 $vals['known'] = true;
 369                         }
 370                         $pages[$fakeId] = $vals;
 371                 }
 372                 // Report any invalid titles
 373                 foreach ( $pageSet->getInvalidTitlesAndReasons() as $fakeId => $data ) {
 374                         $pages[$fakeId] = $data + [ 'invalid' => true ];
 375                 }
 376                 // Report any missing page ids
 377                 foreach ( $pageSet->getMissingPageIDs() as $pageid ) {
 378                         $pages[$pageid] = [
 379                                 'pageid' => $pageid,
 380                                 'missing' => true,
 381                         ];
 382                 }
 383                 // Report special pages
 384                 /** @var Title $title */
 385                 foreach ( $pageSet->getSpecialTitles() as $fakeId => $title ) {
 386                         $vals = [];
 387                         ApiQueryBase::addTitleInfo( $vals, $title );
 388                         $vals['special'] = true;
 389                         if ( !$title->isKnown() ) {
 390                                 $vals['missing'] = true;
 391                         }
 392                         $pages[$fakeId] = $vals;
 393                 }
 394
 395                 // Output general page information for found titles
 396                 foreach ( $pageSet->getGoodTitles() as $pageid => $title ) {
 397                         $vals = [];
 398                         $vals['pageid'] = $pageid;
 399                         ApiQueryBase::addTitleInfo( $vals, $title );
 400                         $pages[$pageid] = $vals;
 401                 }
 402
 403                 if ( count( $pages ) ) {
 404                         $pageSet->populateGeneratorData( $pages );
 405                         ApiResult::setArrayType( $pages, 'BCarray' );
 406
 407                         if ( $this->mParams['indexpageids'] ) {
 408                                 $pageIDs = array_keys( ApiResult::stripMetadataNonRecursive( $pages ) );
 409                                 // json treats all map keys as strings - converting to match
 410                                 $pageIDs = array_map( 'strval', $pageIDs );
 411                                 ApiResult::setIndexedTagName( $pageIDs, 'id' );
 412                                 $fit = $fit && $result->addValue( 'query', 'pageids', $pageIDs );
 413                         }
 414
 415                         ApiResult::setIndexedTagName( $pages, 'page' );
 416                         $fit = $fit && $result->addValue( 'query', 'pages', $pages );
 417                 }
 418
 419                 if ( !$fit ) {
 420                         $this->dieWithError( 'apierror-badconfig-resulttoosmall', 'badconfig' );
 421                 }
 422
 423                 if ( $this->mParams['export'] ) {
 424                         $this->doExport( $pageSet, $result );
 425                 }
 426         }
 427
 428         /**
 429          * @param ApiPageSet $pageSet Pages to be exported
 430          * @param ApiResult $result Result to output to
 431          */
 432         private function doExport( $pageSet, $result ) {
 433                 $exportTitles = [];
 434                 $titles = $pageSet->getGoodTitles();
 435                 if ( count( $titles ) ) {
 436                         $user = $this->getUser();
 437                         /** @var Title $title */
 438                         foreach ( $titles as $title ) {
 439                                 if ( $title->userCan( 'read', $user ) ) {
 440                                         $exportTitles[] = $title;
 441                                 }
 442                         }
 443                 }
 444
 445                 $exporter = new WikiExporter( $this->getDB() );
 446                 $sink = new DumpStringOutput;
 447                 $exporter->setOutputSink( $sink );
 448                 $exporter->openStream();
 449                 foreach ( $exportTitles as $title ) {
 450                         $exporter->pageByTitle( $title );
 451                 }
 452                 $exporter->closeStream();
 453
 454                 // Don't check the size of exported stuff
 455                 // It's not continuable, so it would cause more
 456                 // problems than it'd solve
 457                 if ( $this->mParams['exportnowrap'] ) {
 458                         $result->reset();
 459                         // Raw formatter will handle this
 460                         $result->addValue( null, 'text', $sink, ApiResult::NO_SIZE_CHECK );
 461                         $result->addValue( null, 'mime', 'text/xml', ApiResult::NO_SIZE_CHECK );
 462                 } else {
 463                         $result->addValue( 'query', 'export', $sink, ApiResult::NO_SIZE_CHECK );
 464                         $result->addValue( 'query', ApiResult::META_BC_SUBELEMENTS, [ 'export' ] );
 465                 }
 466         }
 467
 468         public function getAllowedParams( $flags = 0 ) {
 469                 $result = [
 470                         'prop' => [
 471                                 ApiBase::PARAM_ISMULTI => true,
 472                                 ApiBase::PARAM_TYPE => 'submodule',
 473                         ],
 474                         'list' => [
 475                                 ApiBase::PARAM_ISMULTI => true,
 476                                 ApiBase::PARAM_TYPE => 'submodule',
 477                         ],
 478                         'meta' => [
 479                                 ApiBase::PARAM_ISMULTI => true,
 480                                 ApiBase::PARAM_TYPE => 'submodule',
 481                         ],
 482                         'indexpageids' => false,
 483                         'export' => false,
 484                         'exportnowrap' => false,
 485                         'iwurl' => false,
 486                         'continue' => [
 487                                 ApiBase::PARAM_HELP_MSG => 'api-help-param-continue',
 488                         ],
 489                         'rawcontinue' => false,
 490                 ];
 491                 if ( $flags ) {
 492                         $result += $this->getPageSet()->getFinalParams( $flags );
 493                 }
 494
 495                 return $result;
 496         }
 497
 498         public function isReadMode() {
 499                 // We need to make an exception for certain meta modules that should be
 500                 // accessible even without the 'read' right. Restrict the exception as
 501                 // much as possible: no other modules allowed, and no pageset
 502                 // parameters either. We do allow the 'rawcontinue' and 'indexpageids'
 503                 // parameters since frameworks might add these unconditionally and they
 504                 // can't expose anything here.
 505                 $this->mParams = $this->extractRequestParams();
 506                 $params = array_filter(
 507                         array_diff_key(
 508                                 $this->mParams + $this->getPageSet()->extractRequestParams(),
 509                                 [ 'rawcontinue' => 1, 'indexpageids' => 1 ]
 510                         )
 511                 );
 512                 if ( array_keys( $params ) !== [ 'meta' ] ) {
 513                         return true;
 514                 }
 515
 516                 // Ask each module if it requires read mode. Any true => this returns
 517                 // true.
 518                 $modules = [];
 519                 $this->instantiateModules( $modules, 'meta' );
 520                 foreach ( $modules as $module ) {
 521                         if ( $module->isReadMode() ) {
 522                                 return true;
 523                         }
 524                 }
 525
 526                 return false;
 527         }
 528
 529         protected function getExamplesMessages() {
 530                 return [
 531                         'action=query&prop=revisions&meta=siteinfo&' .
 532                                 'titles=Main%20Page&rvprop=user|comment&continue='
 533                                 => 'apihelp-query-example-revisions',
 534                         'action=query&generator=allpages&gapprefix=API/&prop=revisions&continue='
 535                                 => 'apihelp-query-example-allpages',
 536                 ];
 537         }
 538
 539         public function getHelpUrls() {
 540                 return [
 541                         'https://www.mediawiki.org/wiki/Special:MyLanguage/API:Query',
 542                         'https://www.mediawiki.org/wiki/Special:MyLanguage/API:Meta',
 543                         'https://www.mediawiki.org/wiki/Special:MyLanguage/API:Properties',
 544                         'https://www.mediawiki.org/wiki/Special:MyLanguage/API:Lists',
 545                 ];
 546         }
 547 }