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