includes/api/ApiMain.php

   1 <?php
   2
   3
   4 /*
   5  * Created on Sep 4, 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 ApiMain extends ApiBase {
  33
  34         private $mPrinter, $mModules, $mModuleNames, $mFormats, $mFormatNames, $mApiStartTime, $mResult;
  35
  36         /**
  37         * Constructor
  38         * $apiStartTime - time of the originating call for profiling purposes
  39         * $modules - an array of actions (keys) and classes that handle them (values)
  40         */
  41         public function __construct($apiStartTime, $modules, $formats) {
  42                 // Special handling for the main module: $parent === $this
  43                 parent :: __construct($this);
  44
  45                 $this->mModules = $modules;
  46                 $this->mModuleNames = array_keys($modules);
  47                 $this->mFormats = $formats;
  48                 $this->mFormatNames = array_keys($formats);
  49                 $this->mApiStartTime = $apiStartTime;
  50                 $this->mResult = new ApiResult($this);
  51         }
  52
  53         public function & getResult() {
  54                 return $this->mResult;
  55         }
  56
  57         protected function getAllowedParams() {
  58                 return array (
  59                         'format' => array (
  60                                 GN_ENUM_DFLT => API_DEFAULT_FORMAT,
  61                                 GN_ENUM_TYPE => $this->mFormatNames
  62                         ),
  63                         'action' => array (
  64                                 GN_ENUM_DFLT => 'help',
  65                                 GN_ENUM_TYPE => $this->mModuleNames
  66                         )
  67                 );
  68         }
  69
  70         protected function getParamDescription() {
  71                 return array (
  72                         'format' => 'The format of the output',
  73                         'action' => 'What action you would like to perform'
  74                 );
  75         }
  76
  77         public function execute() {
  78                 $this->profileIn();
  79                 $action = $format = null;
  80                 try {
  81                         extract($this->extractRequestParams());
  82
  83                         // Create an appropriate printer
  84                         $this->mPrinter = new $this->mFormats[$format] ($this, $format);
  85
  86                         // Instantiate and execute module requested by the user
  87                         $module = new $this->mModules[$action] ($this, $action);
  88                         $module->profileIn();
  89                         $module->execute();
  90                         $module->profileOut();
  91                         $this->printResult(false);
  92                 } catch (UsageException $e) {
  93                         // Printer may not be initialized if the extractRequestParams() fails for the main module
  94                         if (!isset ($this->mPrinter))
  95                                 $this->mPrinter = new $this->mFormats[API_DEFAULT_FORMAT] ($this, API_DEFAULT_FORMAT);
  96                         $this->printResult(true);
  97                 }
  98                 $this->profileOut();
  99         }
 100
 101         /**
 102          * Internal printer
 103          */
 104         private function printResult($isError) {
 105                 $printer = $this->mPrinter;
 106                 $printer->profileIn();
 107                 $printer->initPrinter($isError);
 108                 if (!$printer->getNeedsRawData())
 109                         $this->getResult()->SanitizeData();
 110                 $printer->execute();
 111                 $printer->closePrinter();
 112                 $printer->profileOut();
 113         }
 114
 115         protected function getDescription() {
 116                 return array (
 117                         '',
 118                         'This API allows programs to access various functions of MediaWiki software.',
 119                         'For more details see API Home Page @ http://meta.wikimedia.org/wiki/API',
 120                         ''
 121                 );
 122         }
 123
 124         public function mainDieUsage($description, $errorCode, $httpRespCode = 0) {
 125                 $this->mResult->Reset();
 126                 if ($httpRespCode === 0)
 127                         header($errorCode, true);
 128                 else
 129                         header($errorCode, true, $httpRespCode);
 130
 131                 $data = array (
 132                         'code' => $errorCode
 133                 );
 134                 ApiResult :: addContent($data, $this->makeHelpMsg());
 135                 $this->mResult->addValue(null, 'error', $data);
 136
 137                 throw new UsageException($description, $errorCode);
 138         }
 139
 140         /**
 141          * Override the parent to generate help messages for all available modules.
 142          */
 143         public function makeHelpMsg() {
 144
 145                 // Use parent to make default message for the main module
 146                 $msg = parent :: makeHelpMsg();
 147
 148                 $astriks = str_repeat('*** ', 10);
 149                 $msg .= "\n\n$astriks Modules  $astriks\n\n";
 150                 foreach ($this->mModules as $moduleName => $moduleClass) {
 151                         $msg .= "* action=$moduleName *";
 152                         $module = new $this->mModules[$moduleName] ($this, $moduleName);
 153                         $msg2 = $module->makeHelpMsg();
 154                         if ($msg2 !== false)
 155                                 $msg .= $msg2;
 156                         $msg .= "\n";
 157                 }
 158
 159                 $msg .= "\n$astriks Formats  $astriks\n\n";
 160                 foreach ($this->mFormats as $moduleName => $moduleClass) {
 161                         $msg .= "* format=$moduleName *";
 162                         $module = new $this->mFormats[$moduleName] ($this, $moduleName);
 163                         $msg2 = $module->makeHelpMsg();
 164                         if ($msg2 !== false)
 165                                 $msg .= $msg2;
 166                         $msg .= "\n";
 167                 }
 168
 169                 return $msg;
 170         }
 171
 172         private $mIsBot = null;
 173         public function isBot() {
 174                 if (!isset ($this->mIsBot)) {
 175                         global $wgUser;
 176                         $this->mIsBot = $wgUser->isAllowed('bot');
 177                 }
 178                 return $this->mIsBot;
 179         }
 180 }
 181
 182 /**
 183 * @desc This exception will be thrown when dieUsage is called to stop module execution.
 184 */
 185 class UsageException extends Exception {
 186
 187         private $codestr;
 188
 189         public function __construct($message, $codestr) {
 190                 parent :: __construct($message);
 191                 $this->codestr = $codestr;
 192         }
 193         public function __toString() {
 194                 return "{$this->codestr}: {$this->message}";
 195         }
 196 }
 197 ?>