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