3 * Copyright © 2008 Roan Kattouw "<Firstname>.<Lastname>@gmail.com"
5 * This program is free software; you can redistribute it and/or modify
6 * it under the terms of the GNU General Public License as published by
7 * the Free Software Foundation; either version 2 of the License, or
8 * (at your option) any later version.
10 * This program is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 * GNU General Public License for more details.
15 * You should have received a copy of the GNU General Public License along
16 * with this program; if not, write to the Free Software Foundation, Inc.,
17 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
18 * http://www.gnu.org/copyleft/gpl.html
26 class ApiParamInfo
extends ApiBase
{
31 public function __construct( ApiMain
$main, $action ) {
32 parent
::__construct( $main, $action );
35 public function execute() {
37 $params = $this->extractRequestParams();
39 $this->helpFormat
= $params['helpformat'];
40 $this->context
= new RequestContext
;
41 $this->context
->setUser( new User
); // anon to avoid caching issues
42 $this->context
->setLanguage( $this->getMain()->getLanguage() );
44 if ( is_array( $params['modules'] ) ) {
46 foreach ( $params['modules'] as $path ) {
47 if ( $path === '*' ||
$path === '**' ) {
50 if ( substr( $path, -2 ) === '+*' ||
substr( $path, -2 ) === ' *' ) {
52 $path = substr( $path, 0, -2 );
54 } elseif ( substr( $path, -3 ) === '+**' ||
substr( $path, -3 ) === ' **' ) {
56 $path = substr( $path, 0, -3 );
64 $module = $this->getModuleFromPath( $path );
65 } catch ( ApiUsageException
$ex ) {
66 foreach ( $ex->getStatusValue()->getErrors() as $error ) {
67 $this->addWarning( $error );
71 $submodules = $this->listAllSubmodules( $module, $recursive );
73 $modules = array_merge( $modules, $submodules );
75 $this->addWarning( [ 'apierror-badmodule-nosubmodules', $path ], 'badmodule' );
85 if ( is_array( $params['querymodules'] ) ) {
86 $queryModules = $params['querymodules'];
87 foreach ( $queryModules as $m ) {
88 $modules[] = 'query+' . $m;
94 if ( is_array( $params['formatmodules'] ) ) {
95 $formatModules = $params['formatmodules'];
96 foreach ( $formatModules as $m ) {
103 $modules = array_unique( $modules );
107 foreach ( $modules as $m ) {
109 $module = $this->getModuleFromPath( $m );
110 } catch ( ApiUsageException
$ex ) {
111 foreach ( $ex->getStatusValue()->getErrors() as $error ) {
112 $this->addWarning( $error );
120 if ( $module->getParent() && $module->getParent()->getModuleName() == 'query' &&
121 in_array( $module->getModuleName(), $queryModules )
124 $key = 'querymodules';
126 if ( in_array( $module->getModuleName(), $formatModules ) ) {
127 $key = 'formatmodules';
130 $item = $this->getModuleInfo( $module );
132 $item['querytype'] = $item['group'];
134 $res[$key][] = $item;
137 $result = $this->getResult();
138 $result->addValue( [ $this->getModuleName() ], 'helpformat', $this->helpFormat
);
140 foreach ( $res as $key => $stuff ) {
141 ApiResult
::setIndexedTagName( $res[$key], 'module' );
144 if ( $params['mainmodule'] ) {
145 $res['mainmodule'] = $this->getModuleInfo( $this->getMain() );
148 if ( $params['pagesetmodule'] ) {
149 $pageSet = new ApiPageSet( $this->getMain()->getModuleManager()->getModule( 'query' ) );
150 $res['pagesetmodule'] = $this->getModuleInfo( $pageSet );
151 unset( $res['pagesetmodule']['name'] );
152 unset( $res['pagesetmodule']['path'] );
153 unset( $res['pagesetmodule']['group'] );
156 $result->addValue( null, $this->getModuleName(), $res );
160 * List all submodules of a module
161 * @param ApiBase $module
162 * @param bool $recursive
165 private function listAllSubmodules( ApiBase
$module, $recursive ) {
166 $manager = $module->getModuleManager();
169 $names = $manager->getNames();
171 foreach ( $names as $name ) {
172 $submodule = $manager->getModule( $name );
173 $paths[] = $submodule->getModulePath();
174 if ( $recursive && $submodule->getModuleManager() ) {
175 $paths = array_merge( $paths, $this->listAllSubmodules( $submodule, $recursive ) );
183 * @param array &$res Result array
184 * @param string $key Result key
185 * @param Message[] $msgs
186 * @param bool $joinLists
188 protected function formatHelpMessages( array &$res, $key, array $msgs, $joinLists = false ) {
189 switch ( $this->helpFormat
) {
195 foreach ( $msgs as $m ) {
196 $ret[] = $m->setContext( $this->context
)->text();
198 $res[$key] = implode( "\n\n", $ret );
200 $res[$key] = preg_replace( '!^(([*#:;])[^\n]*)\n\n(?=\2)!m', "$1\n", $res[$key] );
206 foreach ( $msgs as $m ) {
207 $ret[] = $m->setContext( $this->context
)->parseAsBlock();
209 $ret = implode( "\n", $ret );
211 $ret = preg_replace( '!\s*</([oud]l)>\s*<\1>\s*!', "\n", $ret );
213 $res[$key] = Parser
::stripOuterParagraph( $ret );
218 foreach ( $msgs as $m ) {
220 'key' => $m->getKey(),
221 'params' => $m->getParams(),
223 ApiResult
::setIndexedTagName( $a['params'], 'param' );
224 if ( $m instanceof ApiHelpParamValueMessage
) {
225 $a['forvalue'] = $m->getParamValue();
229 ApiResult
::setIndexedTagName( $res[$key], 'msg' );
235 * @param ApiBase $module
238 private function getModuleInfo( $module ) {
240 $path = $module->getModulePath();
242 $ret['name'] = $module->getModuleName();
243 $ret['classname'] = get_class( $module );
244 $ret['path'] = $path;
245 if ( !$module->isMain() ) {
246 $ret['group'] = $module->getParent()->getModuleManager()->getModuleGroup(
247 $module->getModuleName()
250 $ret['prefix'] = $module->getModulePrefix();
252 $sourceInfo = $module->getModuleSourceInfo();
254 $ret['source'] = $sourceInfo['name'];
255 if ( isset( $sourceInfo['namemsg'] ) ) {
256 $ret['sourcename'] = $this->context
->msg( $sourceInfo['namemsg'] )->text();
258 $ret['sourcename'] = $ret['source'];
261 $link = SpecialPage
::getTitleFor( 'Version', 'License/' . $sourceInfo['name'] )->getFullURL();
262 if ( isset( $sourceInfo['license-name'] ) ) {
263 $ret['licensetag'] = $sourceInfo['license-name'];
264 $ret['licenselink'] = (string)$link;
265 } elseif ( SpecialVersion
::getExtLicenseFileName( dirname( $sourceInfo['path'] ) ) ) {
266 $ret['licenselink'] = (string)$link;
270 $this->formatHelpMessages( $ret, 'description', $module->getFinalDescription() );
272 foreach ( $module->getHelpFlags() as $flag ) {
276 $ret['helpurls'] = (array)$module->getHelpUrls();
277 if ( isset( $ret['helpurls'][0] ) && $ret['helpurls'][0] === false ) {
278 $ret['helpurls'] = [];
280 ApiResult
::setIndexedTagName( $ret['helpurls'], 'helpurl' );
282 if ( $this->helpFormat
!== 'none' ) {
283 $ret['examples'] = [];
284 $examples = $module->getExamplesMessages();
285 foreach ( $examples as $qs => $msg ) {
289 $msg = ApiBase
::makeMessage( $msg, $this->context
, [
290 $module->getModulePrefix(),
291 $module->getModuleName(),
292 $module->getModulePath()
294 $this->formatHelpMessages( $item, 'description', [ $msg ] );
295 if ( isset( $item['description'] ) ) {
296 if ( is_array( $item['description'] ) ) {
297 $item['description'] = $item['description'][0];
299 ApiResult
::setSubelementsList( $item, 'description' );
302 $ret['examples'][] = $item;
304 ApiResult
::setIndexedTagName( $ret['examples'], 'example' );
307 $ret['parameters'] = [];
308 $ret['templatedparameters'] = [];
309 $params = $module->getFinalParams( ApiBase
::GET_VALUES_FOR_HELP
);
310 $paramDesc = $module->getFinalParamDescription();
312 foreach ( $params as $name => $settings ) {
313 if ( !is_array( $settings ) ) {
314 $settings = [ ApiBase
::PARAM_DFLT
=> $settings ];
322 if ( !empty( $settings[ApiBase
::PARAM_TEMPLATE_VARS
] ) ) {
323 $item['templatevars'] = $settings[ApiBase
::PARAM_TEMPLATE_VARS
];
324 ApiResult
::setIndexedTagName( $item['templatevars'], 'var' );
327 if ( isset( $paramDesc[$name] ) ) {
328 $this->formatHelpMessages( $item, 'description', $paramDesc[$name], true );
331 $item['required'] = !empty( $settings[ApiBase
::PARAM_REQUIRED
] );
333 if ( !empty( $settings[ApiBase
::PARAM_DEPRECATED
] ) ) {
334 $item['deprecated'] = true;
337 if ( $name === 'token' && $module->needsToken() ) {
338 $item['tokentype'] = $module->needsToken();
341 if ( !isset( $settings[ApiBase
::PARAM_TYPE
] ) ) {
342 $dflt = $settings[ApiBase
::PARAM_DFLT
] ??
null;
343 if ( is_bool( $dflt ) ) {
344 $settings[ApiBase
::PARAM_TYPE
] = 'boolean';
345 } elseif ( is_string( $dflt ) ||
is_null( $dflt ) ) {
346 $settings[ApiBase
::PARAM_TYPE
] = 'string';
347 } elseif ( is_int( $dflt ) ) {
348 $settings[ApiBase
::PARAM_TYPE
] = 'integer';
352 if ( isset( $settings[ApiBase
::PARAM_DFLT
] ) ) {
353 switch ( $settings[ApiBase
::PARAM_TYPE
] ) {
355 $item['default'] = (bool)$settings[ApiBase
::PARAM_DFLT
];
360 $item['default'] = strval( $settings[ApiBase
::PARAM_DFLT
] );
364 $item['default'] = (int)$settings[ApiBase
::PARAM_DFLT
];
367 $item['default'] = wfTimestamp( TS_ISO_8601
, $settings[ApiBase
::PARAM_DFLT
] );
370 $item['default'] = $settings[ApiBase
::PARAM_DFLT
];
375 $item['multi'] = !empty( $settings[ApiBase
::PARAM_ISMULTI
] );
376 if ( $item['multi'] ) {
377 $item['lowlimit'] = !empty( $settings[ApiBase
::PARAM_ISMULTI_LIMIT1
] )
378 ?
$settings[ApiBase
::PARAM_ISMULTI_LIMIT1
]
379 : ApiBase
::LIMIT_SML1
;
380 $item['highlimit'] = !empty( $settings[ApiBase
::PARAM_ISMULTI_LIMIT2
] )
381 ?
$settings[ApiBase
::PARAM_ISMULTI_LIMIT2
]
382 : ApiBase
::LIMIT_SML2
;
383 $item['limit'] = $this->getMain()->canApiHighLimits()
388 if ( !empty( $settings[ApiBase
::PARAM_ALLOW_DUPLICATES
] ) ) {
389 $item['allowsduplicates'] = true;
392 if ( isset( $settings[ApiBase
::PARAM_TYPE
] ) ) {
393 if ( $settings[ApiBase
::PARAM_TYPE
] === 'submodule' ) {
394 if ( isset( $settings[ApiBase
::PARAM_SUBMODULE_MAP
] ) ) {
395 ksort( $settings[ApiBase
::PARAM_SUBMODULE_MAP
] );
396 $item['type'] = array_keys( $settings[ApiBase
::PARAM_SUBMODULE_MAP
] );
397 $item['submodules'] = $settings[ApiBase
::PARAM_SUBMODULE_MAP
];
399 $item['type'] = $module->getModuleManager()->getNames( $name );
400 sort( $item['type'] );
401 $prefix = $module->isMain()
402 ?
'' : ( $module->getModulePath() . '+' );
403 $item['submodules'] = [];
404 foreach ( $item['type'] as $v ) {
405 $item['submodules'][$v] = $prefix . $v;
408 if ( isset( $settings[ApiBase
::PARAM_SUBMODULE_PARAM_PREFIX
] ) ) {
409 $item['submoduleparamprefix'] = $settings[ApiBase
::PARAM_SUBMODULE_PARAM_PREFIX
];
412 $deprecatedSubmodules = [];
413 foreach ( $item['submodules'] as $v => $submodulePath ) {
415 $submod = $this->getModuleFromPath( $submodulePath );
416 if ( $submod && $submod->isDeprecated() ) {
417 $deprecatedSubmodules[] = $v;
419 } catch ( ApiUsageException
$ex ) {
423 if ( $deprecatedSubmodules ) {
424 $item['type'] = array_merge(
425 array_diff( $item['type'], $deprecatedSubmodules ),
426 $deprecatedSubmodules
428 $item['deprecatedvalues'] = $deprecatedSubmodules;
430 } elseif ( $settings[ApiBase
::PARAM_TYPE
] === 'tags' ) {
431 $item['type'] = ChangeTags
::listExplicitlyDefinedTags();
433 $item['type'] = $settings[ApiBase
::PARAM_TYPE
];
435 if ( is_array( $item['type'] ) ) {
436 // To prevent sparse arrays from being serialized to JSON as objects
437 $item['type'] = array_values( $item['type'] );
438 ApiResult
::setIndexedTagName( $item['type'], 't' );
441 // Add 'allspecifier' if applicable
442 if ( $item['type'] === 'namespace' ) {
444 $allSpecifier = ApiBase
::ALL_DEFAULT_STRING
;
446 $allowAll = $settings[ApiBase
::PARAM_ALL
] ??
false;
447 $allSpecifier = ( is_string( $allowAll ) ?
$allowAll : ApiBase
::ALL_DEFAULT_STRING
);
449 if ( $allowAll && $item['multi'] &&
450 ( is_array( $item['type'] ) ||
$item['type'] === 'namespace' ) ) {
451 $item['allspecifier'] = $allSpecifier;
454 if ( $item['type'] === 'namespace' &&
455 isset( $settings[ApiBase
::PARAM_EXTRA_NAMESPACES
] ) &&
456 is_array( $settings[ApiBase
::PARAM_EXTRA_NAMESPACES
] )
458 $item['extranamespaces'] = $settings[ApiBase
::PARAM_EXTRA_NAMESPACES
];
459 ApiResult
::setArrayType( $item['extranamespaces'], 'array' );
460 ApiResult
::setIndexedTagName( $item['extranamespaces'], 'ns' );
463 if ( isset( $settings[ApiBase
::PARAM_MAX
] ) ) {
464 $item['max'] = $settings[ApiBase
::PARAM_MAX
];
466 if ( isset( $settings[ApiBase
::PARAM_MAX2
] ) ) {
467 $item['highmax'] = $settings[ApiBase
::PARAM_MAX2
];
469 if ( isset( $settings[ApiBase
::PARAM_MIN
] ) ) {
470 $item['min'] = $settings[ApiBase
::PARAM_MIN
];
472 if ( !empty( $settings[ApiBase
::PARAM_RANGE_ENFORCE
] ) ) {
473 $item['enforcerange'] = true;
475 if ( isset( $settings[self
::PARAM_MAX_BYTES
] ) ) {
476 $item['maxbytes'] = $settings[self
::PARAM_MAX_BYTES
];
478 if ( isset( $settings[self
::PARAM_MAX_CHARS
] ) ) {
479 $item['maxchars'] = $settings[self
::PARAM_MAX_CHARS
];
481 if ( !empty( $settings[ApiBase
::PARAM_DEPRECATED_VALUES
] ) ) {
482 $deprecatedValues = array_keys( $settings[ApiBase
::PARAM_DEPRECATED_VALUES
] );
483 if ( is_array( $item['type'] ) ) {
484 $deprecatedValues = array_intersect( $deprecatedValues, $item['type'] );
486 if ( $deprecatedValues ) {
487 $item['deprecatedvalues'] = array_values( $deprecatedValues );
488 ApiResult
::setIndexedTagName( $item['deprecatedvalues'], 'v' );
492 if ( !empty( $settings[ApiBase
::PARAM_HELP_MSG_INFO
] ) ) {
494 foreach ( $settings[ApiBase
::PARAM_HELP_MSG_INFO
] as $i ) {
495 $tag = array_shift( $i );
500 $info['values'] = $i;
501 ApiResult
::setIndexedTagName( $info['values'], 'v' );
503 $this->formatHelpMessages( $info, 'text', [
504 $this->context
->msg( "apihelp-{$path}-paraminfo-{$tag}" )
505 ->numParams( count( $i ) )
506 ->params( $this->context
->getLanguage()->commaList( $i ) )
507 ->params( $module->getModulePrefix() )
509 ApiResult
::setSubelementsList( $info, 'text' );
510 $item['info'][] = $info;
512 ApiResult
::setIndexedTagName( $item['info'], 'i' );
515 $key = empty( $settings[ApiBase
::PARAM_TEMPLATE_VARS
] ) ?
'parameters' : 'templatedparameters';
516 $ret[$key][] = $item;
518 ApiResult
::setIndexedTagName( $ret['parameters'], 'param' );
519 ApiResult
::setIndexedTagName( $ret['templatedparameters'], 'param' );
521 $dynamicParams = $module->dynamicParameterDocumentation();
522 if ( $dynamicParams !== null ) {
523 if ( $this->helpFormat
=== 'none' ) {
524 $ret['dynamicparameters'] = true;
526 $dynamicParams = ApiBase
::makeMessage( $dynamicParams, $this->context
, [
527 $module->getModulePrefix(),
528 $module->getModuleName(),
529 $module->getModulePath()
531 $this->formatHelpMessages( $ret, 'dynamicparameters', [ $dynamicParams ] );
538 public function isReadMode() {
542 public function getAllowedParams() {
544 $querymodules = $this->getMain()->getModuleManager()
545 ->getModule( 'query' )->getModuleManager()->getNames();
546 sort( $querymodules );
547 $formatmodules = $this->getMain()->getModuleManager()->getNames( 'format' );
548 sort( $formatmodules );
552 ApiBase
::PARAM_ISMULTI
=> true,
555 ApiBase
::PARAM_DFLT
=> 'none',
556 ApiBase
::PARAM_TYPE
=> [ 'html', 'wikitext', 'raw', 'none' ],
560 ApiBase
::PARAM_DEPRECATED
=> true,
561 ApiBase
::PARAM_ISMULTI
=> true,
562 ApiBase
::PARAM_TYPE
=> $querymodules,
565 ApiBase
::PARAM_DEPRECATED
=> true,
568 ApiBase
::PARAM_DEPRECATED
=> true,
571 ApiBase
::PARAM_DEPRECATED
=> true,
572 ApiBase
::PARAM_ISMULTI
=> true,
573 ApiBase
::PARAM_TYPE
=> $formatmodules,
578 protected function getExamplesMessages() {
580 'action=paraminfo&modules=parse|phpfm|query%2Ballpages|query%2Bsiteinfo'
581 => 'apihelp-paraminfo-example-1',
582 'action=paraminfo&modules=query%2B*'
583 => 'apihelp-paraminfo-example-2',
587 public function getHelpUrls() {
588 return 'https://www.mediawiki.org/wiki/Special:MyLanguage/API:Parameter_information';