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 $mMetaModuleNames, $mPropModuleNames, $mListModuleNames;
  35         private $mData;
  36
  37         private $mQueryMetaModules = array (
  38                 'siteinfo' => 'ApiQuerySiteinfo'
  39         );
  40         //      'userinfo' => 'ApiQueryUserinfo',
  41
  42         private $mQueryPropModules = array (
  43                 'info' => 'ApiQueryInfo',
  44                 'revisions' => 'ApiQueryRevisions'
  45         );
  46         //      'categories' => 'ApiQueryCategories',
  47         //      'imageinfo' => 'ApiQueryImageinfo',
  48         //      'langlinks' => 'ApiQueryLanglinks',
  49         //      'links' => 'ApiQueryLinks',
  50         //      'templates' => 'ApiQueryTemplates',
  51
  52         private $mQueryListModules = array (
  53                 'allpages' => 'ApiQueryAllpages'
  54         );
  55         //      'backlinks' => 'ApiQueryBacklinks',
  56         //      'categorymembers' => 'ApiQueryCategorymembers',
  57         //      'embeddedin' => 'ApiQueryEmbeddedin',
  58         //      'imagelinks' => 'ApiQueryImagelinks',
  59         //      'logevents' => 'ApiQueryLogevents',
  60         //      'recentchanges' => 'ApiQueryRecentchanges',
  61         //      'usercontribs' => 'ApiQueryUsercontribs',
  62         //      'users' => 'ApiQueryUsers',
  63         //      'watchlist' => 'ApiQueryWatchlist',
  64
  65         private $mSlaveDB = null;
  66
  67         public function __construct($main, $action) {
  68                 parent :: __construct($main);
  69                 $this->mMetaModuleNames = array_keys($this->mQueryMetaModules);
  70                 $this->mPropModuleNames = array_keys($this->mQueryPropModules);
  71                 $this->mListModuleNames = array_keys($this->mQueryListModules);
  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 getData() {
  85                 return $this->mData;
  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                 $meta = $prop = $list = $generator = $titles = $pageids = null;
 100                 $redirects = null;
 101                 extract($this->extractRequestParams());
 102
 103                 //
 104                 // Create and initialize PageSet
 105                 //
 106                 $dataSource = null;
 107                 if (isset ($titles) && isset($pageids))
 108                         $this->dieUsage("At present you may not use titles= and pageids= at the same time", 'multisource');
 109
 110                 $this->mData = new ApiPageSet($this, $redirects);
 111
 112                 if (isset($titles))
 113                         $this->mData->populateTitles($titles);
 114
 115                 if (isset($pageids))
 116                         $this->mData->populatePageIDs($pageids);
 117
 118                 //
 119                 // If generator is provided, get a new dataset to work on
 120                 //
 121                 if (isset ($generator))
 122                         $this->executeGenerator($generator, $redirects);
 123
 124                 // Instantiate required modules
 125                 // During instantiation, modules may optimize data requests through the $this->mData object
 126                 // $this->mData will be lazy loaded when modules begin to request data during execution
 127                 $modules = array ();
 128                 if (isset ($meta))
 129                         foreach ($meta as $moduleName)
 130                                 $modules[] = new $this->mQueryMetaModules[$moduleName] ($this, $moduleName);
 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
 138                 // Title normalizations
 139                 foreach ($this->mData->getNormalizedTitles() as $rawTitleStr => $titleStr) {
 140                         $this->getResult()->addMessage('query', 'normalized', array (
 141                                 'from' => $rawTitleStr,
 142                                 'to' => $titleStr,
 143                                 '*' => ''
 144                         ), 'n');
 145                 }
 146
 147                 // Show redirect information
 148                 if ($redirects) {
 149                         foreach ($this->mData->getRedirectTitles() as $titleStrFrom => $titleStrTo) {
 150                                 $this->getResult()->addMessage('query', 'redirects', array (
 151                                         'from' => $titleStrFrom,
 152                                         'to' => $titleStrTo,
 153                                         '*' => ''
 154                                 ), 'r');
 155                         }
 156                 }
 157
 158                 // Execute all requested modules.
 159                 foreach ($modules as $module) {
 160                         $module->profileIn();
 161                         $module->execute();
 162                         $module->profileOut();
 163                 }
 164         }
 165
 166         protected function executeGenerator($generator, $redirects) {
 167
 168                 // Find class that implements requested generator
 169                 if (isset ($this->mQueryListModules[$generator]))
 170                         $className = $this->mQueryListModules[$generator];
 171                 else
 172                         if (isset ($this->mQueryPropModules[$generator]))
 173                                 $className = $this->mQueryPropModules[$generator];
 174                         else
 175                                 $this->dieDebug("Unknown generator=$generator");
 176
 177                 $module = new $className ($this, $generator, true);
 178
 179                 // change $this->mData
 180
 181                 // TODO: implement
 182                 $this->dieUsage("Generator execution has not been implemented", 'notimplemented');
 183         }
 184
 185         protected function getAllowedParams() {
 186                 return array (
 187                         'meta' => array (
 188                                 GN_ENUM_ISMULTI => true,
 189                                 GN_ENUM_TYPE => $this->mMetaModuleNames
 190                         ),
 191                         'prop' => array (
 192                                 GN_ENUM_ISMULTI => true,
 193                                 GN_ENUM_TYPE => $this->mPropModuleNames
 194                         ),
 195                         'list' => array (
 196                                 GN_ENUM_ISMULTI => true,
 197                                 GN_ENUM_TYPE => $this->mListModuleNames
 198                         ),
 199                         //                      'generator' => array (
 200                         //                              GN_ENUM_TYPE => $this->mAllowedGenerators
 201                         //                      ),
 202                         'titles' => array (
 203                                 GN_ENUM_ISMULTI => true
 204                         ),
 205                         //                      'pageids' => array (
 206                         //                              GN_ENUM_TYPE => 'integer',
 207                         //                              GN_ENUM_ISMULTI => true
 208                         //                      ),
 209                         'redirects' => false
 210                 );
 211         }
 212
 213         /**
 214          * Override the parent to generate help messages for all available query modules.
 215          */
 216         public function makeHelpMsg() {
 217
 218                 // Use parent to make default message for the query module
 219                 $msg = parent :: makeHelpMsg();
 220
 221                 // Make sure the internal object is empty
 222                 // (just in case a sub-module decides to optimize during instantiation)
 223                 $this->mData = null;
 224
 225                 $astriks = str_repeat('--- ', 8);
 226                 $msg .= "\n$astriks Query: Meta  $astriks\n\n";
 227                 $msg .= $this->makeHelpMsgHelper($this->mQueryMetaModules, 'meta');
 228                 $msg .= "\n$astriks Query: Prop  $astriks\n\n";
 229                 $msg .= $this->makeHelpMsgHelper($this->mQueryPropModules, 'prop');
 230                 $msg .= "\n$astriks Query: List  $astriks\n\n";
 231                 $msg .= $this->makeHelpMsgHelper($this->mQueryListModules, 'list');
 232
 233                 return $msg;
 234         }
 235
 236         private function makeHelpMsgHelper($moduleList, $paramName) {
 237                 $msg = '';
 238
 239                 foreach ($moduleList as $moduleName => $moduleClass) {
 240                         $msg .= "* $paramName=$moduleName *";
 241                         $module = new $moduleClass ($this, $moduleName, null);
 242                         $msg2 = $module->makeHelpMsg();
 243                         if ($msg2 !== false)
 244                                 $msg .= $msg2;
 245                         $msg .= "\n";
 246                         if ($module->getCanGenerate())
 247                                 $msg .= "  * Can be used as a generator\n";
 248                 }
 249
 250                 return $msg;
 251         }
 252
 253         protected function getParamDescription() {
 254                 return array (
 255                         'meta' => 'Which meta data to get about the site',
 256                         'prop' => 'Which properties to get for the titles/revisions/pageids',
 257                         'list' => 'Which lists to get',
 258                         'generator' => 'Use the output of a list as the input for other prop/list/meta items',
 259                         'titles' => 'A list of titles to work on',
 260                         'pageids' => 'A list of page IDs to work on',
 261                         'redirects' => 'Automatically resolve redirects'
 262                 );
 263         }
 264
 265         protected function getDescription() {
 266                 return array (
 267                         'Query API module allows applications to get needed pieces of data from the MediaWiki databases,',
 268                         'and is loosely based on the Query API interface currently available on all MediaWiki servers.',
 269                         'All data modifications will first have to use query to acquire a token to prevent abuse from malicious sites.'
 270                 );
 271         }
 272
 273         protected function getExamples() {
 274                 return array (
 275                         'api.php?action=query&what=content&titles=ArticleA|ArticleB'
 276                 );
 277         }
 278 }
 279 ?>