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
{
35 public function __construct( ApiMain
$main, $action ) {
36 parent
::__construct( $main, $action );
39 public function execute() {
41 $params = $this->extractRequestParams();
43 $this->helpFormat
= $params['helpformat'];
44 $this->context
= new RequestContext
;
45 $this->context
->setUser( new User
); // anon to avoid caching issues
46 $this->context
->setLanguage( $this->getMain()->getLanguage() );
48 if ( is_array( $params['modules'] ) ) {
49 $modules = $params['modules'];
54 if ( is_array( $params['querymodules'] ) ) {
55 $this->logFeatureUsage( 'action=paraminfo&querymodules' );
56 $queryModules = $params['querymodules'];
57 foreach ( $queryModules as $m ) {
58 $modules[] = 'query+' . $m;
61 $queryModules = array();
64 if ( is_array( $params['formatmodules'] ) ) {
65 $this->logFeatureUsage( 'action=paraminfo&formatmodules' );
66 $formatModules = $params['formatmodules'];
67 foreach ( $formatModules as $m ) {
71 $formatModules = array();
76 foreach ( $modules as $m ) {
78 $module = $this->getModuleFromPath( $m );
79 } catch ( UsageException
$ex ) {
80 $this->setWarning( $ex->getMessage() );
87 if ( $module->getParent() && $module->getParent()->getModuleName() == 'query' &&
88 in_array( $module->getModuleName(), $queryModules )
91 $key = 'querymodules';
93 if ( in_array( $module->getModuleName(), $formatModules ) ) {
94 $key = 'formatmodules';
97 $item = $this->getModuleInfo( $module );
99 $item['querytype'] = $item['group'];
101 $res[$key][] = $item;
104 $result = $this->getResult();
105 $result->addValue( array( $this->getModuleName() ), 'helpformat', $this->helpFormat
);
107 foreach ( $res as $key => $stuff ) {
108 $result->setIndexedTagName( $res[$key], 'module' );
111 if ( $params['mainmodule'] ) {
112 $this->logFeatureUsage( 'action=paraminfo&mainmodule' );
113 $res['mainmodule'] = $this->getModuleInfo( $this->getMain() );
116 if ( $params['pagesetmodule'] ) {
117 $this->logFeatureUsage( 'action=paraminfo&pagesetmodule' );
118 $pageSet = new ApiPageSet( $this->getMain()->getModuleManager()->getModule( 'query' ) );
119 $res['pagesetmodule'] = $this->getModuleInfo( $pageSet );
120 unset( $res['pagesetmodule']['name'] );
121 unset( $res['pagesetmodule']['path'] );
122 unset( $res['pagesetmodule']['group'] );
125 $result->addValue( null, $this->getModuleName(), $res );
129 * @param array $res Result array
130 * @param string $key Result key
131 * @param Message[] $msgs
133 protected function formatHelpMessages( array &$res, $key, array $msgs ) {
134 switch ( $this->helpFormat
) {
140 foreach ( $msgs as $m ) {
141 $ret[] = $m->setContext( $this->context
)->text();
143 $res[$key] = join( "\n\n", $ret );
148 foreach ( $msgs as $m ) {
149 $ret[] = $m->setContext( $this->context
)->parseAsBlock();
151 $res[$key] = join( "\n", $ret );
155 $res[$key] = array();
156 foreach ( $msgs as $m ) {
157 $res[$key][] = array(
158 'key' => $m->getKey(),
159 'params' => $m->getParams(),
162 $this->getResult()->setIndexedTagName( $res[$key], 'msg' );
168 * @param ApiBase $module
171 private function getModuleInfo( $module ) {
172 $result = $this->getResult();
174 $path = $module->getModulePath();
176 $ret['name'] = $module->getModuleName();
177 $ret['classname'] = get_class( $module );
178 $ret['path'] = $path;
179 if ( !$module->isMain() ) {
180 $ret['group'] = $module->getParent()->getModuleManager()->getModuleGroup(
181 $module->getModuleName()
184 $ret['prefix'] = $module->getModulePrefix();
186 $this->formatHelpMessages( $ret, 'description', $module->getFinalDescription() );
188 foreach ( $module->getHelpFlags() as $flag ) {
192 $ret['helpurls'] = (array)$module->getHelpUrls();
193 if ( isset( $ret['helpurls'][0] ) && $ret['helpurls'][0] === false ) {
194 $ret['helpurls'] = array();
196 $result->setIndexedTagName( $ret['helpurls'], 'helpurl' );
198 if ( $this->helpFormat
!== 'none' ) {
199 $ret['examples'] = array();
200 $examples = $module->getExamplesMessages();
201 foreach ( $examples as $qs => $msg ) {
205 $msg = ApiBase
::makeMessage( $msg, $this->context
, array(
206 $module->getModulePrefix(),
207 $module->getModuleName(),
208 $module->getModulePath()
210 $this->formatHelpMessages( $item, 'description', array( $msg ) );
211 if ( isset( $item['description'] ) ) {
212 if ( is_array( $item['description'] ) ) {
213 $item['description'] = $item['description'][0];
215 $result->setSubelements( $item, 'description' );
218 $ret['examples'][] = $item;
220 $result->setIndexedTagName( $ret['examples'], 'example' );
223 $ret['parameters'] = array();
224 $params = $module->getFinalParams( ApiBase
::GET_VALUES_FOR_HELP
);
225 $paramDesc = $module->getFinalParamDescription();
226 foreach ( $params as $name => $settings ) {
227 if ( !is_array( $settings ) ) {
228 $settings = array( ApiBase
::PARAM_DFLT
=> $settings );
234 if ( isset( $paramDesc[$name] ) ) {
235 $this->formatHelpMessages( $item, 'description', $paramDesc[$name] );
238 if ( !empty( $settings[ApiBase
::PARAM_REQUIRED
] ) ) {
239 $item['required'] = '';
242 if ( !empty( $settings[ApiBase
::PARAM_DEPRECATED
] ) ) {
243 $item['deprecated'] = '';
246 if ( $name === 'token' && $module->needsToken() ) {
247 $item['tokentype'] = $module->needsToken();
250 if ( !isset( $settings[ApiBase
::PARAM_TYPE
] ) ) {
251 $dflt = isset( $settings[ApiBase
::PARAM_DFLT
] )
252 ?
$settings[ApiBase
::PARAM_DFLT
]
254 if ( is_bool( $dflt ) ) {
255 $settings[ApiBase
::PARAM_TYPE
] = 'boolean';
256 } elseif ( is_string( $dflt ) ||
is_null( $dflt ) ) {
257 $settings[ApiBase
::PARAM_TYPE
] = 'string';
258 } elseif ( is_int( $dflt ) ) {
259 $settings[ApiBase
::PARAM_TYPE
] = 'integer';
263 if ( isset( $settings[ApiBase
::PARAM_DFLT
] ) ) {
264 switch ( $settings[ApiBase
::PARAM_TYPE
] ) {
266 $item['default'] = ( $settings[ApiBase
::PARAM_DFLT
] ?
'true' : 'false' );
269 $item['default'] = strval( $settings[ApiBase
::PARAM_DFLT
] );
272 $item['default'] = intval( $settings[ApiBase
::PARAM_DFLT
] );
275 $item['default'] = $settings[ApiBase
::PARAM_DFLT
];
280 if ( !empty( $settings[ApiBase
::PARAM_ISMULTI
] ) ) {
282 $item['limit'] = $this->getMain()->canApiHighLimits() ?
283 ApiBase
::LIMIT_SML2
:
285 $item['lowlimit'] = ApiBase
::LIMIT_SML1
;
286 $item['highlimit'] = ApiBase
::LIMIT_SML2
;
289 if ( !empty( $settings[ApiBase
::PARAM_ALLOW_DUPLICATES
] ) ) {
290 $item['allowsduplicates'] = '';
293 if ( isset( $settings[ApiBase
::PARAM_TYPE
] ) ) {
294 if ( $settings[ApiBase
::PARAM_TYPE
] === 'submodule' ) {
295 $item['type'] = $module->getModuleManager()->getNames( $name );
296 sort( $item['type'] );
297 $item['submodules'] = '';
299 $item['type'] = $settings[ApiBase
::PARAM_TYPE
];
301 if ( is_array( $item['type'] ) ) {
302 // To prevent sparse arrays from being serialized to JSON as objects
303 $item['type'] = array_values( $item['type'] );
304 $result->setIndexedTagName( $item['type'], 't' );
307 if ( isset( $settings[ApiBase
::PARAM_MAX
] ) ) {
308 $item['max'] = $settings[ApiBase
::PARAM_MAX
];
310 if ( isset( $settings[ApiBase
::PARAM_MAX2
] ) ) {
311 $item['highmax'] = $settings[ApiBase
::PARAM_MAX2
];
313 if ( isset( $settings[ApiBase
::PARAM_MIN
] ) ) {
314 $item['min'] = $settings[ApiBase
::PARAM_MIN
];
317 if ( !empty( $settings[ApiBase
::PARAM_HELP_MSG_INFO
] ) ) {
318 $item['info'] = array();
319 foreach ( $settings[ApiBase
::PARAM_HELP_MSG_INFO
] as $i ) {
320 $tag = array_shift( $i );
325 $info['values'] = $i;
326 $result->setIndexedTagName( $info['values'], 'v' );
328 $this->formatHelpMessages( $info, 'text', array(
329 $this->context
->msg( "apihelp-{$path}-paraminfo-{$tag}" )
330 ->numParams( count( $i ) )
331 ->params( $this->context
->getLanguage()->commaList( $i ) )
332 ->params( $module->getModulePrefix() )
334 $result->setSubelements( $info, 'text' );
335 $item['info'][] = $info;
337 $result->setIndexedTagName( $item['info'], 'i' );
340 $ret['parameters'][] = $item;
342 $result->setIndexedTagName( $ret['parameters'], 'param' );
347 public function isReadMode() {
351 public function getAllowedParams() {
353 $querymodules = $this->getMain()->getModuleManager()
354 ->getModule( 'query' )->getModuleManager()->getNames();
355 sort( $querymodules );
356 $formatmodules = $this->getMain()->getModuleManager()->getNames( 'format' );
357 sort( $formatmodules );
361 ApiBase
::PARAM_ISMULTI
=> true,
363 'helpformat' => array(
364 ApiBase
::PARAM_DFLT
=> 'none',
365 ApiBase
::PARAM_TYPE
=> array( 'html', 'wikitext', 'raw', 'none' ),
368 'querymodules' => array(
369 ApiBase
::PARAM_DEPRECATED
=> true,
370 ApiBase
::PARAM_ISMULTI
=> true,
371 ApiBase
::PARAM_TYPE
=> $querymodules,
373 'mainmodule' => array(
374 ApiBase
::PARAM_DEPRECATED
=> true,
376 'pagesetmodule' => array(
377 ApiBase
::PARAM_DEPRECATED
=> true,
379 'formatmodules' => array(
380 ApiBase
::PARAM_DEPRECATED
=> true,
381 ApiBase
::PARAM_ISMULTI
=> true,
382 ApiBase
::PARAM_TYPE
=> $formatmodules,
387 protected function getExamplesMessages() {
389 'action=paraminfo&modules=parse|phpfm|query+allpages|query+siteinfo'
390 => 'apihelp-paraminfo-example-1',
394 public function getHelpUrls() {
395 return 'https://www.mediawiki.org/wiki/API:Parameter_information';