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', 0);
  29 define('GN_ENUM_ISMULTI', 1);
  30 define('GN_ENUM_CHOICES', 2);
  31
  32 abstract class ApiBase {
  33
  34         private $mMainModule;
  35
  36         /**
  37         * Constructor
  38         */
  39         public function __construct($mainModule) {
  40                 $this->mMainModule = $mainModule;
  41         }
  42
  43         /**
  44          * Executes this module
  45          */
  46         abstract function Execute();
  47
  48         /**
  49          * Get main module
  50          */
  51         public function GetMain() {
  52                 return $this->mMainModule;
  53         }
  54
  55         /**
  56          * If this module's $this is the same as $this->mMainModule, its the root, otherwise no
  57          */
  58         public function IsMain() {
  59                 return $this === $this->mMainModule;
  60         }
  61
  62         /**
  63          * Get result object
  64          */
  65         public function GetResult() {
  66                 // Main module has GetResult() method overriden
  67                 // Safety - avoid infinite loop:
  68                 if ($this->IsMain())
  69                         $this->DieDebug(__METHOD__.' base method was called on main module. ');
  70                 return $this->GetMain()->GetResult();
  71         }
  72
  73         /**
  74          * Returns an array of allowed parameters (keys) => default value for that parameter
  75          */
  76         protected function GetAllowedParams() {
  77                 return false;
  78         }
  79
  80         /**
  81          * Returns the description string for this module
  82          */
  83         protected function GetDescription() {
  84                 return false;
  85         }
  86
  87         /**
  88          * Returns usage examples for this module. Return null if no examples are available.
  89          */
  90         protected function GetExamples() {
  91                 return false;
  92         }
  93
  94         /**
  95          * Returns the description string for the given parameter.
  96          */
  97         protected function GetParamDescription($paramName) {
  98                 return '';
  99         }
 100
 101         /**
 102          * Generates help message for this module, or false if there is no description
 103          */
 104         public function MakeHelpMsg() {
 105
 106                 $msg = $this->GetDescription();
 107
 108                 if ($msg !== false) {
 109                         $msg .= "\n";
 110
 111                         // Parameters
 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));
 117                                 }
 118                         }
 119
 120                         // Examples
 121                         $examples = $this->GetExamples();
 122                         if ($examples !== false) {
 123                                 $msg .= "Examples:\n  ";
 124                                 $msg .= implode("\n  ", $examples) . "\n";
 125                         }
 126                 }
 127
 128                 return $msg;
 129         }
 130
 131         /**
 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().
 135         */
 136         public function ExtractRequestParams() {
 137                 global $wgRequest;
 138
 139                 $params = $this->GetAllowedParams();
 140                 $results = array ();
 141
 142                 foreach ($params as $param => $dflt) {
 143                         switch (gettype($dflt)) {
 144                                 case 'NULL' :
 145                                 case 'string' :
 146                                         $result = $wgRequest->getVal($param, $dflt);
 147                                         break;
 148                                 case 'integer' :
 149                                         $result = $wgRequest->getInt($param, $dflt);
 150                                         break;
 151                                 case 'boolean' :
 152                                         // Having a default value of 'true' is pointless
 153                                         $result = $wgRequest->getCheck($param);
 154                                         break;
 155                                 case 'array' :
 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]);
 160                                         break;
 161                                 default :
 162                                         $this->DieDebug("In '$param', unprocessed type " . gettype($dflt));
 163                         }
 164                         $results[$param] = $result;
 165                 }
 166
 167                 return $results;
 168         }
 169
 170         /**
 171         * Return an array of values that were given in a "a|b|c" notation, after it validates them against the list allowed values.
 172         */
 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");
 180                 }
 181
 182                 return $allowMultiple ? $valuesList : $valuesList[0];
 183         }
 184
 185         /**
 186          * Call main module's error handler
 187          */
 188         public function DieUsage($description, $errorCode, $httpRespCode = 0) {
 189                 $this->GetMain()->MainDieUsage($description, $errorCode, $httpRespCode);
 190         }
 191
 192         protected function DieDebug($message) {
 193                 wfDebugDieBacktrace("Internal error in '{get_class($this)}': $message");
 194         }
 195 }
 196 ?>