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                 // Page elements
 200                 //
 201                 $pages = array ();
 202
 203                 // Report any missing titles
 204                 $fakepageid = -1;
 205                 foreach ($pageSet->getMissingTitles() as $title) {
 206                         $pages[$fakepageid--] = array (
 207                         'ns' => $title->getNamespace(), 'title' => $title->getPrefixedText(), 'missing' => '');
 208                 }
 209
 210                 // Report any missing page ids
 211                 foreach ($pageSet->getMissingPageIDs() as $pageid) {
 212                         $pages[$pageid] = array (
 213                                 'id' => $pageid,
 214                                 'missing' => ''
 215                         );
 216                 }
 217
 218                 // Output general page information for found titles
 219                 foreach ($pageSet->getGoodTitles() as $pageid => $title) {
 220                         $pages[$pageid] = array (
 221                         'ns' => $title->getNamespace(), 'title' => $title->getPrefixedText(), 'id' => $pageid);
 222                 }
 223
 224                 if (!empty ($pages)) {
 225                         ApiResult :: setIndexedTagName($pages, 'page');
 226                         $this->getResult()->addValue('query', 'pages', $pages);
 227                 }
 228         }
 229
 230         protected function executeGeneratorModule($generatorName, $redirects) {
 231
 232                 // Find class that implements requested generator
 233                 if (isset ($this->mQueryListModules[$generatorName])) {
 234                         $className = $this->mQueryListModules[$generatorName];
 235                 }
 236                 elseif (isset ($this->mQueryPropModules[$generatorName])) {
 237                         $className = $this->mQueryPropModules[$generatorName];
 238                 } else {
 239                         ApiBase :: dieDebug(__METHOD__, "Unknown generator=$generatorName");
 240                 }
 241
 242                 // Use current pageset as the result, and create a new one just for the generator
 243                 $resultPageSet = $this->mPageSet;
 244                 $this->mPageSet = new ApiPageSet($this, $redirects);
 245
 246                 // Create and execute the generator
 247                 $generator = new $className ($this, $generatorName);
 248                 if (!$generator instanceof ApiQueryGeneratorBase)
 249                         $this->dieUsage("Module $generatorName cannot be used as a generator", "badgenerator");
 250
 251                 $generator->setGeneratorMode();
 252                 $generator->requestExtraData();
 253
 254                 // execute current pageSet to get the data for the generator module
 255                 $this->mPageSet->execute();
 256
 257                 // populate resultPageSet with the generator output
 258                 $generator->profileIn();
 259                 $generator->executeGenerator($resultPageSet);
 260                 $resultPageSet->finishPageSetGeneration();
 261                 $generator->profileOut();
 262
 263                 // Swap the resulting pageset back in
 264                 $this->mPageSet = $resultPageSet;
 265         }
 266
 267         protected function getAllowedParams() {
 268                 return array (
 269                         'prop' => array (
 270                                 ApiBase :: PARAM_ISMULTI => true,
 271                                 ApiBase :: PARAM_TYPE => $this->mPropModuleNames
 272                         ),
 273                         'list' => array (
 274                                 ApiBase :: PARAM_ISMULTI => true,
 275                                 ApiBase :: PARAM_TYPE => $this->mListModuleNames
 276                         ),
 277                         'meta' => array (
 278                                 ApiBase :: PARAM_ISMULTI => true,
 279                                 ApiBase :: PARAM_TYPE => $this->mMetaModuleNames
 280                         ),
 281                         'generator' => array (
 282                                 ApiBase :: PARAM_TYPE => $this->mAllowedGenerators
 283                         ),
 284                         'redirects' => false
 285                 );
 286         }
 287
 288         /**
 289          * Override the parent to generate help messages for all available query modules.
 290          */
 291         public function makeHelpMsg() {
 292
 293                 // Use parent to make default message for the query module
 294                 $msg = parent :: makeHelpMsg();
 295
 296                 // Make sure the internal object is empty
 297                 // (just in case a sub-module decides to optimize during instantiation)
 298                 $this->mPageSet = null;
 299
 300                 $astriks = str_repeat('--- ', 8);
 301                 $msg .= "\n$astriks Query: Prop  $astriks\n\n";
 302                 $msg .= $this->makeHelpMsgHelper($this->mQueryPropModules, 'prop');
 303                 $msg .= "\n$astriks Query: List  $astriks\n\n";
 304                 $msg .= $this->makeHelpMsgHelper($this->mQueryListModules, 'list');
 305                 $msg .= "\n$astriks Query: Meta  $astriks\n\n";
 306                 $msg .= $this->makeHelpMsgHelper($this->mQueryMetaModules, 'meta');
 307
 308                 return $msg;
 309         }
 310
 311         private function makeHelpMsgHelper($moduleList, $paramName) {
 312
 313                 $moduleDscriptions = array ();
 314
 315                 foreach ($moduleList as $moduleName => $moduleClass) {
 316                         $msg = "* $paramName=$moduleName *";
 317                         $module = new $moduleClass ($this, $moduleName, null);
 318                         $msg2 = $module->makeHelpMsg();
 319                         if ($msg2 !== false)
 320                                 $msg .= $msg2;
 321                         if ($module instanceof ApiQueryGeneratorBase)
 322                                 $msg .= "Generator:\n  This module may be used as a generator\n";
 323                         $moduleDscriptions[] = $msg;
 324                 }
 325
 326                 return implode("\n", $moduleDscriptions);
 327         }
 328
 329         /**
 330          * Override to add extra parameters from PageSet
 331          */
 332         public function makeHelpMsgParameters() {
 333                 $psModule = new ApiPageSet($this);
 334                 return $psModule->makeHelpMsgParameters() . parent :: makeHelpMsgParameters();
 335         }
 336
 337         protected function getParamDescription() {
 338                 return array (
 339                         'prop' => 'Which properties to get for the titles/revisions/pageids',
 340                         'list' => 'Which lists to get',
 341                         'meta' => 'Which meta data to get about the site',
 342                         'generator' => 'Use the output of a list as the input for other prop/list/meta items',
 343                         'redirects' => 'Automatically resolve redirects'
 344                 );
 345         }
 346
 347         protected function getDescription() {
 348                 return array (
 349                         'Query API module allows applications to get needed pieces of data from the MediaWiki databases,',
 350                         'and is loosely based on the Query API interface currently available on all MediaWiki servers.',
 351                         'All data modifications will first have to use query to acquire a token to prevent abuse from malicious sites.'
 352                 );
 353         }
 354
 355         protected function getExamples() {
 356                 return array (
 357                         'api.php?action=query&prop=revisions&meta=siteinfo&titles=Main%20Page&rvprop=user|comment'
 358                 );
 359         }
 360
 361         public function getVersion() {
 362                 $psModule = new ApiPageSet($this);
 363                 $vers = array ();
 364                 $vers[] = __CLASS__ . ': $Id$';
 365                 $vers[] = $psModule->getVersion();
 366                 return $vers;
 367         }
 368 }
 369 ?>