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( ApiMain
$main, $action ) {
38 parent
::__construct( $main, $action );
39 $this->queryObj
= new ApiQuery( $this->getMain(), 'query' );
42 public function execute() {
44 $params = $this->extractRequestParams();
45 $resultObj = $this->getResult();
49 $this->addModulesInfo( $params, 'modules', $res, $resultObj );
51 $this->addModulesInfo( $params, 'querymodules', $res, $resultObj );
53 if ( $params['mainmodule'] ) {
54 $res['mainmodule'] = $this->getClassInfo( $this->getMain() );
57 if ( $params['pagesetmodule'] ) {
58 $pageSet = new ApiPageSet( $this->queryObj
);
59 $res['pagesetmodule'] = $this->getClassInfo( $pageSet );
62 $this->addModulesInfo( $params, 'formatmodules', $res, $resultObj );
64 $resultObj->addValue( null, $this->getModuleName(), $res );
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.
74 private function addModulesInfo( $params, $type, &$res, $resultObj ) {
75 if ( !is_array( $params[$type] ) ) {
78 $isQuery = ( $type === 'querymodules' );
80 $mgr = $this->queryObj
->getModuleManager();
82 $mgr = $this->getMain()->getModuleManager();
84 $res[$type] = array();
85 foreach ( $params[$type] as $mod ) {
86 if ( !$mgr->isDefined( $mod ) ) {
87 $res[$type][] = array( 'name' => $mod, 'missing' => '' );
90 $obj = $mgr->getModule( $mod );
91 $item = $this->getClassInfo( $obj );
94 $item['querytype'] = $mgr->getModuleGroup( $mod );
96 $res[$type][] = $item;
98 $resultObj->setIndexedTagName( $res[$type], 'module' );
102 * @param ApiBase $obj
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'] = '';
111 // version is deprecated since 1.21, but needs to be returned for v1
112 $retval['version'] = '';
113 $retval['prefix'] = $obj->getModulePrefix();
115 if ( $obj->isReadMode() ) {
116 $retval['readrights'] = '';
118 if ( $obj->isWriteMode() ) {
119 $retval['writerights'] = '';
121 if ( $obj->mustBePosted() ) {
122 $retval['mustbeposted'] = '';
124 if ( $obj instanceof ApiQueryGeneratorBase
) {
125 $retval['generator'] = '';
128 $allowedParams = $obj->getFinalParams( ApiBase
::GET_VALUES_FOR_HELP
);
129 if ( !is_array( $allowedParams ) ) {
133 $retval['helpurls'] = (array)$obj->getHelpUrls();
134 if ( isset( $retval['helpurls'][0] ) && $retval['helpurls'][0] === false ) {
135 $retval['helpurls'] = array();
137 $result->setIndexedTagName( $retval['helpurls'], 'helpurl' );
139 $examples = $obj->getExamples();
140 $retval['allexamples'] = array();
141 if ( $examples !== false ) {
142 if ( is_string( $examples ) ) {
143 $examples = array( $examples );
145 foreach ( $examples as $k => $v ) {
146 if ( strlen( $retval['examples'] ) ) {
147 $retval['examples'] .= ' ';
150 if ( is_numeric( $k ) ) {
151 $retval['examples'] .= $v;
152 ApiResult
::setContent( $item, $v );
154 if ( !is_array( $v ) ) {
155 $item['description'] = $v;
157 $item['description'] = implode( $v, "\n" );
159 $retval['examples'] .= $item['description'] . ' ' . $k;
160 ApiResult
::setContent( $item, $k );
162 $retval['allexamples'][] = $item;
165 $result->setIndexedTagName( $retval['allexamples'], 'example' );
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] );
176 if ( !is_array( $p ) ) {
178 ApiBase
::PARAM_DFLT
=> $p,
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';
194 if ( isset( $p[ApiBase
::PARAM_DEPRECATED
] ) && $p[ApiBase
::PARAM_DEPRECATED
] ) {
195 $a['deprecated'] = '';
197 if ( isset( $p[ApiBase
::PARAM_REQUIRED
] ) && $p[ApiBase
::PARAM_REQUIRED
] ) {
201 if ( isset( $p[ApiBase
::PARAM_DFLT
] ) ) {
202 $type = $p[ApiBase
::PARAM_TYPE
];
203 if ( $type === 'boolean' ) {
204 $a['default'] = ( $p[ApiBase
::PARAM_DFLT
] ?
'true' : 'false' );
205 } elseif ( $type === 'string' ) {
206 $a['default'] = strval( $p[ApiBase
::PARAM_DFLT
] );
207 } elseif ( $type === 'integer' ) {
208 $a['default'] = intval( $p[ApiBase
::PARAM_DFLT
] );
210 $a['default'] = $p[ApiBase
::PARAM_DFLT
];
213 if ( isset( $p[ApiBase
::PARAM_ISMULTI
] ) && $p[ApiBase
::PARAM_ISMULTI
] ) {
215 $a['limit'] = $this->getMain()->canApiHighLimits() ?
216 ApiBase
::LIMIT_SML2
:
218 $a['lowlimit'] = ApiBase
::LIMIT_SML1
;
219 $a['highlimit'] = ApiBase
::LIMIT_SML2
;
222 if ( isset( $p[ApiBase
::PARAM_ALLOW_DUPLICATES
] ) && $p[ApiBase
::PARAM_ALLOW_DUPLICATES
] ) {
223 $a['allowsduplicates'] = '';
226 if ( isset( $p[ApiBase
::PARAM_TYPE
] ) ) {
227 $a['type'] = $p[ApiBase
::PARAM_TYPE
];
228 if ( is_array( $a['type'] ) ) {
229 // To prevent sparse arrays from being serialized to JSON as objects
230 $a['type'] = array_values( $a['type'] );
231 $result->setIndexedTagName( $a['type'], 't' );
234 if ( isset( $p[ApiBase
::PARAM_MAX
] ) ) {
235 $a['max'] = $p[ApiBase
::PARAM_MAX
];
237 if ( isset( $p[ApiBase
::PARAM_MAX2
] ) ) {
238 $a['highmax'] = $p[ApiBase
::PARAM_MAX2
];
240 if ( isset( $p[ApiBase
::PARAM_MIN
] ) ) {
241 $a['min'] = $p[ApiBase
::PARAM_MIN
];
243 $retval['parameters'][] = $a;
245 $result->setIndexedTagName( $retval['parameters'], 'param' );
247 $props = $obj->getFinalResultProperties();
249 if ( $props !== false ) {
250 $retval['props'] = array();
252 foreach ( $props as $prop => $properties ) {
253 $propResult = array();
254 if ( $prop == ApiBase
::PROP_LIST
) {
255 $listResult = $properties;
258 if ( $prop != ApiBase
::PROP_ROOT
) {
259 $propResult['name'] = $prop;
261 $propResult['properties'] = array();
263 foreach ( $properties as $name => $p ) {
264 $propertyResult = array();
266 $propertyResult['name'] = $name;
268 if ( !is_array( $p ) ) {
269 $p = array( ApiBase
::PROP_TYPE
=> $p );
272 $propertyResult['type'] = $p[ApiBase
::PROP_TYPE
];
274 if ( is_array( $propertyResult['type'] ) ) {
275 $propertyResult['type'] = array_values( $propertyResult['type'] );
276 $result->setIndexedTagName( $propertyResult['type'], 't' );
280 if ( isset( $p[ApiBase
::PROP_NULLABLE
] ) ) {
281 $nullable = $p[ApiBase
::PROP_NULLABLE
];
284 if ( $nullable === true ) {
285 $propertyResult['nullable'] = '';
288 $propResult['properties'][] = $propertyResult;
291 $result->setIndexedTagName( $propResult['properties'], 'property' );
292 $retval['props'][] = $propResult;
295 // default is true for query modules, false for other modules, overridden by ApiBase::PROP_LIST
296 if ( $listResult === true ||
( $listResult !== false && $obj instanceof ApiQueryBase
) ) {
297 $retval['listresult'] = '';
300 $result->setIndexedTagName( $retval['props'], 'prop' );
304 $retval['errors'] = $this->parseErrors( $obj->getFinalPossibleErrors() );
305 $result->setIndexedTagName( $retval['errors'], 'error' );
310 public function isReadMode() {
314 public function getAllowedParams() {
315 $modules = $this->getMain()->getModuleManager()->getNames( 'action' );
317 $querymodules = $this->queryObj
->getModuleManager()->getNames();
318 sort( $querymodules );
319 $formatmodules = $this->getMain()->getModuleManager()->getNames( 'format' );
320 sort( $formatmodules );
324 ApiBase
::PARAM_ISMULTI
=> true,
325 ApiBase
::PARAM_TYPE
=> $modules,
327 'querymodules' => array(
328 ApiBase
::PARAM_ISMULTI
=> true,
329 ApiBase
::PARAM_TYPE
=> $querymodules,
331 'mainmodule' => false,
332 'pagesetmodule' => false,
333 'formatmodules' => array(
334 ApiBase
::PARAM_ISMULTI
=> true,
335 ApiBase
::PARAM_TYPE
=> $formatmodules,
340 public function getParamDescription() {
342 'modules' => 'List of module names (value of the action= parameter)',
343 'querymodules' => 'List of query module names (value of prop=, meta= or list= parameter)',
344 'mainmodule' => 'Get information about the main (top-level) module as well',
345 'pagesetmodule' => 'Get information about the pageset module ' .
346 '(providing titles= and friends) as well',
347 'formatmodules' => 'List of format module names (value of format= parameter)',
351 public function getDescription() {
352 return 'Obtain information about certain API parameters and errors.';
355 public function getExamples() {
357 'api.php?action=paraminfo&modules=parse&querymodules=allpages|siteinfo'
361 public function getHelpUrls() {
362 return 'https://www.mediawiki.org/wiki/API:Parameter_information';