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         private $mPropModuleNames, $mListModuleNames, $mMetaModuleNames;
  41
  42         /**
  43          * @var ApiPageSet
  44          */
  45         private $mPageSet;
  46
  47         private $params, $redirects, $convertTitles, $iwUrl;
  48
  49         /**
  50          * List of Api Query prop modules
  51          * @var array
  52          */
  53         private $mQueryPropModules = array(
  54                 'categories' => 'ApiQueryCategories',
  55                 'categoryinfo' => 'ApiQueryCategoryInfo',
  56                 'duplicatefiles' => 'ApiQueryDuplicateFiles',
  57                 'extlinks' => 'ApiQueryExternalLinks',
  58                 'images' => 'ApiQueryImages',
  59                 'imageinfo' => 'ApiQueryImageInfo',
  60                 'info' => 'ApiQueryInfo',
  61                 'links' => 'ApiQueryLinks',
  62                 'iwlinks' => 'ApiQueryIWLinks',
  63                 'langlinks' => 'ApiQueryLangLinks',
  64                 'pageprops' => 'ApiQueryPageProps',
  65                 'revisions' => 'ApiQueryRevisions',
  66                 'stashimageinfo' => 'ApiQueryStashImageInfo',
  67                 'templates' => 'ApiQueryLinks',
  68         );
  69
  70         /**
  71          * List of Api Query list modules
  72          * @var array
  73          */
  74         private $mQueryListModules = array(
  75                 'allcategories' => 'ApiQueryAllCategories',
  76                 'allimages' => 'ApiQueryAllImages',
  77                 'alllinks' => 'ApiQueryAllLinks',
  78                 'allpages' => 'ApiQueryAllPages',
  79                 'allusers' => 'ApiQueryAllUsers',
  80                 'backlinks' => 'ApiQueryBacklinks',
  81                 'blocks' => 'ApiQueryBlocks',
  82                 'categorymembers' => 'ApiQueryCategoryMembers',
  83                 'deletedrevs' => 'ApiQueryDeletedrevs',
  84                 'embeddedin' => 'ApiQueryBacklinks',
  85                 'exturlusage' => 'ApiQueryExtLinksUsage',
  86                 'filearchive' => 'ApiQueryFilearchive',
  87                 'imageusage' => 'ApiQueryBacklinks',
  88                 'iwbacklinks' => 'ApiQueryIWBacklinks',
  89                 'langbacklinks' => 'ApiQueryLangBacklinks',
  90                 'logevents' => 'ApiQueryLogEvents',
  91                 'protectedtitles' => 'ApiQueryProtectedTitles',
  92                 'querypage' => 'ApiQueryQueryPage',
  93                 'random' => 'ApiQueryRandom',
  94                 'recentchanges' => 'ApiQueryRecentChanges',
  95                 'search' => 'ApiQuerySearch',
  96                 'tags' => 'ApiQueryTags',
  97                 'usercontribs' => 'ApiQueryContributions',
  98                 'users' => 'ApiQueryUsers',
  99                 'watchlist' => 'ApiQueryWatchlist',
 100                 'watchlistraw' => 'ApiQueryWatchlistRaw',
 101         );
 102
 103         /**
 104          * List of Api Query meta modules
 105          * @var array
 106          */
 107         private $mQueryMetaModules = array(
 108                 'allmessages' => 'ApiQueryAllMessages',
 109                 'siteinfo' => 'ApiQuerySiteinfo',
 110                 'userinfo' => 'ApiQueryUserInfo',
 111         );
 112
 113         /**
 114          * List of Api Query generator modules
 115          * Defined in code, rather than being derived at runtime,
 116          * due to performance reasons
 117          * @var array
 118          */
 119         private $mQueryGenerators = array(
 120                 'allcategories' => 'ApiQueryAllCategories',
 121                 'allimages' => 'ApiQueryAllImages',
 122                 'alllinks' => 'ApiQueryAllLinks',
 123                 'allpages' => 'ApiQueryAllPages',
 124                 'backlinks' => 'ApiQueryBacklinks',
 125                 'categories' => 'ApiQueryCategories',
 126                 'categorymembers' => 'ApiQueryCategoryMembers',
 127                 'duplicatefiles' => 'ApiQueryDuplicateFiles',
 128                 'embeddedin' => 'ApiQueryBacklinks',
 129                 'exturlusage' => 'ApiQueryExtLinksUsage',
 130                 'images' => 'ApiQueryImages',
 131                 'imageusage' => 'ApiQueryBacklinks',
 132                 'iwbacklinks' => 'ApiQueryIWBacklinks',
 133                 'langbacklinks' => 'ApiQueryLangBacklinks',
 134                 'links' => 'ApiQueryLinks',
 135                 'protectedtitles' => 'ApiQueryProtectedTitles',
 136                 'querypage' => 'ApiQueryQueryPage',
 137                 'random' => 'ApiQueryRandom',
 138                 'recentchanges' => 'ApiQueryRecentChanges',
 139                 'search' => 'ApiQuerySearch',
 140                 'templates' => 'ApiQueryLinks',
 141                 'watchlist' => 'ApiQueryWatchlist',
 142                 'watchlistraw' => 'ApiQueryWatchlistRaw',
 143         );
 144
 145         private $mSlaveDB = null;
 146         private $mNamedDB = array();
 147
 148         protected $mAllowedGenerators;
 149
 150         /**
 151          * @param $main ApiMain
 152          * @param $action string
 153          */
 154         public function __construct( $main, $action ) {
 155                 parent::__construct( $main, $action );
 156
 157                 // Allow custom modules to be added in LocalSettings.php
 158                 global $wgAPIPropModules, $wgAPIListModules, $wgAPIMetaModules, $wgAPIGeneratorModules;
 159                 self::appendUserModules( $this->mQueryPropModules, $wgAPIPropModules );
 160                 self::appendUserModules( $this->mQueryListModules, $wgAPIListModules );
 161                 self::appendUserModules( $this->mQueryMetaModules, $wgAPIMetaModules );
 162                 self::appendUserModules( $this->mQueryGenerators, $wgAPIGeneratorModules );
 163
 164                 $this->mPropModuleNames = array_keys( $this->mQueryPropModules );
 165                 $this->mListModuleNames = array_keys( $this->mQueryListModules );
 166                 $this->mMetaModuleNames = array_keys( $this->mQueryMetaModules );
 167                 $this->mAllowedGenerators = array_keys( $this->mQueryGenerators );
 168         }
 169
 170         /**
 171          * Helper function to append any add-in modules to the list
 172          * @param $modules array Module array
 173          * @param $newModules array Module array to add to $modules
 174          */
 175         private static function appendUserModules( &$modules, $newModules ) {
 176                 if ( is_array( $newModules ) ) {
 177                         foreach ( $newModules as $moduleName => $moduleClass ) {
 178                                 $modules[$moduleName] = $moduleClass;
 179                         }
 180                 }
 181         }
 182
 183         /**
 184          * Gets a default slave database connection object
 185          * @return DatabaseBase
 186          */
 187         public function getDB() {
 188                 if ( !isset( $this->mSlaveDB ) ) {
 189                         $this->profileDBIn();
 190                         $this->mSlaveDB = wfGetDB( DB_SLAVE, 'api' );
 191                         $this->profileDBOut();
 192                 }
 193                 return $this->mSlaveDB;
 194         }
 195
 196         /**
 197          * Get the query database connection with the given name.
 198          * If no such connection has been requested before, it will be created.
 199          * Subsequent calls with the same $name will return the same connection
 200          * as the first, regardless of the values of $db and $groups
 201          * @param $name string Name to assign to the database connection
 202          * @param $db int One of the DB_* constants
 203          * @param $groups array Query groups
 204          * @return DatabaseBase
 205          */
 206         public function getNamedDB( $name, $db, $groups ) {
 207                 if ( !array_key_exists( $name, $this->mNamedDB ) ) {
 208                         $this->profileDBIn();
 209                         $this->mNamedDB[$name] = wfGetDB( $db, $groups );
 210                         $this->profileDBOut();
 211                 }
 212                 return $this->mNamedDB[$name];
 213         }
 214
 215         /**
 216          * Gets the set of pages the user has requested (or generated)
 217          * @return ApiPageSet
 218          */
 219         public function getPageSet() {
 220                 return $this->mPageSet;
 221         }
 222
 223         /**
 224          * Get the array mapping module names to class names
 225          * @return array array(modulename => classname)
 226          */
 227         public function getModules() {
 228                 return array_merge( $this->mQueryPropModules, $this->mQueryListModules, $this->mQueryMetaModules );
 229         }
 230
 231         /**
 232          * Get the generators array mapping module names to class names
 233          * @return array array(modulename => classname)
 234          */
 235         public function getGenerators() {
 236                 return $this->mQueryGenerators;
 237         }
 238
 239         /**
 240          * Get whether the specified module is a prop, list or a meta query module
 241          * @param $moduleName string Name of the module to find type for
 242          * @return mixed string or null
 243          */
 244         function getModuleType( $moduleName ) {
 245                 if ( isset( $this->mQueryPropModules[$moduleName] ) ) {
 246                         return 'prop';
 247                 }
 248
 249                 if ( isset( $this->mQueryListModules[$moduleName] ) ) {
 250                         return 'list';
 251                 }
 252
 253                 if ( isset( $this->mQueryMetaModules[$moduleName] ) ) {
 254                         return 'meta';
 255                 }
 256
 257                 return null;
 258         }
 259
 260         /**
 261          * @return ApiFormatRaw|null
 262          */
 263         public function getCustomPrinter() {
 264                 // If &exportnowrap is set, use the raw formatter
 265                 if ( $this->getParameter( 'export' ) &&
 266                                 $this->getParameter( 'exportnowrap' ) )
 267                 {
 268                         return new ApiFormatRaw( $this->getMain(),
 269                                 $this->getMain()->createPrinterByName( 'xml' ) );
 270                 } else {
 271                         return null;
 272                 }
 273         }
 274
 275         /**
 276          * Query execution happens in the following steps:
 277          * #1 Create a PageSet object with any pages requested by the user
 278          * #2 If using a generator, execute it to get a new ApiPageSet object
 279          * #3 Instantiate all requested modules.
 280          *    This way the PageSet object will know what shared data is required,
 281          *    and minimize DB calls.
 282          * #4 Output all normalization and redirect resolution information
 283          * #5 Execute all requested modules
 284          */
 285         public function execute() {
 286                 $this->params = $this->extractRequestParams();
 287                 $this->redirects = $this->params['redirects'];
 288                 $this->convertTitles = $this->params['converttitles'];
 289                 $this->iwUrl = $this->params['iwurl'];
 290
 291                 // Create PageSet
 292                 $this->mPageSet = new ApiPageSet( $this, $this->redirects, $this->convertTitles );
 293
 294                 // Instantiate requested modules
 295                 $modules = array();
 296                 $this->instantiateModules( $modules, 'prop', $this->mQueryPropModules );
 297                 $this->instantiateModules( $modules, 'list', $this->mQueryListModules );
 298                 $this->instantiateModules( $modules, 'meta', $this->mQueryMetaModules );
 299
 300                 $cacheMode = 'public';
 301
 302                 // If given, execute generator to substitute user supplied data with generated data.
 303                 if ( isset( $this->params['generator'] ) ) {
 304                         $generator = $this->newGenerator( $this->params['generator'] );
 305                         $params = $generator->extractRequestParams();
 306                         $cacheMode = $this->mergeCacheMode( $cacheMode,
 307                                 $generator->getCacheMode( $params ) );
 308                         $this->executeGeneratorModule( $generator, $modules );
 309                 } else {
 310                         // Append custom fields and populate page/revision information
 311                         $this->addCustomFldsToPageSet( $modules, $this->mPageSet );
 312                         $this->mPageSet->execute();
 313                 }
 314
 315                 // Record page information (title, namespace, if exists, etc)
 316                 $this->outputGeneralPageInfo();
 317
 318                 // Execute all requested modules.
 319                 /**
 320                  * @var $module ApiQueryBase
 321                  */
 322                 foreach ( $modules as $module ) {
 323                         $params = $module->extractRequestParams();
 324                         $cacheMode = $this->mergeCacheMode(
 325                                 $cacheMode, $module->getCacheMode( $params ) );
 326                         $module->profileIn();
 327                         $module->execute();
 328                         wfRunHooks( 'APIQueryAfterExecute', array( &$module ) );
 329                         $module->profileOut();
 330                 }
 331
 332                 // Set the cache mode
 333                 $this->getMain()->setCacheMode( $cacheMode );
 334         }
 335
 336         /**
 337          * Update a cache mode string, applying the cache mode of a new module to it.
 338          * The cache mode may increase in the level of privacy, but public modules
 339          * added to private data do not decrease the level of privacy.
 340          *
 341          * @param $cacheMode string
 342          * @param $modCacheMode string
 343          * @return string
 344          */
 345         protected function mergeCacheMode( $cacheMode, $modCacheMode ) {
 346                 if ( $modCacheMode === 'anon-public-user-private' ) {
 347                         if ( $cacheMode !== 'private' ) {
 348                                 $cacheMode = 'anon-public-user-private';
 349                         }
 350                 } elseif ( $modCacheMode === 'public' ) {
 351                         // do nothing, if it's public already it will stay public
 352                 } else { // private
 353                         $cacheMode = 'private';
 354                 }
 355                 return $cacheMode;
 356         }
 357
 358         /**
 359          * Query modules may optimize data requests through the $this->getPageSet() object
 360          * by adding extra fields from the page table.
 361          * This function will gather all the extra request fields from the modules.
 362          * @param $modules array of module objects
 363          * @param $pageSet ApiPageSet
 364          */
 365         private function addCustomFldsToPageSet( $modules, $pageSet ) {
 366                 // Query all requested modules.
 367                 /**
 368                  * @var $module ApiQueryBase
 369                  */
 370                 foreach ( $modules as $module ) {
 371                         $module->requestExtraData( $pageSet );
 372                 }
 373         }
 374
 375         /**
 376          * Create instances of all modules requested by the client
 377          * @param $modules Array to append instantiated modules to
 378          * @param $param string Parameter name to read modules from
 379          * @param $moduleList Array array(modulename => classname)
 380          */
 381         private function instantiateModules( &$modules, $param, $moduleList ) {
 382                 if ( isset( $this->params[$param] ) ) {
 383                         foreach ( $this->params[$param] as $moduleName ) {
 384                                 $modules[] = new $moduleList[$moduleName] ( $this, $moduleName );
 385                         }
 386                 }
 387         }
 388
 389         /**
 390          * Appends an element for each page in the current pageSet with the
 391          * most general information (id, title), plus any title normalizations
 392          * and missing or invalid title/pageids/revids.
 393          */
 394         private function outputGeneralPageInfo() {
 395                 $pageSet = $this->getPageSet();
 396                 $result = $this->getResult();
 397
 398                 // We don't check for a full result set here because we can't be adding
 399                 // more than 380K. The maximum revision size is in the megabyte range,
 400                 // and the maximum result size must be even higher than that.
 401
 402                 // Title normalizations
 403                 $normValues = array();
 404                 foreach ( $pageSet->getNormalizedTitles() as $rawTitleStr => $titleStr ) {
 405                         $normValues[] = array(
 406                                 'from' => $rawTitleStr,
 407                                 'to' => $titleStr
 408                         );
 409                 }
 410
 411                 if ( count( $normValues ) ) {
 412                         $result->setIndexedTagName( $normValues, 'n' );
 413                         $result->addValue( 'query', 'normalized', $normValues );
 414                 }
 415
 416                 // Title conversions
 417                 $convValues = array();
 418                 foreach ( $pageSet->getConvertedTitles() as $rawTitleStr => $titleStr ) {
 419                         $convValues[] = array(
 420                                 'from' => $rawTitleStr,
 421                                 'to' => $titleStr
 422                         );
 423                 }
 424
 425                 if ( count( $convValues ) ) {
 426                         $result->setIndexedTagName( $convValues, 'c' );
 427                         $result->addValue( 'query', 'converted', $convValues );
 428                 }
 429
 430                 // Interwiki titles
 431                 $intrwValues = array();
 432                 foreach ( $pageSet->getInterwikiTitles() as $rawTitleStr => $interwikiStr ) {
 433                         $item = array(
 434                                 'title' => $rawTitleStr,
 435                                 'iw' => $interwikiStr,
 436                         );
 437                         if ( $this->iwUrl ) {
 438                                 $title = Title::newFromText( $rawTitleStr );
 439                                 $item['url'] = wfExpandUrl( $title->getFullURL(), PROTO_CURRENT );
 440                         }
 441                         $intrwValues[] = $item;
 442                 }
 443
 444                 if ( count( $intrwValues ) ) {
 445                         $result->setIndexedTagName( $intrwValues, 'i' );
 446                         $result->addValue( 'query', 'interwiki', $intrwValues );
 447                 }
 448
 449                 // Show redirect information
 450                 $redirValues = array();
 451                 /**
 452                  * @var $titleTo Title
 453                  */
 454                 foreach ( $pageSet->getRedirectTitles() as $titleStrFrom => $titleTo ) {
 455                         $r = array(
 456                                 'from' => strval( $titleStrFrom ),
 457                                 'to' => $titleTo->getPrefixedText(),
 458                         );
 459                         if ( $titleTo->getFragment() !== '' ) {
 460                                 $r['tofragment'] = $titleTo->getFragment();
 461                         }
 462                         $redirValues[] = $r;
 463                 }
 464
 465                 if ( count( $redirValues ) ) {
 466                         $result->setIndexedTagName( $redirValues, 'r' );
 467                         $result->addValue( 'query', 'redirects', $redirValues );
 468                 }
 469
 470                 // Missing revision elements
 471                 $missingRevIDs = $pageSet->getMissingRevisionIDs();
 472                 if ( count( $missingRevIDs ) ) {
 473                         $revids = array();
 474                         foreach ( $missingRevIDs as $revid ) {
 475                                 $revids[$revid] = array(
 476                                         'revid' => $revid
 477                                 );
 478                         }
 479                         $result->setIndexedTagName( $revids, 'rev' );
 480                         $result->addValue( 'query', 'badrevids', $revids );
 481                 }
 482
 483                 // Page elements
 484                 $pages = array();
 485
 486                 // Report any missing titles
 487                 foreach ( $pageSet->getMissingTitles() as $fakeId => $title ) {
 488                         $vals = array();
 489                         ApiQueryBase::addTitleInfo( $vals, $title );
 490                         $vals['missing'] = '';
 491                         $pages[$fakeId] = $vals;
 492                 }
 493                 // Report any invalid titles
 494                 foreach ( $pageSet->getInvalidTitles() as $fakeId => $title ) {
 495                         $pages[$fakeId] = array( 'title' => $title, 'invalid' => '' );
 496                 }
 497                 // Report any missing page ids
 498                 foreach ( $pageSet->getMissingPageIDs() as $pageid ) {
 499                         $pages[$pageid] = array(
 500                                 'pageid' => $pageid,
 501                                 'missing' => ''
 502                         );
 503                 }
 504                 // Report special pages
 505                 foreach ( $pageSet->getSpecialTitles() as $fakeId => $title ) {
 506                         $vals = array();
 507                         ApiQueryBase::addTitleInfo( $vals, $title );
 508                         $vals['special'] = '';
 509                         if ( $title->isSpecialPage() &&
 510                                         !SpecialPageFactory::exists( $title->getDbKey() ) ) {
 511                                 $vals['missing'] = '';
 512                         } elseif ( $title->getNamespace() == NS_MEDIA &&
 513                                         !wfFindFile( $title ) ) {
 514                                 $vals['missing'] = '';
 515                         }
 516                         $pages[$fakeId] = $vals;
 517                 }
 518
 519                 // Output general page information for found titles
 520                 foreach ( $pageSet->getGoodTitles() as $pageid => $title ) {
 521                         $vals = array();
 522                         $vals['pageid'] = $pageid;
 523                         ApiQueryBase::addTitleInfo( $vals, $title );
 524                         $pages[$pageid] = $vals;
 525                 }
 526
 527                 if ( count( $pages ) ) {
 528                         if ( $this->params['indexpageids'] ) {
 529                                 $pageIDs = array_keys( $pages );
 530                                 // json treats all map keys as strings - converting to match
 531                                 $pageIDs = array_map( 'strval', $pageIDs );
 532                                 $result->setIndexedTagName( $pageIDs, 'id' );
 533                                 $result->addValue( 'query', 'pageids', $pageIDs );
 534                         }
 535
 536                         $result->setIndexedTagName( $pages, 'page' );
 537                         $result->addValue( 'query', 'pages', $pages );
 538                 }
 539                 if ( $this->params['export'] ) {
 540                         $this->doExport( $pageSet, $result );
 541                 }
 542         }
 543
 544         /**
 545          * @param  $pageSet ApiPageSet Pages to be exported
 546          * @param  $result ApiResult Result to output to
 547          */
 548         private function doExport( $pageSet, $result ) {
 549                 $exportTitles = array();
 550                 $titles = $pageSet->getGoodTitles();
 551                 if ( count( $titles ) ) {
 552                         $user = $this->getUser();
 553                         foreach ( $titles as $title ) {
 554                                 if ( $title->userCan( 'read', $user ) ) {
 555                                         $exportTitles[] = $title;
 556                                 }
 557                         }
 558                 }
 559
 560                 $exporter = new WikiExporter( $this->getDB() );
 561                 // WikiExporter writes to stdout, so catch its
 562                 // output with an ob
 563                 ob_start();
 564                 $exporter->openStream();
 565                 foreach ( $exportTitles as $title ) {
 566                         $exporter->pageByTitle( $title );
 567                 }
 568                 $exporter->closeStream();
 569                 $exportxml = ob_get_contents();
 570                 ob_end_clean();
 571
 572                 // Don't check the size of exported stuff
 573                 // It's not continuable, so it would cause more
 574                 // problems than it'd solve
 575                 $result->disableSizeCheck();
 576                 if ( $this->params['exportnowrap'] ) {
 577                         $result->reset();
 578                         // Raw formatter will handle this
 579                         $result->addValue( null, 'text', $exportxml );
 580                         $result->addValue( null, 'mime', 'text/xml' );
 581                 } else {
 582                         $r = array();
 583                         ApiResult::setContent( $r, $exportxml );
 584                         $result->addValue( 'query', 'export', $r );
 585                 }
 586                 $result->enableSizeCheck();
 587         }
 588
 589         /**
 590          * Create a generator object of the given type and return it
 591          * @param $generatorName string Module name
 592          * @return ApiQueryGeneratorBase
 593          */
 594         public function newGenerator( $generatorName ) {
 595                 // Find class that implements requested generator
 596                 if ( isset( $this->mQueryListModules[$generatorName] ) ) {
 597                         $className = $this->mQueryListModules[$generatorName];
 598                 } elseif ( isset( $this->mQueryPropModules[$generatorName] ) ) {
 599                         $className = $this->mQueryPropModules[$generatorName];
 600                 } else {
 601                         ApiBase::dieDebug( __METHOD__, "Unknown generator=$generatorName" );
 602                 }
 603                 $generator = new $className ( $this, $generatorName );
 604                 if ( !$generator instanceof ApiQueryGeneratorBase ) {
 605                         $this->dieUsage( "Module $generatorName cannot be used as a generator", 'badgenerator' );
 606                 }
 607                 $generator->setGeneratorMode();
 608                 return $generator;
 609         }
 610
 611         /**
 612          * For generator mode, execute generator, and use its output as new
 613          * ApiPageSet
 614          * @param $generator ApiQueryGeneratorBase Generator Module
 615          * @param $modules array of module objects
 616          */
 617         protected function executeGeneratorModule( $generator, $modules ) {
 618                 // Generator results
 619                 $resultPageSet = new ApiPageSet( $this, $this->redirects, $this->convertTitles );
 620
 621                 // Add any additional fields modules may need
 622                 $generator->requestExtraData( $this->mPageSet );
 623                 $this->addCustomFldsToPageSet( $modules, $resultPageSet );
 624
 625                 // Populate page information with the original user input
 626                 $this->mPageSet->execute();
 627
 628                 // populate resultPageSet with the generator output
 629                 $generator->profileIn();
 630                 $generator->executeGenerator( $resultPageSet );
 631                 wfRunHooks( 'APIQueryGeneratorAfterExecute', array( &$generator, &$resultPageSet ) );
 632                 $resultPageSet->finishPageSetGeneration();
 633                 $generator->profileOut();
 634
 635                 // Swap the resulting pageset back in
 636                 $this->mPageSet = $resultPageSet;
 637         }
 638
 639         public function getAllowedParams() {
 640                 return array(
 641                         'prop' => array(
 642                                 ApiBase::PARAM_ISMULTI => true,
 643                                 ApiBase::PARAM_TYPE => $this->mPropModuleNames
 644                         ),
 645                         'list' => array(
 646                                 ApiBase::PARAM_ISMULTI => true,
 647                                 ApiBase::PARAM_TYPE => $this->mListModuleNames
 648                         ),
 649                         'meta' => array(
 650                                 ApiBase::PARAM_ISMULTI => true,
 651                                 ApiBase::PARAM_TYPE => $this->mMetaModuleNames
 652                         ),
 653                         'generator' => array(
 654                                 ApiBase::PARAM_TYPE => $this->mAllowedGenerators
 655                         ),
 656                         'redirects' => false,
 657                         'converttitles' => false,
 658                         'indexpageids' => false,
 659                         'export' => false,
 660                         'exportnowrap' => false,
 661                         'iwurl' => false,
 662                 );
 663         }
 664
 665         /**
 666          * Override the parent to generate help messages for all available query modules.
 667          * @return string
 668          */
 669         public function makeHelpMsg() {
 670                 // Make sure the internal object is empty
 671                 // (just in case a sub-module decides to optimize during instantiation)
 672                 $this->mPageSet = null;
 673
 674                 $querySeparator = str_repeat( '--- ', 12 );
 675                 $moduleSeparator = str_repeat( '*** ', 14 );
 676                 $msg = "\n$querySeparator Query: Prop  $querySeparator\n\n";
 677                 $msg .= $this->makeHelpMsgHelper( $this->mQueryPropModules, 'prop' );
 678                 $msg .= "\n$querySeparator Query: List  $querySeparator\n\n";
 679                 $msg .= $this->makeHelpMsgHelper( $this->mQueryListModules, 'list' );
 680                 $msg .= "\n$querySeparator Query: Meta  $querySeparator\n\n";
 681                 $msg .= $this->makeHelpMsgHelper( $this->mQueryMetaModules, 'meta' );
 682                 $msg .= "\n\n$moduleSeparator Modules: continuation  $moduleSeparator\n\n";
 683
 684                 // Use parent to make default message for the query module
 685                 $msg = parent::makeHelpMsg() . $msg;
 686
 687                 return $msg;
 688         }
 689
 690         /**
 691          * For all modules in $moduleList, generate help messages and join them together
 692          * @param $moduleList Array array(modulename => classname)
 693          * @param $paramName string Parameter name
 694          * @return string
 695          */
 696         private function makeHelpMsgHelper( $moduleList, $paramName ) {
 697                 $moduleDescriptions = array();
 698
 699                 foreach ( $moduleList as $moduleName => $moduleClass ) {
 700                         /**
 701                          * @var $module ApiQueryBase
 702                          */
 703                         $module = new $moduleClass( $this, $moduleName, null );
 704
 705                         $msg = ApiMain::makeHelpMsgHeader( $module, $paramName );
 706                         $msg2 = $module->makeHelpMsg();
 707                         if ( $msg2 !== false ) {
 708                                 $msg .= $msg2;
 709                         }
 710                         if ( $module instanceof ApiQueryGeneratorBase ) {
 711                                 $msg .= "Generator:\n  This module may be used as a generator\n";
 712                         }
 713                         $moduleDescriptions[] = $msg;
 714                 }
 715
 716                 return implode( "\n", $moduleDescriptions );
 717         }
 718
 719         /**
 720          * Override to add extra parameters from PageSet
 721          * @return string
 722          */
 723         public function makeHelpMsgParameters() {
 724                 $psModule = new ApiPageSet( $this );
 725                 return $psModule->makeHelpMsgParameters() . parent::makeHelpMsgParameters();
 726         }
 727
 728         public function shouldCheckMaxlag() {
 729                 return true;
 730         }
 731
 732         public function getParamDescription() {
 733                 return array(
 734                         'prop' => 'Which properties to get for the titles/revisions/pageids. Module help is available below',
 735                         'list' => 'Which lists to get. Module help is available below',
 736                         'meta' => 'Which metadata to get about the site. Module help is available below',
 737                         'generator' => array( 'Use the output of a list as the input for other prop/list/meta items',
 738                                         'NOTE: generator parameter names must be prefixed with a \'g\', see examples' ),
 739                         'redirects' => 'Automatically resolve redirects',
 740                         'converttitles' => array( "Convert titles to other variants if necessary. Only works if the wiki's content language supports variant conversion.",
 741                                         'Languages that support variant conversion include ' . implode( ', ', LanguageConverter::$languagesWithVariants ) ),
 742                         'indexpageids' => 'Include an additional pageids section listing all returned page IDs',
 743                         'export' => 'Export the current revisions of all given or generated pages',
 744                         'exportnowrap' => 'Return the export XML without wrapping it in an XML result (same format as Special:Export). Can only be used with export',
 745                         'iwurl' => 'Whether to get the full URL if the title is an interwiki link',
 746                 );
 747         }
 748
 749         public function getDescription() {
 750                 return array(
 751                         'Query API module allows applications to get needed pieces of data from the MediaWiki databases,',
 752                         'and is loosely based on the old query.php interface.',
 753                         'All data modifications will first have to use query to acquire a token to prevent abuse from malicious sites'
 754                 );
 755         }
 756
 757         public function getPossibleErrors() {
 758                 return array_merge( parent::getPossibleErrors(), array(
 759                         array( 'code' => 'badgenerator', 'info' => 'Module $generatorName cannot be used as a generator' ),
 760                 ) );
 761         }
 762
 763         public function getExamples() {
 764                 return array(
 765                         'api.php?action=query&prop=revisions&meta=siteinfo&titles=Main%20Page&rvprop=user|comment',
 766                         'api.php?action=query&generator=allpages&gapprefix=API/&prop=revisions',
 767                 );
 768         }
 769
 770         public function getHelpUrls() {
 771                 return array(
 772                         'https://www.mediawiki.org/wiki/API:Meta',
 773                         'https://www.mediawiki.org/wiki/API:Properties',
 774                         'https://www.mediawiki.org/wiki/API:Lists',
 775                 );
 776         }
 777
 778         public function getVersion() {
 779                 $psModule = new ApiPageSet( $this );
 780                 $vers = array();
 781                 $vers[] = __CLASS__ . ': $Id$';
 782                 $vers[] = $psModule->getVersion();
 783                 return $vers;
 784         }
 785 }