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 /**
  28  * This is the main query class. It behaves similar to ApiMain: based on the
  29  * parameters given, it will create a list of titles to work on (an ApiPageSet
  30  * object), instantiate and execute various property/list/meta modules, and
  31  * assemble all resulting data into a single ApiResult object.
  32  *
  33  * In generator mode, a generator will be executed first to populate a second
  34  * ApiPageSet object, and that object will be used for all subsequent modules.
  35  *
  36  * @ingroup API
  37  */
  38 class ApiQuery extends ApiBase {
  39
  40         /**
  41          * List of Api Query prop modules
  42          * @var array
  43          */
  44         private static $QueryPropModules = array(
  45                 'categories' => 'ApiQueryCategories',
  46                 'categoryinfo' => 'ApiQueryCategoryInfo',
  47                 'duplicatefiles' => 'ApiQueryDuplicateFiles',
  48                 'extlinks' => 'ApiQueryExternalLinks',
  49                 'images' => 'ApiQueryImages',
  50                 'imageinfo' => 'ApiQueryImageInfo',
  51                 'info' => 'ApiQueryInfo',
  52                 'links' => 'ApiQueryLinks',
  53                 'iwlinks' => 'ApiQueryIWLinks',
  54                 'langlinks' => 'ApiQueryLangLinks',
  55                 'pageprops' => 'ApiQueryPageProps',
  56                 'revisions' => 'ApiQueryRevisions',
  57                 'stashimageinfo' => 'ApiQueryStashImageInfo',
  58                 'templates' => 'ApiQueryLinks',
  59         );
  60
  61         /**
  62          * List of Api Query list modules
  63          * @var array
  64          */
  65         private static $QueryListModules = array(
  66                 'allcategories' => 'ApiQueryAllCategories',
  67                 'allimages' => 'ApiQueryAllImages',
  68                 'alllinks' => 'ApiQueryAllLinks',
  69                 'allpages' => 'ApiQueryAllPages',
  70                 'alltransclusions' => 'ApiQueryAllLinks',
  71                 'allusers' => 'ApiQueryAllUsers',
  72                 'backlinks' => 'ApiQueryBacklinks',
  73                 'blocks' => 'ApiQueryBlocks',
  74                 'categorymembers' => 'ApiQueryCategoryMembers',
  75                 'deletedrevs' => 'ApiQueryDeletedrevs',
  76                 'embeddedin' => 'ApiQueryBacklinks',
  77                 'exturlusage' => 'ApiQueryExtLinksUsage',
  78                 'filearchive' => 'ApiQueryFilearchive',
  79                 'imageusage' => 'ApiQueryBacklinks',
  80                 'iwbacklinks' => 'ApiQueryIWBacklinks',
  81                 'langbacklinks' => 'ApiQueryLangBacklinks',
  82                 'logevents' => 'ApiQueryLogEvents',
  83                 'pageswithprop' => 'ApiQueryPagesWithProp',
  84                 'pagepropnames' => 'ApiQueryPagePropNames',
  85                 'protectedtitles' => 'ApiQueryProtectedTitles',
  86                 'querypage' => 'ApiQueryQueryPage',
  87                 'random' => 'ApiQueryRandom',
  88                 'recentchanges' => 'ApiQueryRecentChanges',
  89                 'search' => 'ApiQuerySearch',
  90                 'tags' => 'ApiQueryTags',
  91                 'usercontribs' => 'ApiQueryContributions',
  92                 'users' => 'ApiQueryUsers',
  93                 'watchlist' => 'ApiQueryWatchlist',
  94                 'watchlistraw' => 'ApiQueryWatchlistRaw',
  95         );
  96
  97         /**
  98          * List of Api Query meta modules
  99          * @var array
 100          */
 101         private static $QueryMetaModules = array(
 102                 'allmessages' => 'ApiQueryAllMessages',
 103                 'siteinfo' => 'ApiQuerySiteinfo',
 104                 'userinfo' => 'ApiQueryUserInfo',
 105         );
 106
 107         /**
 108          * @var ApiPageSet
 109          */
 110         private $mPageSet;
 111
 112         private $params;
 113         private $iwUrl;
 114         private $mNamedDB = array();
 115         private $mModuleMgr;
 116
 117         /**
 118          * @param $main ApiMain
 119          * @param $action string
 120          */
 121         public function __construct( $main, $action ) {
 122                 parent::__construct( $main, $action );
 123
 124                 $this->mModuleMgr = new ApiModuleManager( $this );
 125
 126                 // Allow custom modules to be added in LocalSettings.php
 127                 global $wgAPIPropModules, $wgAPIListModules, $wgAPIMetaModules;
 128                 $this->mModuleMgr->addModules( self::$QueryPropModules, 'prop' );
 129                 $this->mModuleMgr->addModules( $wgAPIPropModules, 'prop' );
 130                 $this->mModuleMgr->addModules( self::$QueryListModules, 'list' );
 131                 $this->mModuleMgr->addModules( $wgAPIListModules, 'list' );
 132                 $this->mModuleMgr->addModules( self::$QueryMetaModules, 'meta' );
 133                 $this->mModuleMgr->addModules( $wgAPIMetaModules, 'meta' );
 134
 135                 // Create PageSet that will process titles/pageids/revids/generator
 136                 $this->mPageSet = new ApiPageSet( $this );
 137         }
 138
 139         /**
 140          * Overrides to return this instance's module manager.
 141          * @return ApiModuleManager
 142          */
 143         public function getModuleManager() {
 144                 return $this->mModuleMgr;
 145         }
 146
 147         /**
 148          * Get the query database connection with the given name.
 149          * If no such connection has been requested before, it will be created.
 150          * Subsequent calls with the same $name will return the same connection
 151          * as the first, regardless of the values of $db and $groups
 152          * @param $name string Name to assign to the database connection
 153          * @param $db int One of the DB_* constants
 154          * @param $groups array Query groups
 155          * @return DatabaseBase
 156          */
 157         public function getNamedDB( $name, $db, $groups ) {
 158                 if ( !array_key_exists( $name, $this->mNamedDB ) ) {
 159                         $this->profileDBIn();
 160                         $this->mNamedDB[$name] = wfGetDB( $db, $groups );
 161                         $this->profileDBOut();
 162                 }
 163                 return $this->mNamedDB[$name];
 164         }
 165
 166         /**
 167          * Gets the set of pages the user has requested (or generated)
 168          * @return ApiPageSet
 169          */
 170         public function getPageSet() {
 171                 return $this->mPageSet;
 172         }
 173
 174         /**
 175          * Get the array mapping module names to class names
 176          * @deprecated since 1.21, use getModuleManager()'s methods instead
 177          * @return array array(modulename => classname)
 178          */
 179         public function getModules() {
 180                 wfDeprecated( __METHOD__, '1.21' );
 181                 return $this->getModuleManager()->getNamesWithClasses();
 182         }
 183
 184         /**
 185          * Get the generators array mapping module names to class names
 186          * @deprecated since 1.21, list of generators is maintained by ApiPageSet
 187          * @return array array(modulename => classname)
 188          */
 189         public function getGenerators() {
 190                 wfDeprecated( __METHOD__, '1.21' );
 191                 $gens = array();
 192                 foreach ( $this->mModuleMgr->getNamesWithClasses() as $name => $class ) {
 193                         if ( is_subclass_of( $class, 'ApiQueryGeneratorBase' ) ) {
 194                                 $gens[$name] = $class;
 195                         }
 196                 }
 197                 return $gens;
 198         }
 199
 200         /**
 201          * Get whether the specified module is a prop, list or a meta query module
 202          * @deprecated since 1.21, use getModuleManager()->getModuleGroup()
 203          * @param $moduleName string Name of the module to find type for
 204          * @return mixed string or null
 205          */
 206         function getModuleType( $moduleName ) {
 207                 return $this->getModuleManager()->getModuleGroup( $moduleName );
 208         }
 209
 210         /**
 211          * @return ApiFormatRaw|null
 212          */
 213         public function getCustomPrinter() {
 214                 // If &exportnowrap is set, use the raw formatter
 215                 if ( $this->getParameter( 'export' ) &&
 216                                 $this->getParameter( 'exportnowrap' ) )
 217                 {
 218                         return new ApiFormatRaw( $this->getMain(),
 219                                 $this->getMain()->createPrinterByName( 'xml' ) );
 220                 } else {
 221                         return null;
 222                 }
 223         }
 224
 225         /**
 226          * Query execution happens in the following steps:
 227          * #1 Create a PageSet object with any pages requested by the user
 228          * #2 If using a generator, execute it to get a new ApiPageSet object
 229          * #3 Instantiate all requested modules.
 230          *    This way the PageSet object will know what shared data is required,
 231          *    and minimize DB calls.
 232          * #4 Output all normalization and redirect resolution information
 233          * #5 Execute all requested modules
 234          */
 235         public function execute() {
 236                 $this->params = $this->extractRequestParams();
 237                 $this->iwUrl = $this->params['iwurl'];
 238
 239                 // Instantiate requested modules
 240                 $modules = array();
 241                 $this->instantiateModules( $modules, 'prop' );
 242                 $this->instantiateModules( $modules, 'list' );
 243                 $this->instantiateModules( $modules, 'meta' );
 244
 245                 // Query modules may optimize data requests through the $this->getPageSet()
 246                 // object by adding extra fields from the page table.
 247                 // This function will gather all the extra request fields from the modules.
 248                 foreach ( $modules as $module ) {
 249                         if ( !$this->getRequest()->wasPosted() && $module->mustBePosted() ) {
 250                                 $this->dieUsageMsgOrDebug( array( 'mustbeposted', $module->getModuleName() ) );
 251                         }
 252
 253                         $module->requestExtraData( $this->mPageSet );
 254                 }
 255
 256                 // Populate page/revision information
 257                 $this->mPageSet->execute();
 258                 $cacheMode = $this->mPageSet->getCacheMode();
 259
 260                 // Record page information (title, namespace, if exists, etc)
 261                 $this->outputGeneralPageInfo();
 262
 263                 // Execute all requested modules.
 264                 /**
 265                  * @var $module ApiQueryBase
 266                  */
 267                 foreach ( $modules as $module ) {
 268                         $params = $module->extractRequestParams();
 269                         $cacheMode = $this->mergeCacheMode(
 270                                 $cacheMode, $module->getCacheMode( $params ) );
 271                         $module->profileIn();
 272                         $module->execute();
 273                         wfRunHooks( 'APIQueryAfterExecute', array( &$module ) );
 274                         $module->profileOut();
 275                 }
 276
 277                 // Set the cache mode
 278                 $this->getMain()->setCacheMode( $cacheMode );
 279         }
 280
 281         /**
 282          * Update a cache mode string, applying the cache mode of a new module to it.
 283          * The cache mode may increase in the level of privacy, but public modules
 284          * added to private data do not decrease the level of privacy.
 285          *
 286          * @param $cacheMode string
 287          * @param $modCacheMode string
 288          * @return string
 289          */
 290         protected function mergeCacheMode( $cacheMode, $modCacheMode ) {
 291                 if ( $modCacheMode === 'anon-public-user-private' ) {
 292                         if ( $cacheMode !== 'private' ) {
 293                                 $cacheMode = 'anon-public-user-private';
 294                         }
 295                 } elseif ( $modCacheMode === 'public' ) {
 296                         // do nothing, if it's public already it will stay public
 297                 } else { // private
 298                         $cacheMode = 'private';
 299                 }
 300                 return $cacheMode;
 301         }
 302
 303         /**
 304          * Create instances of all modules requested by the client
 305          * @param $modules Array to append instantiated modules to
 306          * @param $param string Parameter name to read modules from
 307          */
 308         private function instantiateModules( &$modules, $param ) {
 309                 if ( isset( $this->params[$param] ) ) {
 310                         foreach ( $this->params[$param] as $moduleName ) {
 311                                 $modules[] = $this->mModuleMgr->getModule( $moduleName );
 312                         }
 313                 }
 314         }
 315
 316         /**
 317          * Appends an element for each page in the current pageSet with the
 318          * most general information (id, title), plus any title normalizations
 319          * and missing or invalid title/pageids/revids.
 320          */
 321         private function outputGeneralPageInfo() {
 322                 $pageSet = $this->getPageSet();
 323                 $result = $this->getResult();
 324
 325                 // We don't check for a full result set here because we can't be adding
 326                 // more than 380K. The maximum revision size is in the megabyte range,
 327                 // and the maximum result size must be even higher than that.
 328
 329                 $values = $pageSet->getNormalizedTitlesAsResult( $result );
 330                 if ( $values ) {
 331                         $result->addValue( 'query', 'normalized', $values );
 332                 }
 333                 $values = $pageSet->getConvertedTitlesAsResult( $result );
 334                 if ( $values ) {
 335                         $result->addValue( 'query', 'converted', $values );
 336                 }
 337                 $values = $pageSet->getInterwikiTitlesAsResult( $result, $this->iwUrl );
 338                 if ( $values ) {
 339                         $result->addValue( 'query', 'interwiki', $values );
 340                 }
 341                 $values = $pageSet->getRedirectTitlesAsResult( $result );
 342                 if ( $values ) {
 343                         $result->addValue( 'query', 'redirects', $values );
 344                 }
 345                 $values = $pageSet->getMissingRevisionIDsAsResult( $result );
 346                 if ( $values ) {
 347                         $result->addValue( 'query', 'badrevids', $values );
 348                 }
 349
 350                 // Page elements
 351                 $pages = array();
 352
 353                 // Report any missing titles
 354                 foreach ( $pageSet->getMissingTitles() as $fakeId => $title ) {
 355                         $vals = array();
 356                         ApiQueryBase::addTitleInfo( $vals, $title );
 357                         $vals['missing'] = '';
 358                         $pages[$fakeId] = $vals;
 359                 }
 360                 // Report any invalid titles
 361                 foreach ( $pageSet->getInvalidTitles() as $fakeId => $title ) {
 362                         $pages[$fakeId] = array( 'title' => $title, 'invalid' => '' );
 363                 }
 364                 // Report any missing page ids
 365                 foreach ( $pageSet->getMissingPageIDs() as $pageid ) {
 366                         $pages[$pageid] = array(
 367                                 'pageid' => $pageid,
 368                                 'missing' => ''
 369                         );
 370                 }
 371                 // Report special pages
 372                 foreach ( $pageSet->getSpecialTitles() as $fakeId => $title ) {
 373                         $vals = array();
 374                         ApiQueryBase::addTitleInfo( $vals, $title );
 375                         $vals['special'] = '';
 376                         if ( $title->isSpecialPage() &&
 377                                         !SpecialPageFactory::exists( $title->getDbKey() ) ) {
 378                                 $vals['missing'] = '';
 379                         } elseif ( $title->getNamespace() == NS_MEDIA &&
 380                                         !wfFindFile( $title ) ) {
 381                                 $vals['missing'] = '';
 382                         }
 383                         $pages[$fakeId] = $vals;
 384                 }
 385
 386                 // Output general page information for found titles
 387                 foreach ( $pageSet->getGoodTitles() as $pageid => $title ) {
 388                         $vals = array();
 389                         $vals['pageid'] = $pageid;
 390                         ApiQueryBase::addTitleInfo( $vals, $title );
 391                         $pages[$pageid] = $vals;
 392                 }
 393
 394                 if ( count( $pages ) ) {
 395                         if ( $this->params['indexpageids'] ) {
 396                                 $pageIDs = array_keys( $pages );
 397                                 // json treats all map keys as strings - converting to match
 398                                 $pageIDs = array_map( 'strval', $pageIDs );
 399                                 $result->setIndexedTagName( $pageIDs, 'id' );
 400                                 $result->addValue( 'query', 'pageids', $pageIDs );
 401                         }
 402
 403                         $result->setIndexedTagName( $pages, 'page' );
 404                         $result->addValue( 'query', 'pages', $pages );
 405                 }
 406                 if ( $this->params['export'] ) {
 407                         $this->doExport( $pageSet, $result );
 408                 }
 409         }
 410
 411         /**
 412          * @param $pageSet ApiPageSet Pages to be exported
 413          * @param $result ApiResult Result to output to
 414          */
 415         private function doExport( $pageSet, $result ) {
 416                 $exportTitles = array();
 417                 $titles = $pageSet->getGoodTitles();
 418                 if ( count( $titles ) ) {
 419                         $user = $this->getUser();
 420                         foreach ( $titles as $title ) {
 421                                 if ( $title->userCan( 'read', $user ) ) {
 422                                         $exportTitles[] = $title;
 423                                 }
 424                         }
 425                 }
 426
 427                 $exporter = new WikiExporter( $this->getDB() );
 428                 // WikiExporter writes to stdout, so catch its
 429                 // output with an ob
 430                 ob_start();
 431                 $exporter->openStream();
 432                 foreach ( $exportTitles as $title ) {
 433                         $exporter->pageByTitle( $title );
 434                 }
 435                 $exporter->closeStream();
 436                 $exportxml = ob_get_contents();
 437                 ob_end_clean();
 438
 439                 // Don't check the size of exported stuff
 440                 // It's not continuable, so it would cause more
 441                 // problems than it'd solve
 442                 $result->disableSizeCheck();
 443                 if ( $this->params['exportnowrap'] ) {
 444                         $result->reset();
 445                         // Raw formatter will handle this
 446                         $result->addValue( null, 'text', $exportxml );
 447                         $result->addValue( null, 'mime', 'text/xml' );
 448                 } else {
 449                         $r = array();
 450                         ApiResult::setContent( $r, $exportxml );
 451                         $result->addValue( 'query', 'export', $r );
 452                 }
 453                 $result->enableSizeCheck();
 454         }
 455
 456         public function getAllowedParams( $flags = 0 ) {
 457                 $result = array(
 458                         'prop' => array(
 459                                 ApiBase::PARAM_ISMULTI => true,
 460                                 ApiBase::PARAM_TYPE => $this->mModuleMgr->getNames( 'prop' )
 461                         ),
 462                         'list' => array(
 463                                 ApiBase::PARAM_ISMULTI => true,
 464                                 ApiBase::PARAM_TYPE => $this->mModuleMgr->getNames( 'list' )
 465                         ),
 466                         'meta' => array(
 467                                 ApiBase::PARAM_ISMULTI => true,
 468                                 ApiBase::PARAM_TYPE => $this->mModuleMgr->getNames( 'meta' )
 469                         ),
 470                         'indexpageids' => false,
 471                         'export' => false,
 472                         'exportnowrap' => false,
 473                         'iwurl' => false,
 474                 );
 475                 if ( $flags ) {
 476                         $result += $this->getPageSet()->getFinalParams( $flags );
 477                 }
 478                 return $result;
 479         }
 480
 481         /**
 482          * Override the parent to generate help messages for all available query modules.
 483          * @return string
 484          */
 485         public function makeHelpMsg() {
 486
 487                 // Use parent to make default message for the query module
 488                 $msg = parent::makeHelpMsg();
 489
 490                 $querySeparator = str_repeat( '--- ', 12 );
 491                 $moduleSeparator = str_repeat( '*** ', 14 );
 492                 $msg .= "\n$querySeparator Query: Prop  $querySeparator\n\n";
 493                 $msg .= $this->makeHelpMsgHelper( 'prop' );
 494                 $msg .= "\n$querySeparator Query: List  $querySeparator\n\n";
 495                 $msg .= $this->makeHelpMsgHelper( 'list' );
 496                 $msg .= "\n$querySeparator Query: Meta  $querySeparator\n\n";
 497                 $msg .= $this->makeHelpMsgHelper( 'meta' );
 498                 $msg .= "\n\n$moduleSeparator Modules: continuation  $moduleSeparator\n\n";
 499
 500                 return $msg;
 501         }
 502
 503         /**
 504          * For all modules of a given group, generate help messages and join them together
 505          * @param $group string Module group
 506          * @return string
 507          */
 508         private function makeHelpMsgHelper( $group ) {
 509                 $moduleDescriptions = array();
 510
 511                 $moduleNames = $this->mModuleMgr->getNames( $group );
 512                 sort( $moduleNames );
 513                 foreach ( $moduleNames as $name ) {
 514                         /**
 515                          * @var $module ApiQueryBase
 516                          */
 517                         $module = $this->mModuleMgr->getModule( $name );
 518
 519                         $msg = ApiMain::makeHelpMsgHeader( $module, $group );
 520                         $msg2 = $module->makeHelpMsg();
 521                         if ( $msg2 !== false ) {
 522                                 $msg .= $msg2;
 523                         }
 524                         if ( $module instanceof ApiQueryGeneratorBase ) {
 525                                 $msg .= "Generator:\n  This module may be used as a generator\n";
 526                         }
 527                         $moduleDescriptions[] = $msg;
 528                 }
 529
 530                 return implode( "\n", $moduleDescriptions );
 531         }
 532
 533         public function shouldCheckMaxlag() {
 534                 return true;
 535         }
 536
 537         public function getParamDescription() {
 538                 return $this->getPageSet()->getParamDescription() + array(
 539                         'prop' => 'Which properties to get for the titles/revisions/pageids. Module help is available below',
 540                         'list' => 'Which lists to get. Module help is available below',
 541                         'meta' => 'Which metadata to get about the site. Module help is available below',
 542                         'indexpageids' => 'Include an additional pageids section listing all returned page IDs',
 543                         'export' => 'Export the current revisions of all given or generated pages',
 544                         'exportnowrap' => 'Return the export XML without wrapping it in an XML result (same format as Special:Export). Can only be used with export',
 545                         'iwurl' => 'Whether to get the full URL if the title is an interwiki link',
 546                 );
 547         }
 548
 549         public function getDescription() {
 550                 return array(
 551                         'Query API module allows applications to get needed pieces of data from the MediaWiki databases,',
 552                         'and is loosely based on the old query.php interface.',
 553                         'All data modifications will first have to use query to acquire a token to prevent abuse from malicious sites'
 554                 );
 555         }
 556
 557         public function getPossibleErrors() {
 558                 return array_merge(
 559                         parent::getPossibleErrors(),
 560                         $this->getPageSet()->getPossibleErrors()
 561                 );
 562         }
 563
 564         public function getExamples() {
 565                 return array(
 566                         'api.php?action=query&prop=revisions&meta=siteinfo&titles=Main%20Page&rvprop=user|comment',
 567                         'api.php?action=query&generator=allpages&gapprefix=API/&prop=revisions',
 568                 );
 569         }
 570
 571         public function getHelpUrls() {
 572                 return array(
 573                         'https://www.mediawiki.org/wiki/API:Meta',
 574                         'https://www.mediawiki.org/wiki/API:Properties',
 575                         'https://www.mediawiki.org/wiki/API:Lists',
 576                 );
 577         }
 578 }