includes/api/ApiQuery.php

   1 <?php
   2
   3
   4 /*
   5  * Created on Sep 7, 2006
   6  *
   7  * API for MediaWiki 1.8+
   8  *
   9  * Copyright (C) 2006 Yuri Astrakhan <FirstnameLastname@gmail.com>
  10  *
  11  * This program is free software; you can redistribute it and/or modify
  12  * it under the terms of the GNU General Public License as published by
  13  * the Free Software Foundation; either version 2 of the License, or
  14  * (at your option) any later version.
  15  *
  16  * This program is distributed in the hope that it will be useful,
  17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  19  * GNU General Public License for more details.
  20  *
  21  * You should have received a copy of the GNU General Public License along
  22  * with this program; if not, write to the Free Software Foundation, Inc.,
  23  * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  24  * http://www.gnu.org/copyleft/gpl.html
  25  */
  26
  27 if (!defined('MEDIAWIKI')) {
  28         // Eclipse helper - will be ignored in production
  29         require_once ('ApiBase.php');
  30 }
  31
  32 class ApiQuery extends ApiBase {
  33
  34         private $mPropModuleNames, $mListModuleNames, $mMetaModuleNames;
  35         private $mPageSet;
  36         private $mValidNamespaces;
  37
  38         private $mQueryPropModules = array (
  39                 'info' => 'ApiQueryInfo',
  40                 'revisions' => 'ApiQueryRevisions'
  41         );
  42         //      'categories' => 'ApiQueryCategories',
  43         //      'imageinfo' => 'ApiQueryImageinfo',
  44         //      'langlinks' => 'ApiQueryLanglinks',
  45         //      'links' => 'ApiQueryLinks',
  46         //      'templates' => 'ApiQueryTemplates',
  47
  48         private $mQueryListModules = array (
  49                 'allpages' => 'ApiQueryAllpages',
  50                 'watchlist' => 'ApiQueryWatchlist'
  51         );
  52         //      'backlinks' => 'ApiQueryBacklinks',
  53         //      'categorymembers' => 'ApiQueryCategorymembers',
  54         //      'embeddedin' => 'ApiQueryEmbeddedin',
  55         //      'imagelinks' => 'ApiQueryImagelinks',
  56         //      'logevents' => 'ApiQueryLogevents',
  57         //      'recentchanges' => 'ApiQueryRecentchanges',
  58         //      'usercontribs' => 'ApiQueryUsercontribs',
  59         //      'users' => 'ApiQueryUsers',
  60         //      'watchlist' => 'ApiQueryWatchlist',
  61
  62         private $mQueryMetaModules = array (
  63                 'siteinfo' => 'ApiQuerySiteinfo'
  64         );
  65         //      'userinfo' => 'ApiQueryUserinfo',
  66
  67         private $mSlaveDB = null;
  68
  69         public function __construct($main, $action) {
  70                 parent :: __construct($main, $action);
  71                 $this->mPropModuleNames = array_keys($this->mQueryPropModules);
  72                 $this->mListModuleNames = array_keys($this->mQueryListModules);
  73                 $this->mMetaModuleNames = array_keys($this->mQueryMetaModules);
  74                 $this->mValidNamespaces = null;
  75
  76                 // Allow the entire list of modules at first,
  77                 // but during module instantiation check if it can be used as a generator.
  78                 $this->mAllowedGenerators = array_merge($this->mListModuleNames, $this->mPropModuleNames);
  79         }
  80
  81         public function getDB() {
  82                 if (!isset ($this->mSlaveDB))
  83                         $this->mSlaveDB = & wfGetDB(DB_SLAVE);
  84                 return $this->mSlaveDB;
  85         }
  86
  87         public function getPageSet() {
  88                 return $this->mPageSet;
  89         }
  90
  91         public function getValidNamespaces() {
  92                 global $wgContLang;
  93
  94                 if (is_null($this->mValidNamespaces)) {
  95                         $this->mValidNamespaces = array ();
  96                         foreach (array_keys($wgContLang->getNamespaces()) as $ns) {
  97                                 if ($ns >= 0)
  98                                         $this->mValidNamespaces[] = $ns; // strval($ns);
  99                         }
 100                 }
 101                 return $this->mValidNamespaces;
 102         }
 103
 104         /**
 105          * Query execution happens in the following steps:
 106          * #1 Create a PageSet object with any pages requested by the user
 107          * #2 If using generator, execute it to get a new PageSet object
 108          * #3 Instantiate all requested modules.
 109          *    This way the PageSet object will know what shared data is required,
 110          *    and minimize DB calls.
 111          * #4 Output all normalization and redirect resolution information
 112          * #5 Execute all requested modules
 113          */
 114         public function execute() {
 115                 $prop = $list = $meta = $generator = $redirects = null;
 116                 extract($this->extractRequestParams());
 117
 118                 //
 119                 // Create PageSet
 120                 //
 121                 $this->mPageSet = new ApiPageSet($this, $redirects);
 122
 123                 // Instantiate required modules
 124                 $modules = array ();
 125                 if (isset ($prop))
 126                         foreach ($prop as $moduleName)
 127                                 $modules[] = new $this->mQueryPropModules[$moduleName] ($this, $moduleName);
 128                 if (isset ($list))
 129                         foreach ($list as $moduleName)
 130                                 $modules[] = new $this->mQueryListModules[$moduleName] ($this, $moduleName);
 131                 if (isset ($meta))
 132                         foreach ($meta as $moduleName)
 133                                 $modules[] = new $this->mQueryMetaModules[$moduleName] ($this, $moduleName);
 134
 135                 // Modules may optimize data requests through the $this->getPageSet() object
 136                 // Execute all requested modules.
 137                 foreach ($modules as $module) {
 138                         $module->requestExtraData();
 139                 }
 140
 141                 //
 142                 // If given, execute generator to substitute user supplied data with generated data.
 143                 //
 144                 if (isset ($generator))
 145                         $this->executeGeneratorModule($generator, $redirects);
 146
 147                 //
 148                 // Populate page information for the given pageSet
 149                 //
 150                 $this->mPageSet->execute();
 151
 152                 //
 153                 // Record page information (title, namespace, if exists, etc)
 154                 //
 155                 $this->outputGeneralPageInfo();
 156
 157                 //
 158                 // Execute all requested modules.
 159                 //
 160                 foreach ($modules as $module) {
 161                         $module->profileIn();
 162                         $module->execute();
 163                         $module->profileOut();
 164                 }
 165         }
 166
 167         private function outputGeneralPageInfo() {
 168
 169                 $pageSet = $this->getPageSet();
 170
 171                 // Title normalizations
 172                 $normValues = array ();
 173                 foreach ($pageSet->getNormalizedTitles() as $rawTitleStr => $titleStr) {
 174                         $normValues[] = array (
 175                                 'from' => $rawTitleStr,
 176                                 'to' => $titleStr
 177                         );
 178                 }
 179
 180                 if (!empty ($normValues)) {
 181                         ApiResult :: setIndexedTagName($normValues, 'n');
 182                         $this->getResult()->addValue('query', 'normalized', $normValues);
 183                 }
 184
 185                 // Show redirect information
 186                 $redirValues = array ();
 187                 foreach ($pageSet->getRedirectTitles() as $titleStrFrom => $titleStrTo) {
 188                         $redirValues[] = array (
 189                                 'from' => $titleStrFrom,
 190                                 'to' => $titleStrTo
 191                         );
 192                 }
 193
 194                 if (!empty ($redirValues)) {
 195                         ApiResult :: setIndexedTagName($redirValues, 'r');
 196                         $this->getResult()->addValue('query', 'redirects', $redirValues);
 197                 }
 198
 199
 200                 //
 201                 // Missing revision elements
 202                 //
 203                 $missingRevIDs = $pageSet->getMissingRevisionIDs();
 204                 if (!empty($missingRevIDs)) {
 205                         $revids = array();
 206                         foreach ($missingRevIDs as $revid) {
 207                                 $revids[$revid] = array (
 208                                         'revid' => $revid
 209                                 );
 210                         }
 211                         ApiResult :: setIndexedTagName($revids, 'rev');
 212                         $this->getResult()->addValue('query', 'badrevids', $revids);
 213                 }
 214
 215                 //
 216                 // Page elements
 217                 //
 218                 $pages = array ();
 219
 220                 // Report any missing titles
 221                 $fakepageid = -1;
 222                 foreach ($pageSet->getMissingTitles() as $title) {
 223                         $pages[$fakepageid--] = array (
 224                         'ns' => $title->getNamespace(), 'title' => $title->getPrefixedText(), 'missing' => '');
 225                 }
 226
 227                 // Report any missing page ids
 228                 foreach ($pageSet->getMissingPageIDs() as $pageid) {
 229                         $pages[$pageid] = array (
 230                                 'id' => $pageid,
 231                                 'missing' => ''
 232                         );
 233                 }
 234
 235                 // Output general page information for found titles
 236                 foreach ($pageSet->getGoodTitles() as $pageid => $title) {
 237                         $pages[$pageid] = array (
 238                         'ns' => $title->getNamespace(), 'title' => $title->getPrefixedText(), 'id' => $pageid);
 239                 }
 240
 241                 if (!empty ($pages)) {
 242                         ApiResult :: setIndexedTagName($pages, 'page');
 243                         $this->getResult()->addValue('query', 'pages', $pages);
 244                 }
 245         }
 246
 247         protected function executeGeneratorModule($generatorName, $redirects) {
 248
 249                 // Find class that implements requested generator
 250                 if (isset ($this->mQueryListModules[$generatorName])) {
 251                         $className = $this->mQueryListModules[$generatorName];
 252                 }
 253                 elseif (isset ($this->mQueryPropModules[$generatorName])) {
 254                         $className = $this->mQueryPropModules[$generatorName];
 255                 } else {
 256                         ApiBase :: dieDebug(__METHOD__, "Unknown generator=$generatorName");
 257                 }
 258
 259                 // Use current pageset as the result, and create a new one just for the generator
 260                 $resultPageSet = $this->mPageSet;
 261                 $this->mPageSet = new ApiPageSet($this, $redirects);
 262
 263                 // Create and execute the generator
 264                 $generator = new $className ($this, $generatorName);
 265                 if (!$generator instanceof ApiQueryGeneratorBase)
 266                         $this->dieUsage("Module $generatorName cannot be used as a generator", "badgenerator");
 267
 268                 $generator->setGeneratorMode();
 269                 $generator->requestExtraData();
 270
 271                 // execute current pageSet to get the data for the generator module
 272                 $this->mPageSet->execute();
 273
 274                 // populate resultPageSet with the generator output
 275                 $generator->profileIn();
 276                 $generator->executeGenerator($resultPageSet);
 277                 $resultPageSet->finishPageSetGeneration();
 278                 $generator->profileOut();
 279
 280                 // Swap the resulting pageset back in
 281                 $this->mPageSet = $resultPageSet;
 282         }
 283
 284         protected function getAllowedParams() {
 285                 return array (
 286                         'prop' => array (
 287                                 ApiBase :: PARAM_ISMULTI => true,
 288                                 ApiBase :: PARAM_TYPE => $this->mPropModuleNames
 289                         ),
 290                         'list' => array (
 291                                 ApiBase :: PARAM_ISMULTI => true,
 292                                 ApiBase :: PARAM_TYPE => $this->mListModuleNames
 293                         ),
 294                         'meta' => array (
 295                                 ApiBase :: PARAM_ISMULTI => true,
 296                                 ApiBase :: PARAM_TYPE => $this->mMetaModuleNames
 297                         ),
 298                         'generator' => array (
 299                                 ApiBase :: PARAM_TYPE => $this->mAllowedGenerators
 300                         ),
 301                         'redirects' => false
 302                 );
 303         }
 304
 305         /**
 306          * Override the parent to generate help messages for all available query modules.
 307          */
 308         public function makeHelpMsg() {
 309
 310                 // Use parent to make default message for the query module
 311                 $msg = parent :: makeHelpMsg();
 312
 313                 // Make sure the internal object is empty
 314                 // (just in case a sub-module decides to optimize during instantiation)
 315                 $this->mPageSet = null;
 316
 317                 $astriks = str_repeat('--- ', 8);
 318                 $msg .= "\n$astriks Query: Prop  $astriks\n\n";
 319                 $msg .= $this->makeHelpMsgHelper($this->mQueryPropModules, 'prop');
 320                 $msg .= "\n$astriks Query: List  $astriks\n\n";
 321                 $msg .= $this->makeHelpMsgHelper($this->mQueryListModules, 'list');
 322                 $msg .= "\n$astriks Query: Meta  $astriks\n\n";
 323                 $msg .= $this->makeHelpMsgHelper($this->mQueryMetaModules, 'meta');
 324
 325                 return $msg;
 326         }
 327
 328         private function makeHelpMsgHelper($moduleList, $paramName) {
 329
 330                 $moduleDscriptions = array ();
 331
 332                 foreach ($moduleList as $moduleName => $moduleClass) {
 333                         $msg = "* $paramName=$moduleName *";
 334                         $module = new $moduleClass ($this, $moduleName, null);
 335                         $msg2 = $module->makeHelpMsg();
 336                         if ($msg2 !== false)
 337                                 $msg .= $msg2;
 338                         if ($module instanceof ApiQueryGeneratorBase)
 339                                 $msg .= "Generator:\n  This module may be used as a generator\n";
 340                         $moduleDscriptions[] = $msg;
 341                 }
 342
 343                 return implode("\n", $moduleDscriptions);
 344         }
 345
 346         /**
 347          * Override to add extra parameters from PageSet
 348          */
 349         public function makeHelpMsgParameters() {
 350                 $psModule = new ApiPageSet($this);
 351                 return $psModule->makeHelpMsgParameters() . parent :: makeHelpMsgParameters();
 352         }
 353
 354         protected function getParamDescription() {
 355                 return array (
 356                         'prop' => 'Which properties to get for the titles/revisions/pageids',
 357                         'list' => 'Which lists to get',
 358                         'meta' => 'Which meta data to get about the site',
 359                         'generator' => 'Use the output of a list as the input for other prop/list/meta items',
 360                         'redirects' => 'Automatically resolve redirects'
 361                 );
 362         }
 363
 364         protected function getDescription() {
 365                 return array (
 366                         'Query API module allows applications to get needed pieces of data from the MediaWiki databases,',
 367                         'and is loosely based on the Query API interface currently available on all MediaWiki servers.',
 368                         'All data modifications will first have to use query to acquire a token to prevent abuse from malicious sites.'
 369                 );
 370         }
 371
 372         protected function getExamples() {
 373                 return array (
 374                         'api.php?action=query&prop=revisions&meta=siteinfo&titles=Main%20Page&rvprop=user|comment'
 375                 );
 376         }
 377
 378         public function getVersion() {
 379                 $psModule = new ApiPageSet($this);
 380                 $vers = array ();
 381                 $vers[] = __CLASS__ . ': $Id$';
 382                 $vers[] = $psModule->getVersion();
 383                 return $vers;
 384         }
 385 }
 386 ?>