includes/api/ApiQuery.php

   1 <?php
   2
   3 /**
   4  * Created on Sep 7, 2006
   5  *
   6  * API for MediaWiki 1.8+
   7  *
   8  * Copyright © 2006 Yuri Astrakhan <Firstname><Lastname>@gmail.com
   9  *
  10  * This program is free software; you can redistribute it and/or modify
  11  * it under the terms of the GNU General Public License as published by
  12  * the Free Software Foundation; either version 2 of the License, or
  13  * (at your option) any later version.
  14  *
  15  * This program is distributed in the hope that it will be useful,
  16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  18  * GNU General Public License for more details.
  19  *
  20  * You should have received a copy of the GNU General Public License along
  21  * with this program; if not, write to the Free Software Foundation, Inc.,
  22  * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  23  * http://www.gnu.org/copyleft/gpl.html
  24  */
  25
  26 if ( !defined( 'MEDIAWIKI' ) ) {
  27         // Eclipse helper - will be ignored in production
  28         require_once( 'ApiBase.php' );
  29 }
  30
  31 /**
  32  * This is the main query class. It behaves similar to ApiMain: based on the
  33  * parameters given, it will create a list of titles to work on (an ApiPageSet
  34  * object), instantiate and execute various property/list/meta modules, and
  35  * assemble all resulting data into a single ApiResult object.
  36  *
  37  * In generator mode, a generator will be executed first to populate a second
  38  * ApiPageSet object, and that object will be used for all subsequent modules.
  39  *
  40  * @ingroup API
  41  */
  42 class ApiQuery extends ApiBase {
  43
  44         private $mPropModuleNames, $mListModuleNames, $mMetaModuleNames;
  45         private $mPageSet;
  46         private $params, $redirect;
  47
  48         private $mQueryPropModules = array(
  49                 'info' => 'ApiQueryInfo',
  50                 'revisions' => 'ApiQueryRevisions',
  51                 'links' => 'ApiQueryLinks',
  52                 'langlinks' => 'ApiQueryLangLinks',
  53                 'images' => 'ApiQueryImages',
  54                 'imageinfo' => 'ApiQueryImageInfo',
  55                 'templates' => 'ApiQueryLinks',
  56                 'categories' => 'ApiQueryCategories',
  57                 'extlinks' => 'ApiQueryExternalLinks',
  58                 'categoryinfo' => 'ApiQueryCategoryInfo',
  59                 'duplicatefiles' => 'ApiQueryDuplicateFiles',
  60         );
  61
  62         private $mQueryListModules = array(
  63                 'allimages' => 'ApiQueryAllimages',
  64                 'allpages' => 'ApiQueryAllpages',
  65                 'alllinks' => 'ApiQueryAllLinks',
  66                 'allcategories' => 'ApiQueryAllCategories',
  67                 'allusers' => 'ApiQueryAllUsers',
  68                 'backlinks' => 'ApiQueryBacklinks',
  69                 'blocks' => 'ApiQueryBlocks',
  70                 'categorymembers' => 'ApiQueryCategoryMembers',
  71                 'deletedrevs' => 'ApiQueryDeletedrevs',
  72                 'embeddedin' => 'ApiQueryBacklinks',
  73                 'imageusage' => 'ApiQueryBacklinks',
  74                 'logevents' => 'ApiQueryLogEvents',
  75                 'recentchanges' => 'ApiQueryRecentChanges',
  76                 'search' => 'ApiQuerySearch',
  77                 'tags' => 'ApiQueryTags',
  78                 'usercontribs' => 'ApiQueryContributions',
  79                 'watchlist' => 'ApiQueryWatchlist',
  80                 'watchlistraw' => 'ApiQueryWatchlistRaw',
  81                 'exturlusage' => 'ApiQueryExtLinksUsage',
  82                 'users' => 'ApiQueryUsers',
  83                 'random' => 'ApiQueryRandom',
  84                 'protectedtitles' => 'ApiQueryProtectedTitles',
  85         );
  86
  87         private $mQueryMetaModules = array(
  88                 'siteinfo' => 'ApiQuerySiteinfo',
  89                 'userinfo' => 'ApiQueryUserInfo',
  90                 'allmessages' => 'ApiQueryAllmessages',
  91         );
  92
  93         private $mSlaveDB = null;
  94         private $mNamedDB = array();
  95
  96         public function __construct( $main, $action ) {
  97                 parent::__construct( $main, $action );
  98
  99                 // Allow custom modules to be added in LocalSettings.php
 100                 global $wgAPIPropModules, $wgAPIListModules, $wgAPIMetaModules;
 101                 self::appendUserModules( $this->mQueryPropModules, $wgAPIPropModules );
 102                 self::appendUserModules( $this->mQueryListModules, $wgAPIListModules );
 103                 self::appendUserModules( $this->mQueryMetaModules, $wgAPIMetaModules );
 104
 105                 $this->mPropModuleNames = array_keys( $this->mQueryPropModules );
 106                 $this->mListModuleNames = array_keys( $this->mQueryListModules );
 107                 $this->mMetaModuleNames = array_keys( $this->mQueryMetaModules );
 108
 109                 // Allow the entire list of modules at first,
 110                 // but during module instantiation check if it can be used as a generator.
 111                 $this->mAllowedGenerators = array_merge( $this->mListModuleNames, $this->mPropModuleNames );
 112         }
 113
 114         /**
 115          * Helper function to append any add-in modules to the list
 116          * @param $modules array Module array
 117          * @param $newModules array Module array to add to $modules
 118          */
 119         private static function appendUserModules( &$modules, $newModules ) {
 120                 if ( is_array( $newModules ) ) {
 121                         foreach ( $newModules as $moduleName => $moduleClass ) {
 122                                 $modules[$moduleName] = $moduleClass;
 123                         }
 124                 }
 125         }
 126
 127         /**
 128          * Gets a default slave database connection object
 129          * @return Database
 130          */
 131         public function getDB() {
 132                 if ( !isset( $this->mSlaveDB ) ) {
 133                         $this->profileDBIn();
 134                         $this->mSlaveDB = wfGetDB( DB_SLAVE, 'api' );
 135                         $this->profileDBOut();
 136                 }
 137                 return $this->mSlaveDB;
 138         }
 139
 140         /**
 141          * Get the query database connection with the given name.
 142          * If no such connection has been requested before, it will be created.
 143          * Subsequent calls with the same $name will return the same connection
 144          * as the first, regardless of the values of $db and $groups
 145          * @param $name string Name to assign to the database connection
 146          * @param $db int One of the DB_* constants
 147          * @param $groups array Query groups
 148          * @return Database
 149          */
 150         public function getNamedDB( $name, $db, $groups ) {
 151                 if ( !array_key_exists( $name, $this->mNamedDB ) ) {
 152                         $this->profileDBIn();
 153                         $this->mNamedDB[$name] = wfGetDB( $db, $groups );
 154                         $this->profileDBOut();
 155                 }
 156                 return $this->mNamedDB[$name];
 157         }
 158
 159         /**
 160          * Gets the set of pages the user has requested (or generated)
 161          * @return ApiPageSet
 162          */
 163         public function getPageSet() {
 164                 return $this->mPageSet;
 165         }
 166
 167         /**
 168          * Get the array mapping module names to class names
 169          * @return array(modulename => classname)
 170          */
 171         function getModules() {
 172                 return array_merge( $this->mQueryPropModules, $this->mQueryListModules, $this->mQueryMetaModules );
 173         }
 174
 175         public function getCustomPrinter() {
 176                 // If &exportnowrap is set, use the raw formatter
 177                 if ( $this->getParameter( 'export' ) &&
 178                                 $this->getParameter( 'exportnowrap' ) )
 179                 {
 180                         return new ApiFormatRaw( $this->getMain(),
 181                                 $this->getMain()->createPrinterByName( 'xml' ) );
 182                 } else {
 183                         return null;
 184                 }
 185         }
 186
 187         /**
 188          * Query execution happens in the following steps:
 189          * #1 Create a PageSet object with any pages requested by the user
 190          * #2 If using a generator, execute it to get a new ApiPageSet object
 191          * #3 Instantiate all requested modules.
 192          *    This way the PageSet object will know what shared data is required,
 193          *    and minimize DB calls.
 194          * #4 Output all normalization and redirect resolution information
 195          * #5 Execute all requested modules
 196          */
 197         public function execute() {
 198                 $this->params = $this->extractRequestParams();
 199                 $this->redirects = $this->params['redirects'];
 200
 201                 // Create PageSet
 202                 $this->mPageSet = new ApiPageSet( $this, $this->redirects );
 203
 204                 // Instantiate requested modules
 205                 $modules = array();
 206                 $this->InstantiateModules( $modules, 'prop', $this->mQueryPropModules );
 207                 $this->InstantiateModules( $modules, 'list', $this->mQueryListModules );
 208                 $this->InstantiateModules( $modules, 'meta', $this->mQueryMetaModules );
 209
 210                 // If given, execute generator to substitute user supplied data with generated data.
 211                 if ( isset( $this->params['generator'] ) ) {
 212                         $this->executeGeneratorModule( $this->params['generator'], $modules );
 213                 } else {
 214                         // Append custom fields and populate page/revision information
 215                         $this->addCustomFldsToPageSet( $modules, $this->mPageSet );
 216                         $this->mPageSet->execute();
 217                 }
 218
 219                 // Record page information (title, namespace, if exists, etc)
 220                 $this->outputGeneralPageInfo();
 221
 222                 // Execute all requested modules.
 223                 foreach ( $modules as $module ) {
 224                         $module->profileIn();
 225                         $module->execute();
 226                         wfRunHooks( 'APIQueryAfterExecute', array( &$module ) );
 227                         $module->profileOut();
 228                 }
 229         }
 230
 231         /**
 232          * Query modules may optimize data requests through the $this->getPageSet() object
 233          * by adding extra fields from the page table.
 234          * This function will gather all the extra request fields from the modules.
 235          * @param $modules array of module objects
 236          * @param $pageSet ApiPageSet
 237          */
 238         private function addCustomFldsToPageSet( $modules, $pageSet ) {
 239                 // Query all requested modules.
 240                 foreach ( $modules as $module ) {
 241                         $module->requestExtraData( $pageSet );
 242                 }
 243         }
 244
 245         /**
 246          * Create instances of all modules requested by the client
 247          * @param $modules array to append instatiated modules to
 248          * @param $param string Parameter name to read modules from
 249          * @param $moduleList array(modulename => classname)
 250          */
 251         private function InstantiateModules( &$modules, $param, $moduleList ) {
 252                 $list = @$this->params[$param];
 253                 if ( !is_null ( $list ) ) {
 254                         foreach ( $list as $moduleName ) {
 255                                 $modules[] = new $moduleList[$moduleName] ( $this, $moduleName );
 256                         }
 257                 }
 258         }
 259
 260         /**
 261          * Appends an element for each page in the current pageSet with the
 262          * most general information (id, title), plus any title normalizations
 263          * and missing or invalid title/pageids/revids.
 264          */
 265         private function outputGeneralPageInfo() {
 266                 $pageSet = $this->getPageSet();
 267                 $result = $this->getResult();
 268
 269                 // We don't check for a full result set here because we can't be adding
 270                 // more than 380K. The maximum revision size is in the megabyte range,
 271                 // and the maximum result size must be even higher than that.
 272
 273                 // Title normalizations
 274                 $normValues = array();
 275                 foreach ( $pageSet->getNormalizedTitles() as $rawTitleStr => $titleStr ) {
 276                         $normValues[] = array(
 277                                 'from' => $rawTitleStr,
 278                                 'to' => $titleStr
 279                         );
 280                 }
 281
 282                 if ( count( $normValues ) ) {
 283                         $result->setIndexedTagName( $normValues, 'n' );
 284                         $result->addValue( 'query', 'normalized', $normValues );
 285                 }
 286
 287                 // Interwiki titles
 288                 $intrwValues = array();
 289                 foreach ( $pageSet->getInterwikiTitles() as $rawTitleStr => $interwikiStr ) {
 290                         $intrwValues[] = array(
 291                                 'title' => $rawTitleStr,
 292                                 'iw' => $interwikiStr
 293                         );
 294                 }
 295
 296                 if ( count( $intrwValues ) ) {
 297                         $result->setIndexedTagName( $intrwValues, 'i' );
 298                         $result->addValue( 'query', 'interwiki', $intrwValues );
 299                 }
 300
 301                 // Show redirect information
 302                 $redirValues = array();
 303                 foreach ( $pageSet->getRedirectTitles() as $titleStrFrom => $titleStrTo ) {
 304                         $redirValues[] = array(
 305                                 'from' => strval( $titleStrFrom ),
 306                                 'to' => $titleStrTo
 307                         );
 308                 }
 309
 310                 if ( count( $redirValues ) ) {
 311                         $result->setIndexedTagName( $redirValues, 'r' );
 312                         $result->addValue( 'query', 'redirects', $redirValues );
 313                 }
 314
 315                 //
 316                 // Missing revision elements
 317                 //
 318                 $missingRevIDs = $pageSet->getMissingRevisionIDs();
 319                 if ( count( $missingRevIDs ) ) {
 320                         $revids = array();
 321                         foreach ( $missingRevIDs as $revid ) {
 322                                 $revids[$revid] = array(
 323                                         'revid' => $revid
 324                                 );
 325                         }
 326                         $result->setIndexedTagName( $revids, 'rev' );
 327                         $result->addValue( 'query', 'badrevids', $revids );
 328                 }
 329
 330                 //
 331                 // Page elements
 332                 //
 333                 $pages = array();
 334
 335                 // Report any missing titles
 336                 foreach ( $pageSet->getMissingTitles() as $fakeId => $title ) {
 337                         $vals = array();
 338                         ApiQueryBase::addTitleInfo( $vals, $title );
 339                         $vals['missing'] = '';
 340                         $pages[$fakeId] = $vals;
 341                 }
 342                 // Report any invalid titles
 343                 foreach ( $pageSet->getInvalidTitles() as $fakeId => $title ) {
 344                         $pages[$fakeId] = array( 'title' => $title, 'invalid' => '' );
 345                 }
 346                 // Report any missing page ids
 347                 foreach ( $pageSet->getMissingPageIDs() as $pageid ) {
 348                         $pages[$pageid] = array(
 349                                 'pageid' => $pageid,
 350                                 'missing' => ''
 351                         );
 352                 }
 353
 354                 // Output general page information for found titles
 355                 foreach ( $pageSet->getGoodTitles() as $pageid => $title ) {
 356                         $vals = array();
 357                         $vals['pageid'] = $pageid;
 358                         ApiQueryBase::addTitleInfo( $vals, $title );
 359                         $pages[$pageid] = $vals;
 360                 }
 361
 362                 if ( count( $pages ) ) {
 363                         if ( $this->params['indexpageids'] ) {
 364                                 $pageIDs = array_keys( $pages );
 365                                 // json treats all map keys as strings - converting to match
 366                                 $pageIDs = array_map( 'strval', $pageIDs );
 367                                 $result->setIndexedTagName( $pageIDs, 'id' );
 368                                 $result->addValue( 'query', 'pageids', $pageIDs );
 369                         }
 370
 371                         $result->setIndexedTagName( $pages, 'page' );
 372                         $result->addValue( 'query', 'pages', $pages );
 373                 }
 374                 if ( $this->params['export'] ) {
 375                         $exporter = new WikiExporter( $this->getDB() );
 376                         // WikiExporter writes to stdout, so catch its
 377                         // output with an ob
 378                         ob_start();
 379                         $exporter->openStream();
 380                         foreach ( @$pageSet->getGoodTitles() as $title ) {
 381                                 if ( $title->userCanRead() ) {
 382                                         $exporter->pageByTitle( $title );
 383                                 }
 384                         }
 385                         $exporter->closeStream();
 386                         $exportxml = ob_get_contents();
 387                         ob_end_clean();
 388
 389                         // Don't check the size of exported stuff
 390                         // It's not continuable, so it would cause more
 391                         // problems than it'd solve
 392                         $result->disableSizeCheck();
 393                         if ( $this->params['exportnowrap'] ) {
 394                                 $result->reset();
 395                                 // Raw formatter will handle this
 396                                 $result->addValue( null, 'text', $exportxml );
 397                                 $result->addValue( null, 'mime', 'text/xml' );
 398                         } else {
 399                                 $r = array();
 400                                 ApiResult::setContent( $r, $exportxml );
 401                                 $result->addValue( 'query', 'export', $r );
 402                         }
 403                         $result->enableSizeCheck();
 404                 }
 405         }
 406
 407         /**
 408          * For generator mode, execute generator, and use its output as new
 409          * ApiPageSet
 410          * @param $generatorName string Module name
 411          * @param $modules array of module objects
 412          */
 413         protected function executeGeneratorModule( $generatorName, $modules ) {
 414                 // Find class that implements requested generator
 415                 if ( isset( $this->mQueryListModules[$generatorName] ) ) {
 416                         $className = $this->mQueryListModules[$generatorName];
 417                 } elseif ( isset( $this->mQueryPropModules[$generatorName] ) ) {
 418                         $className = $this->mQueryPropModules[$generatorName];
 419                 } else {
 420                         ApiBase::dieDebug( __METHOD__, "Unknown generator=$generatorName" );
 421                 }
 422
 423                 // Generator results
 424                 $resultPageSet = new ApiPageSet( $this, $this->redirects );
 425
 426                 // Create and execute the generator
 427                 $generator = new $className ( $this, $generatorName );
 428                 if ( !$generator instanceof ApiQueryGeneratorBase ) {
 429                         $this->dieUsage( "Module $generatorName cannot be used as a generator", 'badgenerator' );
 430                 }
 431
 432                 $generator->setGeneratorMode();
 433
 434                 // Add any additional fields modules may need
 435                 $generator->requestExtraData( $this->mPageSet );
 436                 $this->addCustomFldsToPageSet( $modules, $resultPageSet );
 437
 438                 // Populate page information with the original user input
 439                 $this->mPageSet->execute();
 440
 441                 // populate resultPageSet with the generator output
 442                 $generator->profileIn();
 443                 $generator->executeGenerator( $resultPageSet );
 444                 wfRunHooks( 'APIQueryGeneratorAfterExecute', array( &$generator, &$resultPageSet ) );
 445                 $resultPageSet->finishPageSetGeneration();
 446                 $generator->profileOut();
 447
 448                 // Swap the resulting pageset back in
 449                 $this->mPageSet = $resultPageSet;
 450         }
 451
 452         public function getAllowedParams() {
 453                 return array(
 454                         'prop' => array(
 455                                 ApiBase::PARAM_ISMULTI => true,
 456                                 ApiBase::PARAM_TYPE => $this->mPropModuleNames
 457                         ),
 458                         'list' => array(
 459                                 ApiBase::PARAM_ISMULTI => true,
 460                                 ApiBase::PARAM_TYPE => $this->mListModuleNames
 461                         ),
 462                         'meta' => array(
 463                                 ApiBase::PARAM_ISMULTI => true,
 464                                 ApiBase::PARAM_TYPE => $this->mMetaModuleNames
 465                         ),
 466                         'generator' => array(
 467                                 ApiBase::PARAM_TYPE => $this->mAllowedGenerators
 468                         ),
 469                         'redirects' => false,
 470                         'indexpageids' => false,
 471                         'export' => false,
 472                         'exportnowrap' => false,
 473                 );
 474         }
 475
 476         /**
 477          * Override the parent to generate help messages for all available query modules.
 478          * @return string
 479          */
 480         public function makeHelpMsg() {
 481                 $msg = '';
 482
 483                 // Make sure the internal object is empty
 484                 // (just in case a sub-module decides to optimize during instantiation)
 485                 $this->mPageSet = null;
 486                 $this->mAllowedGenerators = array(); // Will be repopulated
 487
 488                 $astriks = str_repeat( '--- ', 8 );
 489                 $astriks2 = str_repeat( '*** ', 10 );
 490                 $msg .= "\n$astriks Query: Prop  $astriks\n\n";
 491                 $msg .= $this->makeHelpMsgHelper( $this->mQueryPropModules, 'prop' );
 492                 $msg .= "\n$astriks Query: List  $astriks\n\n";
 493                 $msg .= $this->makeHelpMsgHelper( $this->mQueryListModules, 'list' );
 494                 $msg .= "\n$astriks Query: Meta  $astriks\n\n";
 495                 $msg .= $this->makeHelpMsgHelper( $this->mQueryMetaModules, 'meta' );
 496                 $msg .= "\n\n$astriks2 Modules: continuation  $astriks2\n\n";
 497
 498                 // Perform the base call last because the $this->mAllowedGenerators
 499                 // will be updated inside makeHelpMsgHelper()
 500                 // Use parent to make default message for the query module
 501                 $msg = parent::makeHelpMsg() . $msg;
 502
 503                 return $msg;
 504         }
 505
 506         /**
 507          * For all modules in $moduleList, generate help messages and join them together
 508          * @param $moduleList array(modulename => classname)
 509          * @param $paramName string Parameter name
 510          * @return string
 511          */
 512         private function makeHelpMsgHelper( $moduleList, $paramName ) {
 513                 $moduleDescriptions = array();
 514
 515                 foreach ( $moduleList as $moduleName => $moduleClass ) {
 516                         $module = new $moduleClass ( $this, $moduleName, null );
 517
 518                         $msg = ApiMain::makeHelpMsgHeader( $module, $paramName );
 519                         $msg2 = $module->makeHelpMsg();
 520                         if ( $msg2 !== false ) {
 521                                 $msg .= $msg2;
 522                         }
 523                         if ( $module instanceof ApiQueryGeneratorBase ) {
 524                                 $this->mAllowedGenerators[] = $moduleName;
 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         /**
 534          * Override to add extra parameters from PageSet
 535          * @return string
 536          */
 537         public function makeHelpMsgParameters() {
 538                 $psModule = new ApiPageSet( $this );
 539                 return $psModule->makeHelpMsgParameters() . parent::makeHelpMsgParameters();
 540         }
 541
 542         public function shouldCheckMaxlag() {
 543                 return true;
 544         }
 545
 546         public function getParamDescription() {
 547                 return array(
 548                         'prop' => 'Which properties to get for the titles/revisions/pageids',
 549                         'list' => 'Which lists to get',
 550                         'meta' => 'Which meta data to get about the site',
 551                         'generator' => array( 'Use the output of a list as the input for other prop/list/meta items',
 552                                         'NOTE: generator parameter names must be prefixed with a \'g\', see examples.' ),
 553                         'redirects' => 'Automatically resolve redirects',
 554                         'indexpageids' => 'Include an additional pageids section listing all returned page IDs.',
 555                         'export' => 'Export the current revisions of all given or generated pages',
 556                         'exportnowrap' => 'Return the export XML without wrapping it in an XML result (same format as Special:Export). Can only be used with export',
 557                 );
 558         }
 559
 560         public function getDescription() {
 561                 return array(
 562                         'Query API module allows applications to get needed pieces of data from the MediaWiki databases,',
 563                         'and is loosely based on the old query.php interface.',
 564                         'All data modifications will first have to use query to acquire a token to prevent abuse from malicious sites.'
 565                 );
 566         }
 567
 568         public function getPossibleErrors() {
 569                 return array_merge( parent::getPossibleErrors(), array(
 570                         array( 'code' => 'badgenerator', 'info' => 'Module $generatorName cannot be used as a generator' ),
 571                 ) );
 572         }
 573
 574         protected function getExamples() {
 575                 return array(
 576                         'api.php?action=query&prop=revisions&meta=siteinfo&titles=Main%20Page&rvprop=user|comment',
 577                         'api.php?action=query&generator=allpages&gapprefix=API/&prop=revisions',
 578                 );
 579         }
 580
 581         public function getVersion() {
 582                 $psModule = new ApiPageSet( $this );
 583                 $vers = array();
 584                 $vers[] = __CLASS__ . ': $Id$';
 585                 $vers[] = $psModule->getVersion();
 586                 return $vers;
 587         }
 588 }