+<?php\r
+\r
+\r
+/*\r
+ * Created on Sep 5, 2006\r
+ *\r
+ * API for MediaWiki 1.8+\r
+ *\r
+ * Copyright (C) 2006 Yuri Astrakhan <FirstnameLastname@gmail.com>\r
+ *\r
+ * This program is free software; you can redistribute it and/or modify\r
+ * it under the terms of the GNU General Public License as published by\r
+ * the Free Software Foundation; either version 2 of the License, or\r
+ * (at your option) any later version.\r
+ *\r
+ * This program is distributed in the hope that it will be useful,\r
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of\r
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the\r
+ * GNU General Public License for more details.\r
+ *\r
+ * You should have received a copy of the GNU General Public License along\r
+ * with this program; if not, write to the Free Software Foundation, Inc.,\r
+ * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.\r
+ * http://www.gnu.org/copyleft/gpl.html\r
+ */\r
+\r
+// Multi-valued enums, limit the values user can supply for the parameter\r
+define('GN_ENUM_DFLT', 0);\r
+define('GN_ENUM_ISMULTI', 1);\r
+define('GN_ENUM_CHOICES', 2);\r
+\r
+abstract class ApiBase {\r
+\r
+ private $mMainModule;\r
+\r
+ /**\r
+ * Constructor\r
+ */\r
+ public function __construct($mainModule) {\r
+ $this->mMainModule = $mainModule;\r
+ }\r
+\r
+ /**\r
+ * Executes this module\r
+ */\r
+ abstract function Execute();\r
+\r
+ /**\r
+ * Get main module\r
+ */\r
+ public function GetMain() {\r
+ return $this->mMainModule;\r
+ }\r
+\r
+ /**\r
+ * If this module's $this is the same as $this->mMainModule, its the root, otherwise no\r
+ */\r
+ public function IsMain() {\r
+ return $this === $this->mMainModule;\r
+ }\r
+\r
+ /**\r
+ * Get result object\r
+ */\r
+ public function GetResult() {\r
+ // Main module has GetResult() method overriden\r
+ // Safety - avoid infinite loop:\r
+ if ($this->IsMain())\r
+ $this->DieDebug(__METHOD__.' base method was called on main module. ');\r
+ return $this->GetMain()->GetResult();\r
+ }\r
+\r
+ /**\r
+ * Returns an array of allowed parameters (keys) => default value for that parameter\r
+ */\r
+ protected function GetAllowedParams() {\r
+ return false;\r
+ }\r
+\r
+ /**\r
+ * Returns the description string for this module\r
+ */\r
+ protected function GetDescription() {\r
+ return false;\r
+ }\r
+\r
+ /**\r
+ * Returns usage examples for this module. Return null if no examples are available.\r
+ */\r
+ protected function GetExamples() {\r
+ return false;\r
+ }\r
+\r
+ /**\r
+ * Returns the description string for the given parameter.\r
+ */\r
+ protected function GetParamDescription($paramName) {\r
+ return '';\r
+ }\r
+\r
+ /**\r
+ * Generates help message for this module, or false if there is no description\r
+ */\r
+ public function MakeHelpMsg() {\r
+\r
+ $msg = $this->GetDescription();\r
+\r
+ if ($msg !== false) {\r
+ $msg .= "\n";\r
+\r
+ // Parameters\r
+ $params = $this->GetAllowedParams();\r
+ if ($params !== false) {\r
+ $msg .= "Supported Parameters:\n";\r
+ foreach (array_keys($params) as $paramName) {\r
+ $msg .= sprintf(" %-14s - %s\n", $paramName, $this->GetParamDescription($paramName));\r
+ }\r
+ }\r
+\r
+ // Examples\r
+ $examples = $this->GetExamples();\r
+ if ($examples !== false) {\r
+ $msg .= "Examples:\n ";\r
+ $msg .= implode("\n ", $examples) . "\n";\r
+ }\r
+ }\r
+\r
+ return $msg;\r
+ }\r
+\r
+ /**\r
+ * Using GetAllowedParams(), makes an array of the values provided by the user,\r
+ * with key being the name of the variable, and value - validated value from user or default.\r
+ * This method can be used to generate local variables using extract().\r
+ */\r
+ public function ExtractRequestParams() {\r
+ global $wgRequest;\r
+\r
+ $params = $this->GetAllowedParams();\r
+ $results = array ();\r
+\r
+ foreach ($params as $param => $dflt) {\r
+ switch (gettype($dflt)) {\r
+ case 'NULL' :\r
+ case 'string' :\r
+ $result = $wgRequest->getVal($param, $dflt);\r
+ break;\r
+ case 'integer' :\r
+ $result = $wgRequest->getInt($param, $dflt);\r
+ break;\r
+ case 'boolean' :\r
+ // Having a default value of 'true' is pointless\r
+ $result = $wgRequest->getCheck($param);\r
+ break;\r
+ case 'array' :\r
+ if (count($dflt) != 3)\r
+ $this->DieDebug("In '$param', the default enum must have 3 parts - default, allowmultiple, and array of values " . gettype($dflt));\r
+ $values = $wgRequest->getVal($param, $dflt[GN_ENUM_DFLT]);\r
+ $result = $this->ParseMultiValue($param, $values, $dflt[GN_ENUM_ISMULTI], $dflt[GN_ENUM_CHOICES]);\r
+ break;\r
+ default :\r
+ $this->DieDebug("In '$param', unprocessed type " . gettype($dflt));\r
+ }\r
+ $results[$param] = $result;\r
+ }\r
+\r
+ return $results;\r
+ }\r
+\r
+ /**\r
+ * Return an array of values that were given in a "a|b|c" notation, after it validates them against the list allowed values.\r
+ */\r
+ protected function ParseMultiValue($valueName, $values, $allowMultiple, $allowedValues) {\r
+ $valuesList = explode('|', $values);\r
+ if (!$allowMultiple && count($valuesList) != 1)\r
+ $this->DieUsage("Only one value is allowed: '" . implode("', '", $allowedValues) . "' for parameter '$valueName'", "multival_$valueName");\r
+ $unknownValues = array_diff($valuesList, $allowedValues);\r
+ if ($unknownValues) {\r
+ $this->DieUsage("Unrecognised value" . (count($unknownValues) > 1 ? "s '" : " '") . implode("', '", $unknownValues) . "' for parameter '$valueName'", "unknown_$valueName");\r
+ }\r
+\r
+ return $allowMultiple ? $valuesList : $valuesList[0];\r
+ }\r
+\r
+ /**\r
+ * Call main module's error handler \r
+ */\r
+ public function DieUsage($description, $errorCode, $httpRespCode = 0) {\r
+ $this->GetMain()->MainDieUsage($description, $errorCode, $httpRespCode);\r
+ }\r
+\r
+ protected function DieDebug($message) {\r
+ wfDebugDieBacktrace("Internal error in '{get_class($this)}': $message");\r
+ }\r
+}\r
+?>\r