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