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                                         $msg .= sprintf("  %-14s - %s\n", $paramName, $desc);
 100                                 }
 101                         }
 102
 103                         // Examples
 104                         $examples = $this->GetExamples();
 105                         if ($examples !== false) {
 106                                 if (!is_array($examples))
 107                                         $examples = array (
 108                                                 $examples
 109                                         );
 110                                 $msg .= 'Example' . (count($examples) > 1 ? 's' : '') . ":\n  ";
 111                                 $msg .= implode($lnPrfx, $examples) . "\n";
 112                         }
 113                 }
 114
 115                 return $msg;
 116         }
 117
 118         /**
 119          * Returns the description string for this module
 120          */
 121         protected function GetDescription() {
 122                 return false;
 123         }
 124
 125         /**
 126          * Returns usage examples for this module. Return null if no examples are available.
 127          */
 128         protected function GetExamples() {
 129                 return false;
 130         }
 131
 132         /**
 133          * Returns an array of allowed parameters (keys) => default value for that parameter
 134          */
 135         protected function GetAllowedParams() {
 136                 return false;
 137         }
 138
 139         /**
 140          * Returns the description string for the given parameter.
 141          */
 142         protected function GetParamDescription() {
 143                 return false;
 144         }
 145
 146         /**
 147         * Using GetAllowedParams(), makes an array of the values provided by the user,
 148         * with key being the name of the variable, and value - validated value from user or default.
 149         * This method can be used to generate local variables using extract().
 150         */
 151         public function ExtractRequestParams() {
 152                 global $wgRequest;
 153
 154                 $params = $this->GetAllowedParams();
 155                 $results = array ();
 156
 157                 foreach ($params as $param => $dflt) {
 158                         switch (gettype($dflt)) {
 159                                 case 'NULL' :
 160                                 case 'string' :
 161                                         $result = $wgRequest->getVal($param, $dflt);
 162                                         break;
 163                                 case 'integer' :
 164                                         $result = $wgRequest->getInt($param, $dflt);
 165                                         break;
 166                                 case 'boolean' :
 167                                         // Having a default value of 'true' is pointless
 168                                         $result = $wgRequest->getCheck($param);
 169                                         break;
 170                                 case 'array' :
 171                                         $enumParams = $dflt;
 172                                         $dflt = isset ($enumParams[GN_ENUM_DFLT]) ? $enumParams[GN_ENUM_DFLT] : null;
 173                                         $multi = isset ($enumParams[GN_ENUM_ISMULTI]) ? $enumParams[GN_ENUM_ISMULTI] : false;
 174                                         $choices = isset ($enumParams[GN_ENUM_CHOICES]) ? $enumParams[GN_ENUM_CHOICES] : null;
 175                                         $type = isset ($enumParams[GN_ENUM_TYPE]) ? $enumParams[GN_ENUM_TYPE] : null;
 176
 177                                         $value = $wgRequest->getVal($param, $dflt);
 178
 179                                         // Allow null when default is not set
 180                                         if (isset ($dflt) || isset ($value)) {
 181                                                 $result = $this->ParseMultiValue($param, $value, $multi, $choices);
 182
 183                                                 // When choices are not given, and the default is an integer, make sure all values are integers
 184                                                 if (!isset ($choices) && isset ($dflt) && $type === 'integer') {
 185                                                         if (is_array($result))
 186                                                                 $result = array_map('intval', $result);
 187                                                         else
 188                                                                 $result = intval($result);
 189                                                 }
 190                                         } else {
 191                                                 $result = null;
 192                                         }
 193                                         break;
 194                                 default :
 195                                         $this->DieDebug("In '$param', unprocessed type " . gettype($dflt));
 196                         }
 197                         $results[$param] = $result;
 198                 }
 199
 200                 return $results;
 201         }
 202
 203         /**
 204         * Return an array of values that were given in a "a|b|c" notation,
 205         * after it optionally validates them against the list allowed values.
 206         *
 207         * @param valueName - The name of the parameter (for error reporting)
 208         * @param value - The value being parsed
 209         * @param allowMultiple - Can $value contain more than one value separated by '|'?
 210         * @param allowedValues - An array of values to check against. If null, all values are accepted.
 211         * @return (allowMultiple ? an_array_of_values : a_single_value)
 212         */
 213         protected function ParseMultiValue($valueName, $value, $allowMultiple, $allowedValues) {
 214                 $valuesList = explode('|', $value);
 215                 if (!$allowMultiple && count($valuesList) != 1) {
 216                         $possibleValues = is_array($allowedValues) ? "of '" . implode("', '", $allowedValues) . "'" : '';
 217                         $this->DieUsage("Only one $possibleValues is allowed for parameter '$valueName'", "multival_$valueName");
 218                 }
 219                 if (is_array($allowedValues)) {
 220                         $unknownValues = array_diff($valuesList, $allowedValues);
 221                         if ($unknownValues) {
 222                                 $this->DieUsage("Unrecognised value" . (count($unknownValues) > 1 ? "s '" : " '") . implode("', '", $unknownValues) . "' for parameter '$valueName'", "unknown_$valueName");
 223                         }
 224                 }
 225
 226                 return $allowMultiple ? $valuesList : $valuesList[0];
 227         }
 228
 229         /**
 230          * Call main module's error handler
 231          */
 232         public function DieUsage($description, $errorCode, $httpRespCode = 0) {
 233                 $this->GetMain()->MainDieUsage($description, $errorCode, $httpRespCode);
 234         }
 235
 236         protected function DieDebug($message) {
 237                 wfDebugDieBacktrace("Internal error in '{get_class($this)}': $message");
 238         }
 239 }
 240 ?>