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