5 * Created on Sep 5, 2006
7 * API for MediaWiki 1.8+
9 * Copyright (C) 2006 Yuri Astrakhan <FirstnameLastname@gmail.com>
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.
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.
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
27 // Multi-valued enums, limit the values user can supply for the parameter
28 define('GN_ENUM_DFLT', 'dflt');
29 define('GN_ENUM_ISMULTI', 'multi');
30 define('GN_ENUM_CHOICES', 'choices');
31 define('GN_ENUM_TYPE', 'type');
33 abstract class ApiBase
{
40 public function __construct($mainModule) {
41 $this->mMainModule
= $mainModule;
45 * Executes this module
47 abstract function Execute();
52 public function GetMain() {
53 return $this->mMainModule
;
57 * If this module's $this is the same as $this->mMainModule, its the root, otherwise no
59 public function IsMain() {
60 return $this === $this->mMainModule
;
66 public function GetResult() {
67 // Main module has GetResult() method overriden
68 // Safety - avoid infinite loop:
70 $this->DieDebug(__METHOD__
.
71 ' base method was called on main module. ');
72 return $this->GetMain()->GetResult();
76 * Generates help message for this module, or false if there is no description
78 public function MakeHelpMsg() {
80 static $lnPrfx = "\n ";
82 $msg = $this->GetDescription();
90 $msg = $lnPrfx . implode($lnPrfx, $msg) . "\n";
93 $params = $this->GetAllowedParams();
94 if ($params !== false) {
95 $paramsDescription = $this->GetParamDescription();
96 $msg .= "Parameters:\n";
97 foreach (array_keys($params) as $paramName) {
98 $desc = isset ($paramsDescription[$paramName]) ?
$paramsDescription[$paramName] : '';
100 $desc = implode("\n" . str_repeat(' ', 19), $desc);
101 $msg .= sprintf(" %-14s - %s\n", $paramName, $desc);
106 $examples = $this->GetExamples();
107 if ($examples !== false) {
108 if (!is_array($examples))
112 $msg .= 'Example' . (count($examples) > 1 ?
's' : '') . ":\n ";
113 $msg .= implode($lnPrfx, $examples) . "\n";
121 * Returns the description string for this module
123 protected function GetDescription() {
128 * Returns usage examples for this module. Return null if no examples are available.
130 protected function GetExamples() {
135 * Returns an array of allowed parameters (keys) => default value for that parameter
137 protected function GetAllowedParams() {
142 * Returns the description string for the given parameter.
144 protected function GetParamDescription() {
149 * Using GetAllowedParams(), makes an array of the values provided by the user,
150 * with key being the name of the variable, and value - validated value from user or default.
151 * This method can be used to generate local variables using extract().
153 public function ExtractRequestParams() {
156 $params = $this->GetAllowedParams();
159 foreach ($params as $param => $dflt) {
160 switch (gettype($dflt)) {
163 $result = $wgRequest->getVal($param, $dflt);
166 $result = $wgRequest->getInt($param, $dflt);
169 // Having a default value of 'true' is pointless
170 $result = $wgRequest->getCheck($param);
174 $dflt = isset ($enumParams[GN_ENUM_DFLT
]) ?
$enumParams[GN_ENUM_DFLT
] : null;
175 $multi = isset ($enumParams[GN_ENUM_ISMULTI
]) ?
$enumParams[GN_ENUM_ISMULTI
] : false;
176 $choices = isset ($enumParams[GN_ENUM_CHOICES
]) ?
$enumParams[GN_ENUM_CHOICES
] : null;
177 $type = isset ($enumParams[GN_ENUM_TYPE
]) ?
$enumParams[GN_ENUM_TYPE
] : null;
179 $value = $wgRequest->getVal($param, $dflt);
181 // Allow null when default is not set
182 if (isset ($dflt) ||
isset ($value)) {
183 $result = $this->ParseMultiValue($param, $value, $multi, $choices);
185 // When choices are not given, and the default is an integer, make sure all values are integers
186 if (!isset ($choices) && isset ($dflt) && $type === 'integer') {
187 if (is_array($result))
188 $result = array_map('intval', $result);
190 $result = intval($result);
197 $this->DieDebug("In '$param', unprocessed type " . gettype($dflt));
199 $results[$param] = $result;
206 * Return an array of values that were given in a "a|b|c" notation,
207 * after it optionally validates them against the list allowed values.
209 * @param valueName - The name of the parameter (for error reporting)
210 * @param value - The value being parsed
211 * @param allowMultiple - Can $value contain more than one value separated by '|'?
212 * @param allowedValues - An array of values to check against. If null, all values are accepted.
213 * @return (allowMultiple ? an_array_of_values : a_single_value)
215 protected function ParseMultiValue($valueName, $value, $allowMultiple, $allowedValues) {
216 $valuesList = explode('|', $value);
217 if (!$allowMultiple && count($valuesList) != 1) {
218 $possibleValues = is_array($allowedValues) ?
"of '" . implode("', '", $allowedValues) . "'" : '';
219 $this->DieUsage("Only one $possibleValues is allowed for parameter '$valueName'", "multival_$valueName");
221 if (is_array($allowedValues)) {
222 $unknownValues = array_diff($valuesList, $allowedValues);
223 if ($unknownValues) {
224 $this->DieUsage("Unrecognised value" . (count($unknownValues) > 1 ?
"s '" : " '") . implode("', '", $unknownValues) . "' for parameter '$valueName'", "unknown_$valueName");
228 return $allowMultiple ?
$valuesList : $valuesList[0];
232 * Call main module's error handler
234 public function DieUsage($description, $errorCode, $httpRespCode = 0) {
235 $this->GetMain()->MainDieUsage($description, $errorCode, $httpRespCode);
238 protected function DieDebug($message) {
239 wfDebugDieBacktrace("Internal error in '{get_class($this)}': $message");