[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   *
   4   *
   5   * Created on Dec 01, 2007
   6   *
   7   * Copyright © 2008 Roan Kattouw "<Firstname>.<Lastname>@gmail.com"
   8   *
   9   * This program is free software; you can redistribute it and/or modify
  10   * it under the terms of the GNU General Public License as published by
  11   * the Free Software Foundation; either version 2 of the License, or
  12   * (at your option) any later version.
  13   *
  14   * This program is distributed in the hope that it will be useful,
  15   * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  17   * GNU General Public License for more details.
  18   *
  19   * You should have received a copy of the GNU General Public License along
  20   * with this program; if not, write to the Free Software Foundation, Inc.,
  21   * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  22   * http://www.gnu.org/copyleft/gpl.html
  23   *
  24   * @file
  25   */
  26  
  27  /**
  28   * @ingroup API
  29   */
  30  class ApiParamInfo extends ApiBase {
  31  
  32      /**
  33       * @var ApiQuery
  34       */
  35      protected $queryObj;
  36  
  37  	public function __construct( ApiMain $main, $action ) {
  38          parent::__construct( $main, $action );
  39          $this->queryObj = new ApiQuery( $this->getMain(), 'query' );
  40      }
  41  
  42  	public function execute() {
  43          // Get parameters
  44          $params = $this->extractRequestParams();
  45          $resultObj = $this->getResult();
  46  
  47          $res = array();
  48  
  49          $this->addModulesInfo( $params, 'modules', $res, $resultObj );
  50  
  51          $this->addModulesInfo( $params, 'querymodules', $res, $resultObj );
  52  
  53          if ( $params['mainmodule'] ) {
  54              $res['mainmodule'] = $this->getClassInfo( $this->getMain() );
  55          }
  56  
  57          if ( $params['pagesetmodule'] ) {
  58              $pageSet = new ApiPageSet( $this->queryObj );
  59              $res['pagesetmodule'] = $this->getClassInfo( $pageSet );
  60          }
  61  
  62          $this->addModulesInfo( $params, 'formatmodules', $res, $resultObj );
  63  
  64          $resultObj->addValue( null, $this->getModuleName(), $res );
  65      }
  66  
  67      /**
  68       * If the type is requested in parameters, adds a section to res with module info.
  69       * @param array $params User parameters array
  70       * @param string $type Parameter name
  71       * @param array $res Store results in this array
  72       * @param ApiResult $resultObj Results object to set indexed tag.
  73       */
  74  	private function addModulesInfo( $params, $type, &$res, $resultObj ) {
  75          if ( !is_array( $params[$type] ) ) {
  76              return;
  77          }
  78          $isQuery = ( $type === 'querymodules' );
  79          if ( $isQuery ) {
  80              $mgr = $this->queryObj->getModuleManager();
  81          } else {
  82              $mgr = $this->getMain()->getModuleManager();
  83          }
  84          $res[$type] = array();
  85          foreach ( $params[$type] as $mod ) {
  86              if ( !$mgr->isDefined( $mod ) ) {
  87                  $res[$type][] = array( 'name' => $mod, 'missing' => '' );
  88                  continue;
  89              }
  90              $obj = $mgr->getModule( $mod );
  91              $item = $this->getClassInfo( $obj );
  92              $item['name'] = $mod;
  93              if ( $isQuery ) {
  94                  $item['querytype'] = $mgr->getModuleGroup( $mod );
  95              }
  96              $res[$type][] = $item;
  97          }
  98          $resultObj->setIndexedTagName( $res[$type], 'module' );
  99      }
 100  
 101      /**
 102       * @param ApiBase $obj
 103       * @return ApiResult
 104       */
 105  	private function getClassInfo( $obj ) {
 106          $result = $this->getResult();
 107          $retval['classname'] = get_class( $obj );
 108          $retval['description'] = implode( "\n", (array)$obj->getFinalDescription() );
 109          $retval['examples'] = '';
 110  
 111          // version is deprecated since 1.21, but needs to be returned for v1
 112          $retval['version'] = '';
 113          $retval['prefix'] = $obj->getModulePrefix();
 114  
 115          if ( $obj->isReadMode() ) {
 116              $retval['readrights'] = '';
 117          }
 118          if ( $obj->isWriteMode() ) {
 119              $retval['writerights'] = '';
 120          }
 121          if ( $obj->mustBePosted() ) {
 122              $retval['mustbeposted'] = '';
 123          }
 124          if ( $obj instanceof ApiQueryGeneratorBase ) {
 125              $retval['generator'] = '';
 126          }
 127  
 128          $allowedParams = $obj->getFinalParams( ApiBase::GET_VALUES_FOR_HELP );
 129          if ( !is_array( $allowedParams ) ) {
 130              return $retval;
 131          }
 132  
 133          $retval['helpurls'] = (array)$obj->getHelpUrls();
 134          if ( isset( $retval['helpurls'][0] ) && $retval['helpurls'][0] === false ) {
 135              $retval['helpurls'] = array();
 136          }
 137          $result->setIndexedTagName( $retval['helpurls'], 'helpurl' );
 138  
 139          $examples = $obj->getExamples();
 140          $retval['allexamples'] = array();
 141          if ( $examples !== false ) {
 142              if ( is_string( $examples ) ) {
 143                  $examples = array( $examples );
 144              }
 145              foreach ( $examples as $k => $v ) {
 146                  if ( strlen( $retval['examples'] ) ) {
 147                      $retval['examples'] .= ' ';
 148                  }
 149                  $item = array();
 150                  if ( is_numeric( $k ) ) {
 151                      $retval['examples'] .= $v;
 152                      ApiResult::setContent( $item, $v );
 153                  } else {
 154                      if ( !is_array( $v ) ) {
 155                          $item['description'] = $v;
 156                      } else {
 157                          $item['description'] = implode( $v, "\n" );
 158                      }
 159                      $retval['examples'] .= $item['description'] . ' ' . $k;
 160                      ApiResult::setContent( $item, $k );
 161                  }
 162                  $retval['allexamples'][] = $item;
 163              }
 164          }
 165          $result->setIndexedTagName( $retval['allexamples'], 'example' );
 166  
 167          $retval['parameters'] = array();
 168          $paramDesc = $obj->getFinalParamDescription();
 169          foreach ( $allowedParams as $n => $p ) {
 170              $a = array( 'name' => $n );
 171              if ( isset( $paramDesc[$n] ) ) {
 172                  $a['description'] = implode( "\n", (array)$paramDesc[$n] );
 173              }
 174  
 175              //handle shorthand
 176              if ( !is_array( $p ) ) {
 177                  $p = array(
 178                      ApiBase::PARAM_DFLT => $p,
 179                  );
 180              }
 181  
 182              //handle missing type
 183              if ( !isset( $p[ApiBase::PARAM_TYPE] ) ) {
 184                  $dflt = isset( $p[ApiBase::PARAM_DFLT] ) ? $p[ApiBase::PARAM_DFLT] : null;
 185                  if ( is_bool( $dflt ) ) {
 186                      $p[ApiBase::PARAM_TYPE] = 'boolean';
 187                  } elseif ( is_string( $dflt ) || is_null( $dflt ) ) {
 188                      $p[ApiBase::PARAM_TYPE] = 'string';
 189                  } elseif ( is_int( $dflt ) ) {
 190                      $p[ApiBase::PARAM_TYPE] = 'integer';
 191                  }
 192              }
 193  
 194              if ( isset( $p[ApiBase::PARAM_DEPRECATED] ) && $p[ApiBase::PARAM_DEPRECATED] ) {
 195                  $a['deprecated'] = '';
 196              }
 197              if ( isset( $p[ApiBase::PARAM_REQUIRED] ) && $p[ApiBase::PARAM_REQUIRED] ) {
 198                  $a['required'] = '';
 199              }
 200  
 201              if ( $n === 'token' && $obj->needsToken() ) {
 202                  $a['tokentype'] = $obj->needsToken();
 203              }
 204  
 205              if ( isset( $p[ApiBase::PARAM_DFLT] ) ) {
 206                  $type = $p[ApiBase::PARAM_TYPE];
 207                  if ( $type === 'boolean' ) {
 208                      $a['default'] = ( $p[ApiBase::PARAM_DFLT] ? 'true' : 'false' );
 209                  } elseif ( $type === 'string' ) {
 210                      $a['default'] = strval( $p[ApiBase::PARAM_DFLT] );
 211                  } elseif ( $type === 'integer' ) {
 212                      $a['default'] = intval( $p[ApiBase::PARAM_DFLT] );
 213                  } else {
 214                      $a['default'] = $p[ApiBase::PARAM_DFLT];
 215                  }
 216              }
 217              if ( isset( $p[ApiBase::PARAM_ISMULTI] ) && $p[ApiBase::PARAM_ISMULTI] ) {
 218                  $a['multi'] = '';
 219                  $a['limit'] = $this->getMain()->canApiHighLimits() ?
 220                      ApiBase::LIMIT_SML2 :
 221                      ApiBase::LIMIT_SML1;
 222                  $a['lowlimit'] = ApiBase::LIMIT_SML1;
 223                  $a['highlimit'] = ApiBase::LIMIT_SML2;
 224              }
 225  
 226              if ( isset( $p[ApiBase::PARAM_ALLOW_DUPLICATES] ) && $p[ApiBase::PARAM_ALLOW_DUPLICATES] ) {
 227                  $a['allowsduplicates'] = '';
 228              }
 229  
 230              if ( isset( $p[ApiBase::PARAM_TYPE] ) ) {
 231                  if ( $p[ApiBase::PARAM_TYPE] === 'submodule' ) {
 232                      $a['type'] = $obj->getModuleManager()->getNames( $n );
 233                      sort( $a['type'] );
 234                      $a['submodules'] = '';
 235                  } else {
 236                      $a['type'] = $p[ApiBase::PARAM_TYPE];
 237                  }
 238                  if ( is_array( $a['type'] ) ) {
 239                      // To prevent sparse arrays from being serialized to JSON as objects
 240                      $a['type'] = array_values( $a['type'] );
 241                      $result->setIndexedTagName( $a['type'], 't' );
 242                  }
 243              }
 244              if ( isset( $p[ApiBase::PARAM_MAX] ) ) {
 245                  $a['max'] = $p[ApiBase::PARAM_MAX];
 246              }
 247              if ( isset( $p[ApiBase::PARAM_MAX2] ) ) {
 248                  $a['highmax'] = $p[ApiBase::PARAM_MAX2];
 249              }
 250              if ( isset( $p[ApiBase::PARAM_MIN] ) ) {
 251                  $a['min'] = $p[ApiBase::PARAM_MIN];
 252              }
 253              $retval['parameters'][] = $a;
 254          }
 255          $result->setIndexedTagName( $retval['parameters'], 'param' );
 256  
 257          return $retval;
 258      }
 259  
 260  	public function isReadMode() {
 261          return false;
 262      }
 263  
 264  	public function getAllowedParams() {
 265          $modules = $this->getMain()->getModuleManager()->getNames( 'action' );
 266          sort( $modules );
 267          $querymodules = $this->queryObj->getModuleManager()->getNames();
 268          sort( $querymodules );
 269          $formatmodules = $this->getMain()->getModuleManager()->getNames( 'format' );
 270          sort( $formatmodules );
 271  
 272          return array(
 273              'modules' => array(
 274                  ApiBase::PARAM_ISMULTI => true,
 275                  ApiBase::PARAM_TYPE => $modules,
 276              ),
 277              'querymodules' => array(
 278                  ApiBase::PARAM_ISMULTI => true,
 279                  ApiBase::PARAM_TYPE => $querymodules,
 280              ),
 281              'mainmodule' => false,
 282              'pagesetmodule' => false,
 283              'formatmodules' => array(
 284                  ApiBase::PARAM_ISMULTI => true,
 285                  ApiBase::PARAM_TYPE => $formatmodules,
 286              )
 287          );
 288      }
 289  
 290  	public function getParamDescription() {
 291          return array(
 292              'modules' => 'List of module names (value of the action= parameter)',
 293              'querymodules' => 'List of query module names (value of prop=, meta= or list= parameter)',
 294              'mainmodule' => 'Get information about the main (top-level) module as well',
 295              'pagesetmodule' => 'Get information about the pageset module ' .
 296                  '(providing titles= and friends) as well',
 297              'formatmodules' => 'List of format module names (value of format= parameter)',
 298          );
 299      }
 300  
 301  	public function getDescription() {
 302          return 'Obtain information about certain API parameters and errors.';
 303      }
 304  
 305  	public function getExamples() {
 306          return array(
 307              'api.php?action=paraminfo&modules=parse&querymodules=allpages|siteinfo'
 308          );
 309      }
 310  
 311  	public function getHelpUrls() {
 312          return 'https://www.mediawiki.org/wiki/API:Parameter_information';
 313      }
 314  }