e482be45f1cbf5fd2fc707ea48e9a6f731b9ecb3
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', 0);
29 define('GN_ENUM_ISMULTI', 1);
30 define('GN_ENUM_CHOICES', 2);
32 abstract class ApiBase
{
39 public function __construct($mainModule) {
40 $this->mMainModule
= $mainModule;
44 * Executes this module
46 abstract function Execute();
51 public function GetMain() {
52 return $this->mMainModule
;
56 * If this module's $this is the same as $this->mMainModule, its the root, otherwise no
58 public function IsMain() {
59 return $this === $this->mMainModule
;
65 public function GetResult() {
66 // Main module has GetResult() method overriden
67 // Safety - avoid infinite loop:
69 $this->DieDebug(__METHOD__
.' base method was called on main module. ');
70 return $this->GetMain()->GetResult();
74 * Returns an array of allowed parameters (keys) => default value for that parameter
76 protected function GetAllowedParams() {
81 * Returns the description string for this module
83 protected function GetDescription() {
88 * Returns usage examples for this module. Return null if no examples are available.
90 protected function GetExamples() {
95 * Returns the description string for the given parameter.
97 protected function GetParamDescription($paramName) {
102 * Generates help message for this module, or false if there is no description
104 public function MakeHelpMsg() {
106 $msg = $this->GetDescription();
108 if ($msg !== false) {
112 $params = $this->GetAllowedParams();
113 if ($params !== false) {
114 $msg .= "Supported Parameters:\n";
115 foreach (array_keys($params) as $paramName) {
116 $msg .= sprintf(" %-14s - %s\n", $paramName, $this->GetParamDescription($paramName));
121 $examples = $this->GetExamples();
122 if ($examples !== false) {
123 $msg .= "Examples:\n ";
124 $msg .= implode("\n ", $examples) . "\n";
132 * Using GetAllowedParams(), makes an array of the values provided by the user,
133 * with key being the name of the variable, and value - validated value from user or default.
134 * This method can be used to generate local variables using extract().
136 public function ExtractRequestParams() {
139 $params = $this->GetAllowedParams();
142 foreach ($params as $param => $dflt) {
143 switch (gettype($dflt)) {
146 $result = $wgRequest->getVal($param, $dflt);
149 $result = $wgRequest->getInt($param, $dflt);
152 // Having a default value of 'true' is pointless
153 $result = $wgRequest->getCheck($param);
156 if (count($dflt) != 3)
157 $this->DieDebug("In '$param', the default enum must have 3 parts - default, allowmultiple, and array of values " . gettype($dflt));
158 $values = $wgRequest->getVal($param, $dflt[GN_ENUM_DFLT
]);
159 $result = $this->ParseMultiValue($param, $values, $dflt[GN_ENUM_ISMULTI
], $dflt[GN_ENUM_CHOICES
]);
162 $this->DieDebug("In '$param', unprocessed type " . gettype($dflt));
164 $results[$param] = $result;
171 * Return an array of values that were given in a "a|b|c" notation, after it validates them against the list allowed values.
173 protected function ParseMultiValue($valueName, $values, $allowMultiple, $allowedValues) {
174 $valuesList = explode('|', $values);
175 if (!$allowMultiple && count($valuesList) != 1)
176 $this->DieUsage("Only one value is allowed: '" . implode("', '", $allowedValues) . "' for parameter '$valueName'", "multival_$valueName");
177 $unknownValues = array_diff($valuesList, $allowedValues);
178 if ($unknownValues) {
179 $this->DieUsage("Unrecognised value" . (count($unknownValues) > 1 ?
"s '" : " '") . implode("', '", $unknownValues) . "' for parameter '$valueName'", "unknown_$valueName");
182 return $allowMultiple ?
$valuesList : $valuesList[0];
186 * Call main module's error handler
188 public function DieUsage($description, $errorCode, $httpRespCode = 0) {
189 $this->GetMain()->MainDieUsage($description, $errorCode, $httpRespCode);
192 protected function DieDebug($message) {
193 wfDebugDieBacktrace("Internal error in '{get_class($this)}': $message");