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