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