5 * Created on Dec 01, 2007
7 * Copyright © 2008 Roan Kattouw "<Firstname>.<Lastname>@gmail.com"
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.
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.
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
30 class ApiParamInfo
extends ApiBase
{
37 public function __construct( $main, $action ) {
38 parent
::__construct( $main, $action );
39 $this->queryObj
= new ApiQuery( $this->getMain(), 'query' );
42 public function execute() {
44 $params = $this->extractRequestParams();
45 $result = $this->getResult();
48 if ( is_array( $params['modules'] ) ) {
49 $modules = $this->getMain()->getModules();
50 $res['modules'] = array();
51 foreach ( $params['modules'] as $mod ) {
52 if ( !isset( $modules[$mod] ) ) {
53 $res['modules'][] = array( 'name' => $mod, 'missing' => '' );
56 $obj = new $modules[$mod]( $this->getMain(), $mod );
58 $item = $this->getClassInfo( $obj );
60 $res['modules'][] = $item;
62 $result->setIndexedTagName( $res['modules'], 'module' );
65 if ( is_array( $params['querymodules'] ) ) {
66 $queryModules = $this->queryObj
->getModules();
67 $res['querymodules'] = array();
68 foreach ( $params['querymodules'] as $qm ) {
69 if ( !isset( $queryModules[$qm] ) ) {
70 $res['querymodules'][] = array( 'name' => $qm, 'missing' => '' );
73 $obj = new $queryModules[$qm]( $this, $qm );
74 $item = $this->getClassInfo( $obj );
76 $item['querytype'] = $this->queryObj
->getModuleType( $qm );
77 $res['querymodules'][] = $item;
79 $result->setIndexedTagName( $res['querymodules'], 'module' );
82 if ( $params['mainmodule'] ) {
83 $res['mainmodule'] = $this->getClassInfo( $this->getMain() );
86 if ( $params['pagesetmodule'] ) {
87 $pageSet = new ApiPageSet( $this->queryObj
);
88 $res['pagesetmodule'] = $this->getClassInfo( $pageSet );
91 if ( is_array( $params['formatmodules'] ) ) {
92 $formats = $this->getMain()->getFormats();
93 $res['formatmodules'] = array();
94 foreach ( $params['formatmodules'] as $f ) {
95 if ( !isset( $formats[$f] ) ) {
96 $res['formatmodules'][] = array( 'name' => $f, 'missing' => '' );
99 $obj = new $formats[$f]( $this, $f );
100 $item = $this->getClassInfo( $obj );
102 $res['formatmodules'][] = $item;
104 $result->setIndexedTagName( $res['formatmodules'], 'module' );
106 $result->addValue( null, $this->getModuleName(), $res );
110 * @param $obj ApiBase
113 function getClassInfo( $obj ) {
114 $result = $this->getResult();
115 $retval['classname'] = get_class( $obj );
116 $retval['description'] = implode( "\n", (array)$obj->getFinalDescription() );
118 $retval['examples'] = '';
120 $retval['version'] = implode( "\n", (array)$obj->getVersion() );
121 $retval['prefix'] = $obj->getModulePrefix();
123 if ( $obj->isReadMode() ) {
124 $retval['readrights'] = '';
126 if ( $obj->isWriteMode() ) {
127 $retval['writerights'] = '';
129 if ( $obj->mustBePosted() ) {
130 $retval['mustbeposted'] = '';
132 if ( $obj instanceof ApiQueryGeneratorBase
) {
133 $retval['generator'] = '';
136 $allowedParams = $obj->getFinalParams();
137 if ( !is_array( $allowedParams ) ) {
141 $retval['helpurls'] = (array)$obj->getHelpUrls();
142 if ( isset( $retval['helpurls'][0] ) && $retval['helpurls'][0] === false ) {
143 $retval['helpurls'] = array();
145 $result->setIndexedTagName( $retval['helpurls'], 'helpurl' );
147 $examples = $obj->getExamples();
148 $retval['allexamples'] = array();
149 if ( $examples !== false ) {
150 if ( is_string( $examples ) ) {
151 $examples = array( $examples );
153 foreach( $examples as $k => $v ) {
154 if ( strlen( $retval['examples'] ) ) {
155 $retval['examples'] .= ' ';
158 if ( is_numeric( $k ) ) {
159 $retval['examples'] .= $v;
160 $result->setContent( $item, $v );
162 if ( !is_array( $v ) ) {
163 $item['description'] = $v;
165 $item['description'] = implode( $v, "\n" );
167 $retval['examples'] .= $item['description'] . ' ' . $k;
168 $result->setContent( $item, $k );
170 $retval['allexamples'][] = $item;
173 $result->setIndexedTagName( $retval['allexamples'], 'example' );
175 $retval['parameters'] = array();
176 $paramDesc = $obj->getFinalParamDescription();
177 foreach ( $allowedParams as $n => $p ) {
178 $a = array( 'name' => $n );
179 if ( isset( $paramDesc[$n] ) ) {
180 $a['description'] = implode( "\n", (array)$paramDesc[$n] );
184 if( !is_array( $p ) ) {
186 ApiBase
::PARAM_DFLT
=> $p,
190 //handle missing type
191 if ( !isset( $p[ApiBase
::PARAM_TYPE
] ) ) {
192 $dflt = isset( $p[ApiBase
::PARAM_DFLT
] ) ?
$p[ApiBase
::PARAM_DFLT
] : null;
193 if ( is_bool( $dflt ) ) {
194 $p[ApiBase
::PARAM_TYPE
] = 'boolean';
195 } elseif ( is_string( $dflt ) ||
is_null( $dflt ) ) {
196 $p[ApiBase
::PARAM_TYPE
] = 'string';
197 } elseif ( is_int( $dflt ) ) {
198 $p[ApiBase
::PARAM_TYPE
] = 'integer';
202 if ( isset( $p[ApiBase
::PARAM_DEPRECATED
] ) && $p[ApiBase
::PARAM_DEPRECATED
] ) {
203 $a['deprecated'] = '';
205 if ( isset( $p[ApiBase
::PARAM_REQUIRED
] ) && $p[ApiBase
::PARAM_REQUIRED
] ) {
209 if ( isset( $p[ApiBase
::PARAM_DFLT
] ) ) {
210 $type = $p[ApiBase
::PARAM_TYPE
];
211 if( $type === 'boolean' ) {
212 $a['default'] = ( $p[ApiBase
::PARAM_DFLT
] ?
'true' : 'false' );
213 } elseif( $type === 'string' ) {
214 $a['default'] = strval( $p[ApiBase
::PARAM_DFLT
] );
215 } elseif( $type === 'integer' ) {
216 $a['default'] = intval( $p[ApiBase
::PARAM_DFLT
] );
218 $a['default'] = $p[ApiBase
::PARAM_DFLT
];
221 if ( isset( $p[ApiBase
::PARAM_ISMULTI
] ) && $p[ApiBase
::PARAM_ISMULTI
] ) {
223 $a['limit'] = $this->getMain()->canApiHighLimits() ?
224 ApiBase
::LIMIT_SML2
:
226 $a['lowlimit'] = ApiBase
::LIMIT_SML1
;
227 $a['highlimit'] = ApiBase
::LIMIT_SML2
;
230 if ( isset( $p[ApiBase
::PARAM_ALLOW_DUPLICATES
] ) && $p[ApiBase
::PARAM_ALLOW_DUPLICATES
] ) {
231 $a['allowsduplicates'] = '';
234 if ( isset( $p[ApiBase
::PARAM_TYPE
] ) ) {
235 $a['type'] = $p[ApiBase
::PARAM_TYPE
];
236 if ( is_array( $a['type'] ) ) {
237 $a['type'] = array_values( $a['type'] ); // to prevent sparse arrays from being serialized to JSON as objects
238 $result->setIndexedTagName( $a['type'], 't' );
241 if ( isset( $p[ApiBase
::PARAM_MAX
] ) ) {
242 $a['max'] = $p[ApiBase
::PARAM_MAX
];
244 if ( isset( $p[ApiBase
::PARAM_MAX2
] ) ) {
245 $a['highmax'] = $p[ApiBase
::PARAM_MAX2
];
247 if ( isset( $p[ApiBase
::PARAM_MIN
] ) ) {
248 $a['min'] = $p[ApiBase
::PARAM_MIN
];
250 $retval['parameters'][] = $a;
252 $result->setIndexedTagName( $retval['parameters'], 'param' );
254 $props = $obj->getFinalResultProperties();
256 if ( $props !== false ) {
257 $retval['props'] = array();
259 foreach ( $props as $prop => $properties ) {
260 $propResult = array();
261 if ( $prop == ApiBase
::PROP_LIST
) {
262 $listResult = $properties;
265 if ( $prop != ApiBase
::PROP_ROOT
) {
266 $propResult['name'] = $prop;
268 $propResult['properties'] = array();
270 foreach ( $properties as $name => $p ) {
271 $propertyResult = array();
273 $propertyResult['name'] = $name;
275 if ( !is_array( $p ) ) {
276 $p = array( ApiBase
::PROP_TYPE
=> $p );
279 $propertyResult['type'] = $p[ApiBase
::PROP_TYPE
];
281 if ( is_array( $propertyResult['type'] ) ) {
282 $propertyResult['type'] = array_values( $propertyResult['type'] );
283 $result->setIndexedTagName( $propertyResult['type'], 't' );
287 if ( isset( $p[ApiBase
::PROP_NULLABLE
] ) ) {
288 $nullable = $p[ApiBase
::PROP_NULLABLE
];
291 if ( $nullable === true ) {
292 $propertyResult['nullable'] = '';
295 $propResult['properties'][] = $propertyResult;
298 $result->setIndexedTagName( $propResult['properties'], 'property' );
299 $retval['props'][] = $propResult;
302 // default is true for query modules, false for other modules, overriden by ApiBase::PROP_LIST
303 if ( $listResult === true ||
( $listResult !== false && $obj instanceof ApiQueryBase
) ) {
304 $retval['listresult'] = '';
307 $result->setIndexedTagName( $retval['props'], 'prop' );
311 $retval['errors'] = $this->parseErrors( $obj->getPossibleErrors() );
312 $result->setIndexedTagName( $retval['errors'], 'error' );
317 public function isReadMode() {
321 public function getAllowedParams() {
322 $modules = array_keys( $this->getMain()->getModules() );
324 $querymodules = array_keys( $this->queryObj
->getModules() );
325 sort( $querymodules );
326 $formatmodules = array_keys( $this->getMain()->getFormats() );
327 sort( $formatmodules );
330 ApiBase
::PARAM_ISMULTI
=> true,
331 ApiBase
::PARAM_TYPE
=> $modules,
333 'querymodules' => array(
334 ApiBase
::PARAM_ISMULTI
=> true,
335 ApiBase
::PARAM_TYPE
=> $querymodules,
337 'mainmodule' => false,
338 'pagesetmodule' => false,
339 'formatmodules' => array(
340 ApiBase
::PARAM_ISMULTI
=> true,
341 ApiBase
::PARAM_TYPE
=> $formatmodules,
346 public function getParamDescription() {
348 'modules' => 'List of module names (value of the action= parameter)',
349 'querymodules' => 'List of query module names (value of prop=, meta= or list= parameter)',
350 'mainmodule' => 'Get information about the main (top-level) module as well',
351 'pagesetmodule' => 'Get information about the pageset module (providing titles= and friends) as well',
352 'formatmodules' => 'List of format module names (value of format= parameter)',
356 public function getDescription() {
357 return 'Obtain information about certain API parameters and errors';
360 public function getExamples() {
362 'api.php?action=paraminfo&modules=parse&querymodules=allpages|siteinfo'
366 public function getHelpUrls() {
367 return 'https://www.mediawiki.org/wiki/API:Parameter_information';
370 public function getVersion() {
371 return __CLASS__
. ': $Id$';