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