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         var $mMetaModuleNames, $mPropModuleNames, $mListModuleNames;
  35
  36         private $mQueryMetaModules = array (
  37                 'siteinfo' => 'ApiQuerySiteinfo',
  38                         //'userinfo' => 'ApiQueryUserinfo'
  39
  40
  41         );
  42
  43         private $mQueryPropModules = array (
  44                 'info' => 'ApiQueryInfo',
  45                         //              'categories' => 'ApiQueryCategories',
  46                 //              'imageinfo' => 'ApiQueryImageinfo',
  47                 //              'langlinks' => 'ApiQueryLanglinks',
  48                 //              'links' => 'ApiQueryLinks',
  49                 //              'templates' => 'ApiQueryTemplates',
  50                 //              'revisions' => 'ApiQueryRevisions',
  51
  52                 // Should be removed
  53         'content' => 'ApiQueryContent'
  54         );
  55
  56         private $mQueryListModules = array (
  57                 'allpages' => 'ApiQueryAllpages',
  58                         //              'backlinks' => 'ApiQueryBacklinks',
  59                 //              'categorymembers' => 'ApiQueryCategorymembers',
  60                 //              'embeddedin' => 'ApiQueryEmbeddedin',
  61                 //              'imagelinks' => 'ApiQueryImagelinks',
  62                 //              'logevents' => 'ApiQueryLogevents',
  63                 //              'recentchanges' => 'ApiQueryRecentchanges',
  64                 //              'usercontribs' => 'ApiQueryUsercontribs',
  65                 //              'users' => 'ApiQueryUsers',
  66                 //              'watchlist' => 'ApiQueryWatchlist'
  67
  68
  69         );
  70
  71         private $mSlaveDB = null;
  72
  73         public function __construct($main, $action) {
  74                 parent :: __construct($main);
  75                 $this->mMetaModuleNames = array_keys($this->mQueryMetaModules);
  76                 $this->mPropModuleNames = array_keys($this->mQueryPropModules);
  77                 $this->mListModuleNames = array_keys($this->mQueryListModules);
  78
  79                 $this->mAllowedGenerators = array_merge($this->mListModuleNames, $this->mPropModuleNames);
  80         }
  81
  82         public function GetDB() {
  83                 if (!isset ($this->mSlaveDB))
  84                         $this->mSlaveDB = & wfGetDB(DB_SLAVE);
  85                 return $this->mSlaveDB;
  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 = $revids = null;
 100                 $redirects = null;
 101                 extract($this->ExtractRequestParams());
 102
 103                 //
 104                 // Create and initialize PageSet
 105                 //
 106                 // Only one of the titles/pageids/revids is allowed at the same time
 107                 $dataSource = null;
 108                 if (isset ($titles))
 109                         $dataSource = 'titles';
 110                 if (isset ($pageids)) {
 111                         if (isset ($dataSource))
 112                                 $this->DieUsage("Cannot use 'pageids' at the same time as '$dataSource'", 'multisource');
 113                         $dataSource = 'pageids';
 114                 }
 115                 if (isset ($revids)) {
 116                         if (isset ($dataSource))
 117                                 $this->DieUsage("Cannot use 'revids' at the same time as '$dataSource'", 'multisource');
 118                         $dataSource = 'revids';
 119                 }
 120
 121                 $data = new ApiPageSet($this->GetMain(), $this->GetDB(), $redirects);
 122
 123                 switch ($dataSource) {
 124                         case 'titles' :
 125                                 $data->PopulateTitles($titles);
 126                                 break;
 127                         case 'pageids' :
 128                                 $data->PopulatePageIDs($pageids);
 129                                 break;
 130                         case 'titles' :
 131                                 $data->PopulateRevIDs($revids);
 132                                 break;
 133                         default :
 134                                 // Do nothing - some queries do not need any of the data sources.
 135                                 break;
 136                 }
 137
 138                 //
 139                 // If generator is provided, get a new dataset to work on
 140                 //
 141                 if (isset ($generator))
 142                         $data = $this->ExecuteGenerator($generator, $data, $redirects);
 143
 144                 // Instantiate required modules
 145                 // During instantiation, modules may optimize data requests through the $data object
 146                 // $data will be lazy loaded when modules begin to request data during execution
 147                 $modules = array ();
 148                 if (isset($meta))
 149                         foreach ($meta as $moduleName)
 150                                 $modules[] = new $this->mQueryMetaModules[$moduleName] ($this, $moduleName, $data);
 151                 if (isset($prop))
 152                         foreach ($prop as $moduleName)
 153                                 $modules[] = new $this->mQueryPropModules[$moduleName] ($this, $moduleName, $data);
 154                 if (isset($list))
 155                         foreach ($list as $moduleName)
 156                                 $modules[] = new $this->mQueryListModules[$moduleName] ($this, $moduleName, $data);
 157
 158                 // Title normalizations
 159                 foreach ($data->GetNormalizedTitles() as $rawTitleStr => $titleStr) {
 160                         $this->GetResult()->AddMessage('query', 'normalized', array (
 161                                 'from' => $rawTitleStr,
 162                                 'to' => $titleStr
 163                         ), 'n');
 164                 }
 165
 166                 // Show redirect information
 167                 if ($redirects) {
 168                         foreach ($data->GetRedirectTitles() as $titleStrFrom => $titleStrTo) {
 169                                 $this->GetResult()->AddMessage('query', 'redirects', array (
 170                                         'from' => $titleStrFrom,
 171                                         'to' => $titleStrTo
 172                                 ), 'r');
 173                         }
 174                 }
 175
 176                 // Execute all requested modules.
 177                 foreach ($modules as $module)
 178                         $module->Execute();
 179         }
 180
 181         protected function ExecuteGenerator($generator, $data, $redirects) {
 182                 // TODO: implement
 183                 $this->DieUsage("Generator execution has not been implemented", 'notimplemented');
 184         }
 185
 186         protected function GetAllowedParams() {
 187                 return array (
 188                         'meta' => array (
 189                                 GN_ENUM_ISMULTI => true,
 190                                 GN_ENUM_CHOICES => $this->mMetaModuleNames
 191                         ),
 192                         'prop' => array (
 193                                 GN_ENUM_ISMULTI => true,
 194                                 GN_ENUM_CHOICES => $this->mPropModuleNames
 195                         ),
 196                         'list' => array (
 197                                 GN_ENUM_ISMULTI => true,
 198                                 GN_ENUM_CHOICES => $this->mListModuleNames
 199                         ),
 200                         //                      'generator' => array (
 201                         //                              GN_ENUM_CHOICES => $this->mAllowedGenerators
 202                         //                      ),
 203                         'titles' => array (
 204                                 GN_ENUM_ISMULTI => true
 205                         ),
 206                         //                      'pageids' => array (
 207                         //                              GN_ENUM_TYPE => 'integer',
 208                         //                              GN_ENUM_ISMULTI => true
 209                         //                      ),
 210                         //                      'revids' => array (
 211                         //                              GN_ENUM_TYPE => 'integer',
 212                         //                              GN_ENUM_ISMULTI => true
 213                         //                      ),
 214                         'redirects' => false
 215                 );
 216         }
 217
 218         protected function GetParamDescription() {
 219                 return array (
 220                         'meta' => 'Which meta data to get about the site',
 221                         'prop' => 'Which properties to get for the titles/revisions/pageids',
 222                         'list' => 'Which lists to get',
 223                         'generator' => 'Use the output of a list as the input for other prop/list/meta items',
 224                         'titles' => 'A list of titles to work on',
 225                         'pageids' => 'A list of page IDs to work on',
 226                         'revids' => 'A list of revision IDs to work on',
 227                         'redirects' => 'Automatically resolve redirects'
 228                 );
 229         }
 230
 231         protected function GetDescription() {
 232                 return array (
 233                         'Query API module allows applications to get needed pieces of data from the MediaWiki databases,',
 234                         'and is loosely based on the Query API interface currently available on all MediaWiki servers.',
 235                         'All data modifications will first have to use query to acquire a token to prevent abuse from malicious sites.'
 236                 );
 237         }
 238
 239         protected function GetExamples() {
 240                 return array (
 241                         'api.php?action=query&what=content&titles=ArticleA|ArticleB'
 242                 );
 243         }
 244 }
 245 ?>