includes/api/ApiBase.php

   1 <?php
   2
   3
   4 /*
   5  * Created on Sep 5, 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 // 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');
  32
  33 abstract class ApiBase {
  34
  35         private $mMainModule;
  36
  37         /**
  38         * Constructor
  39         */
  40         public function __construct($mainModule) {
  41                 $this->mMainModule = $mainModule;
  42         }
  43
  44         /**
  45          * Executes this module
  46          */
  47         abstract function Execute();
  48
  49         /**
  50          * Get main module
  51          */
  52         public function GetMain() {
  53                 return $this->mMainModule;
  54         }
  55
  56         /**
  57          * If this module's $this is the same as $this->mMainModule, its the root, otherwise no
  58          */
  59         public function IsMain() {
  60                 return $this === $this->mMainModule;
  61         }
  62
  63         /**
  64          * Get result object
  65          */
  66         public function GetResult() {
  67                 // Main module has GetResult() method overriden
  68                 // Safety - avoid infinite loop:
  69                 if ($this->IsMain())
  70                         $this->DieDebug(__METHOD__ .
  71                         ' base method was called on main module. ');
  72                 return $this->GetMain()->GetResult();
  73         }
  74
  75         /**
  76          * Generates help message for this module, or false if there is no description
  77          */
  78         public function MakeHelpMsg() {
  79
  80                 static $lnPrfx = "\n  ";
  81
  82                 $msg = $this->GetDescription();
  83
  84                 if ($msg !== false) {
  85
  86                         if (!is_array($msg))
  87                                 $msg = array (
  88                                         $msg
  89                                 );
  90                         $msg = $lnPrfx . implode($lnPrfx, $msg) . "\n";
  91
  92                         // Parameters
  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] : '';
  99                                         if (is_array($desc))
 100                                                 $desc = implode("\n" . str_repeat(' ', 19), $desc);
 101                                         $msg .= sprintf("  %-14s - %s\n", $paramName, $desc);
 102                                 }
 103                         }
 104
 105                         // Examples
 106                         $examples = $this->GetExamples();
 107                         if ($examples !== false) {
 108                                 if (!is_array($examples))
 109                                         $examples = array (
 110                                                 $examples
 111                                         );
 112                                 $msg .= 'Example' . (count($examples) > 1 ? 's' : '') . ":\n  ";
 113                                 $msg .= implode($lnPrfx, $examples) . "\n";
 114                         }
 115                 }
 116
 117                 return $msg;
 118         }
 119
 120         /**
 121          * Returns the description string for this module
 122          */
 123         protected function GetDescription() {
 124                 return false;
 125         }
 126
 127         /**
 128          * Returns usage examples for this module. Return null if no examples are available.
 129          */
 130         protected function GetExamples() {
 131                 return false;
 132         }
 133
 134         /**
 135          * Returns an array of allowed parameters (keys) => default value for that parameter
 136          */
 137         protected function GetAllowedParams() {
 138                 return false;
 139         }
 140
 141         /**
 142          * Returns the description string for the given parameter.
 143          */
 144         protected function GetParamDescription() {
 145                 return false;
 146         }
 147
 148         /**
 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().
 152         */
 153         public function ExtractRequestParams() {
 154                 global $wgRequest;
 155
 156                 $params = $this->GetAllowedParams();
 157                 $results = array ();
 158
 159                 foreach ($params as $param => $dflt) {
 160                         switch (gettype($dflt)) {
 161                                 case 'NULL' :
 162                                 case 'string' :
 163                                         $result = $wgRequest->getVal($param, $dflt);
 164                                         break;
 165                                 case 'integer' :
 166                                         $result = $wgRequest->getInt($param, $dflt);
 167                                         break;
 168                                 case 'boolean' :
 169                                         // Having a default value of 'true' is pointless
 170                                         $result = $wgRequest->getCheck($param);
 171                                         break;
 172                                 case 'array' :
 173                                         $enumParams = $dflt;
 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;
 178
 179                                         $value = $wgRequest->getVal($param, $dflt);
 180
 181                                         // Allow null when default is not set
 182                                         if (isset ($dflt) || isset ($value)) {
 183                                                 $result = $this->ParseMultiValue($param, $value, $multi, $choices);
 184
 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);
 189                                                         else
 190                                                                 $result = intval($result);
 191                                                 }
 192                                         } else {
 193                                                 $result = null;
 194                                         }
 195                                         break;
 196                                 default :
 197                                         $this->DieDebug("In '$param', unprocessed type " . gettype($dflt));
 198                         }
 199                         $results[$param] = $result;
 200                 }
 201
 202                 return $results;
 203         }
 204
 205         /**
 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.
 208         *
 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)
 214         */
 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");
 220                 }
 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");
 225                         }
 226                 }
 227
 228                 return $allowMultiple ? $valuesList : $valuesList[0];
 229         }
 230
 231         /**
 232          * Call main module's error handler
 233          */
 234         public function DieUsage($description, $errorCode, $httpRespCode = 0) {
 235                 $this->GetMain()->MainDieUsage($description, $errorCode, $httpRespCode);
 236         }
 237
 238         protected function DieDebug($message) {
 239                 wfDebugDieBacktrace("Internal error in '{get_class($this)}': $message");
 240         }
 241 }
 242 ?>