includes/api/ApiQuery.php

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