Merge "Special:Newpages feed now shows first revision instead of latest revision"
[lhc/web/wiklou.git] / includes / api / ApiParamInfo.php
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 private $helpFormat;
33 private $context;
34
35 public function __construct( ApiMain $main, $action ) {
36 parent::__construct( $main, $action );
37 }
38
39 public function execute() {
40 // Get parameters
41 $params = $this->extractRequestParams();
42
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() );
47
48 if ( is_array( $params['modules'] ) ) {
49 $modules = [];
50 foreach ( $params['modules'] as $path ) {
51 if ( $path === '*' || $path === '**' ) {
52 $path = "main+$path";
53 }
54 if ( substr( $path, -2 ) === '+*' || substr( $path, -2 ) === ' *' ) {
55 $submodules = true;
56 $path = substr( $path, 0, -2 );
57 $recursive = false;
58 } elseif ( substr( $path, -3 ) === '+**' || substr( $path, -3 ) === ' **' ) {
59 $submodules = true;
60 $path = substr( $path, 0, -3 );
61 $recursive = true;
62 } else {
63 $submodules = false;
64 }
65
66 if ( $submodules ) {
67 try {
68 $module = $this->getModuleFromPath( $path );
69 } catch ( ApiUsageException $ex ) {
70 foreach ( $ex->getStatusValue()->getErrors() as $error ) {
71 $this->addWarning( $error );
72 }
73 continue;
74 }
75 $submodules = $this->listAllSubmodules( $module, $recursive );
76 if ( $submodules ) {
77 $modules = array_merge( $modules, $submodules );
78 } else {
79 $this->addWarning( [ 'apierror-badmodule-nosubmodules', $path ], 'badmodule' );
80 }
81 } else {
82 $modules[] = $path;
83 }
84 }
85 } else {
86 $modules = [];
87 }
88
89 if ( is_array( $params['querymodules'] ) ) {
90 $queryModules = $params['querymodules'];
91 foreach ( $queryModules as $m ) {
92 $modules[] = 'query+' . $m;
93 }
94 } else {
95 $queryModules = [];
96 }
97
98 if ( is_array( $params['formatmodules'] ) ) {
99 $formatModules = $params['formatmodules'];
100 foreach ( $formatModules as $m ) {
101 $modules[] = $m;
102 }
103 } else {
104 $formatModules = [];
105 }
106
107 $modules = array_unique( $modules );
108
109 $res = [];
110
111 foreach ( $modules as $m ) {
112 try {
113 $module = $this->getModuleFromPath( $m );
114 } catch ( ApiUsageException $ex ) {
115 foreach ( $ex->getStatusValue()->getErrors() as $error ) {
116 $this->addWarning( $error );
117 }
118 continue;
119 }
120 $key = 'modules';
121
122 // Back compat
123 $isBCQuery = false;
124 if ( $module->getParent() && $module->getParent()->getModuleName() == 'query' &&
125 in_array( $module->getModuleName(), $queryModules )
126 ) {
127 $isBCQuery = true;
128 $key = 'querymodules';
129 }
130 if ( in_array( $module->getModuleName(), $formatModules ) ) {
131 $key = 'formatmodules';
132 }
133
134 $item = $this->getModuleInfo( $module );
135 if ( $isBCQuery ) {
136 $item['querytype'] = $item['group'];
137 }
138 $res[$key][] = $item;
139 }
140
141 $result = $this->getResult();
142 $result->addValue( [ $this->getModuleName() ], 'helpformat', $this->helpFormat );
143
144 foreach ( $res as $key => $stuff ) {
145 ApiResult::setIndexedTagName( $res[$key], 'module' );
146 }
147
148 if ( $params['mainmodule'] ) {
149 $res['mainmodule'] = $this->getModuleInfo( $this->getMain() );
150 }
151
152 if ( $params['pagesetmodule'] ) {
153 $pageSet = new ApiPageSet( $this->getMain()->getModuleManager()->getModule( 'query' ) );
154 $res['pagesetmodule'] = $this->getModuleInfo( $pageSet );
155 unset( $res['pagesetmodule']['name'] );
156 unset( $res['pagesetmodule']['path'] );
157 unset( $res['pagesetmodule']['group'] );
158 }
159
160 $result->addValue( null, $this->getModuleName(), $res );
161 }
162
163 /**
164 * List all submodules of a module
165 * @param ApiBase $module
166 * @param boolean $recursive
167 * @return string[]
168 */
169 private function listAllSubmodules( ApiBase $module, $recursive ) {
170 $manager = $module->getModuleManager();
171 if ( $manager ) {
172 $paths = [];
173 $names = $manager->getNames();
174 sort( $names );
175 foreach ( $names as $name ) {
176 $submodule = $manager->getModule( $name );
177 $paths[] = $submodule->getModulePath();
178 if ( $recursive && $submodule->getModuleManager() ) {
179 $paths = array_merge( $paths, $this->listAllSubmodules( $submodule, $recursive ) );
180 }
181 }
182 }
183 return $paths;
184 }
185
186 /**
187 * @param array &$res Result array
188 * @param string $key Result key
189 * @param Message[] $msgs
190 * @param bool $joinLists
191 */
192 protected function formatHelpMessages( array &$res, $key, array $msgs, $joinLists = false ) {
193 switch ( $this->helpFormat ) {
194 case 'none':
195 break;
196
197 case 'wikitext':
198 $ret = [];
199 foreach ( $msgs as $m ) {
200 $ret[] = $m->setContext( $this->context )->text();
201 }
202 $res[$key] = implode( "\n\n", $ret );
203 if ( $joinLists ) {
204 $res[$key] = preg_replace( '!^(([*#:;])[^\n]*)\n\n(?=\2)!m', "$1\n", $res[$key] );
205 }
206 break;
207
208 case 'html':
209 $ret = [];
210 foreach ( $msgs as $m ) {
211 $ret[] = $m->setContext( $this->context )->parseAsBlock();
212 }
213 $ret = implode( "\n", $ret );
214 if ( $joinLists ) {
215 $ret = preg_replace( '!\s*</([oud]l)>\s*<\1>\s*!', "\n", $ret );
216 }
217 $res[$key] = Parser::stripOuterParagraph( $ret );
218 break;
219
220 case 'raw':
221 $res[$key] = [];
222 foreach ( $msgs as $m ) {
223 $a = [
224 'key' => $m->getKey(),
225 'params' => $m->getParams(),
226 ];
227 ApiResult::setIndexedTagName( $a['params'], 'param' );
228 if ( $m instanceof ApiHelpParamValueMessage ) {
229 $a['forvalue'] = $m->getParamValue();
230 }
231 $res[$key][] = $a;
232 }
233 ApiResult::setIndexedTagName( $res[$key], 'msg' );
234 break;
235 }
236 }
237
238 /**
239 * @param ApiBase $module
240 * @return array
241 */
242 private function getModuleInfo( $module ) {
243 $ret = [];
244 $path = $module->getModulePath();
245
246 $ret['name'] = $module->getModuleName();
247 $ret['classname'] = get_class( $module );
248 $ret['path'] = $path;
249 if ( !$module->isMain() ) {
250 $ret['group'] = $module->getParent()->getModuleManager()->getModuleGroup(
251 $module->getModuleName()
252 );
253 }
254 $ret['prefix'] = $module->getModulePrefix();
255
256 $sourceInfo = $module->getModuleSourceInfo();
257 if ( $sourceInfo ) {
258 $ret['source'] = $sourceInfo['name'];
259 if ( isset( $sourceInfo['namemsg'] ) ) {
260 $ret['sourcename'] = $this->context->msg( $sourceInfo['namemsg'] )->text();
261 } else {
262 $ret['sourcename'] = $ret['source'];
263 }
264
265 $link = SpecialPage::getTitleFor( 'Version', 'License/' . $sourceInfo['name'] )->getFullURL();
266 if ( isset( $sourceInfo['license-name'] ) ) {
267 $ret['licensetag'] = $sourceInfo['license-name'];
268 $ret['licenselink'] = (string)$link;
269 } elseif ( SpecialVersion::getExtLicenseFileName( dirname( $sourceInfo['path'] ) ) ) {
270 $ret['licenselink'] = (string)$link;
271 }
272 }
273
274 $this->formatHelpMessages( $ret, 'description', $module->getFinalDescription() );
275
276 foreach ( $module->getHelpFlags() as $flag ) {
277 $ret[$flag] = true;
278 }
279
280 $ret['helpurls'] = (array)$module->getHelpUrls();
281 if ( isset( $ret['helpurls'][0] ) && $ret['helpurls'][0] === false ) {
282 $ret['helpurls'] = [];
283 }
284 ApiResult::setIndexedTagName( $ret['helpurls'], 'helpurl' );
285
286 if ( $this->helpFormat !== 'none' ) {
287 $ret['examples'] = [];
288 $examples = $module->getExamplesMessages();
289 foreach ( $examples as $qs => $msg ) {
290 $item = [
291 'query' => $qs
292 ];
293 $msg = ApiBase::makeMessage( $msg, $this->context, [
294 $module->getModulePrefix(),
295 $module->getModuleName(),
296 $module->getModulePath()
297 ] );
298 $this->formatHelpMessages( $item, 'description', [ $msg ] );
299 if ( isset( $item['description'] ) ) {
300 if ( is_array( $item['description'] ) ) {
301 $item['description'] = $item['description'][0];
302 } else {
303 ApiResult::setSubelementsList( $item, 'description' );
304 }
305 }
306 $ret['examples'][] = $item;
307 }
308 ApiResult::setIndexedTagName( $ret['examples'], 'example' );
309 }
310
311 $ret['parameters'] = [];
312 $params = $module->getFinalParams( ApiBase::GET_VALUES_FOR_HELP );
313 $paramDesc = $module->getFinalParamDescription();
314 foreach ( $params as $name => $settings ) {
315 if ( !is_array( $settings ) ) {
316 $settings = [ ApiBase::PARAM_DFLT => $settings ];
317 }
318
319 $item = [
320 'name' => $name
321 ];
322 if ( isset( $paramDesc[$name] ) ) {
323 $this->formatHelpMessages( $item, 'description', $paramDesc[$name], true );
324 }
325
326 $item['required'] = !empty( $settings[ApiBase::PARAM_REQUIRED] );
327
328 if ( !empty( $settings[ApiBase::PARAM_DEPRECATED] ) ) {
329 $item['deprecated'] = true;
330 }
331
332 if ( $name === 'token' && $module->needsToken() ) {
333 $item['tokentype'] = $module->needsToken();
334 }
335
336 if ( !isset( $settings[ApiBase::PARAM_TYPE] ) ) {
337 $dflt = isset( $settings[ApiBase::PARAM_DFLT] )
338 ? $settings[ApiBase::PARAM_DFLT]
339 : null;
340 if ( is_bool( $dflt ) ) {
341 $settings[ApiBase::PARAM_TYPE] = 'boolean';
342 } elseif ( is_string( $dflt ) || is_null( $dflt ) ) {
343 $settings[ApiBase::PARAM_TYPE] = 'string';
344 } elseif ( is_int( $dflt ) ) {
345 $settings[ApiBase::PARAM_TYPE] = 'integer';
346 }
347 }
348
349 if ( isset( $settings[ApiBase::PARAM_DFLT] ) ) {
350 switch ( $settings[ApiBase::PARAM_TYPE] ) {
351 case 'boolean':
352 $item['default'] = (bool)$settings[ApiBase::PARAM_DFLT];
353 break;
354 case 'string':
355 case 'text':
356 case 'password':
357 $item['default'] = strval( $settings[ApiBase::PARAM_DFLT] );
358 break;
359 case 'integer':
360 case 'limit':
361 $item['default'] = intval( $settings[ApiBase::PARAM_DFLT] );
362 break;
363 case 'timestamp':
364 $item['default'] = wfTimestamp( TS_ISO_8601, $settings[ApiBase::PARAM_DFLT] );
365 break;
366 default:
367 $item['default'] = $settings[ApiBase::PARAM_DFLT];
368 break;
369 }
370 }
371
372 $item['multi'] = !empty( $settings[ApiBase::PARAM_ISMULTI] );
373 if ( $item['multi'] ) {
374 $item['limit'] = $this->getMain()->canApiHighLimits() ?
375 ApiBase::LIMIT_SML2 :
376 ApiBase::LIMIT_SML1;
377 $item['lowlimit'] = ApiBase::LIMIT_SML1;
378 $item['highlimit'] = ApiBase::LIMIT_SML2;
379 }
380
381 if ( !empty( $settings[ApiBase::PARAM_ALLOW_DUPLICATES] ) ) {
382 $item['allowsduplicates'] = true;
383 }
384
385 if ( isset( $settings[ApiBase::PARAM_TYPE] ) ) {
386 if ( $settings[ApiBase::PARAM_TYPE] === 'submodule' ) {
387 if ( isset( $settings[ApiBase::PARAM_SUBMODULE_MAP] ) ) {
388 ksort( $settings[ApiBase::PARAM_SUBMODULE_MAP] );
389 $item['type'] = array_keys( $settings[ApiBase::PARAM_SUBMODULE_MAP] );
390 $item['submodules'] = $settings[ApiBase::PARAM_SUBMODULE_MAP];
391 } else {
392 $item['type'] = $module->getModuleManager()->getNames( $name );
393 sort( $item['type'] );
394 $prefix = $module->isMain()
395 ? '' : ( $module->getModulePath() . '+' );
396 $item['submodules'] = [];
397 foreach ( $item['type'] as $v ) {
398 $item['submodules'][$v] = $prefix . $v;
399 }
400 }
401 if ( isset( $settings[ApiBase::PARAM_SUBMODULE_PARAM_PREFIX] ) ) {
402 $item['submoduleparamprefix'] = $settings[ApiBase::PARAM_SUBMODULE_PARAM_PREFIX];
403 }
404
405 $deprecatedSubmodules = [];
406 foreach ( $item['submodules'] as $v => $submodulePath ) {
407 try {
408 $submod = $this->getModuleFromPath( $submodulePath );
409 if ( $submod && $submod->isDeprecated() ) {
410 $deprecatedSubmodules[] = $v;
411 }
412 } catch ( ApiUsageException $ex ) {
413 // Ignore
414 }
415 }
416 if ( $deprecatedSubmodules ) {
417 $item['type'] = array_merge(
418 array_diff( $item['type'], $deprecatedSubmodules ),
419 $deprecatedSubmodules
420 );
421 $item['deprecatedvalues'] = $deprecatedSubmodules;
422 }
423 } elseif ( $settings[ApiBase::PARAM_TYPE] === 'tags' ) {
424 $item['type'] = ChangeTags::listExplicitlyDefinedTags();
425 } else {
426 $item['type'] = $settings[ApiBase::PARAM_TYPE];
427 }
428 if ( is_array( $item['type'] ) ) {
429 // To prevent sparse arrays from being serialized to JSON as objects
430 $item['type'] = array_values( $item['type'] );
431 ApiResult::setIndexedTagName( $item['type'], 't' );
432 }
433
434 // Add 'allspecifier' if applicable
435 if ( $item['type'] === 'namespace' ) {
436 $allowAll = true;
437 $allSpecifier = ApiBase::ALL_DEFAULT_STRING;
438 } else {
439 $allowAll = isset( $settings[ApiBase::PARAM_ALL] )
440 ? $settings[ApiBase::PARAM_ALL]
441 : false;
442 $allSpecifier = ( is_string( $allowAll ) ? $allowAll : ApiBase::ALL_DEFAULT_STRING );
443 }
444 if ( $allowAll && $item['multi'] &&
445 ( is_array( $item['type'] ) || $item['type'] === 'namespace' ) ) {
446 $item['allspecifier'] = $allSpecifier;
447 }
448
449 if ( $item['type'] === 'namespace' &&
450 isset( $settings[ApiBase::PARAM_EXTRA_NAMESPACES] ) &&
451 is_array( $settings[ApiBase::PARAM_EXTRA_NAMESPACES] )
452 ) {
453 $item['extranamespaces'] = $settings[ApiBase::PARAM_EXTRA_NAMESPACES];
454 ApiResult::setArrayType( $item['extranamespaces'], 'array' );
455 ApiResult::setIndexedTagName( $item['extranamespaces'], 'ns' );
456 }
457 }
458 if ( isset( $settings[ApiBase::PARAM_MAX] ) ) {
459 $item['max'] = $settings[ApiBase::PARAM_MAX];
460 }
461 if ( isset( $settings[ApiBase::PARAM_MAX2] ) ) {
462 $item['highmax'] = $settings[ApiBase::PARAM_MAX2];
463 }
464 if ( isset( $settings[ApiBase::PARAM_MIN] ) ) {
465 $item['min'] = $settings[ApiBase::PARAM_MIN];
466 }
467 if ( !empty( $settings[ApiBase::PARAM_RANGE_ENFORCE] ) ) {
468 $item['enforcerange'] = true;
469 }
470 if ( !empty( $settings[ApiBase::PARAM_DEPRECATED_VALUES] ) ) {
471 $deprecatedValues = array_keys( $settings[ApiBase::PARAM_DEPRECATED_VALUES] );
472 if ( is_array( $item['type'] ) ) {
473 $deprecatedValues = array_intersect( $deprecatedValues, $item['type'] );
474 }
475 if ( $deprecatedValues ) {
476 $item['deprecatedvalues'] = array_values( $deprecatedValues );
477 ApiResult::setIndexedTagName( $item['deprecatedvalues'], 'v' );
478 }
479 }
480
481 if ( !empty( $settings[ApiBase::PARAM_HELP_MSG_INFO] ) ) {
482 $item['info'] = [];
483 foreach ( $settings[ApiBase::PARAM_HELP_MSG_INFO] as $i ) {
484 $tag = array_shift( $i );
485 $info = [
486 'name' => $tag,
487 ];
488 if ( count( $i ) ) {
489 $info['values'] = $i;
490 ApiResult::setIndexedTagName( $info['values'], 'v' );
491 }
492 $this->formatHelpMessages( $info, 'text', [
493 $this->context->msg( "apihelp-{$path}-paraminfo-{$tag}" )
494 ->numParams( count( $i ) )
495 ->params( $this->context->getLanguage()->commaList( $i ) )
496 ->params( $module->getModulePrefix() )
497 ] );
498 ApiResult::setSubelementsList( $info, 'text' );
499 $item['info'][] = $info;
500 }
501 ApiResult::setIndexedTagName( $item['info'], 'i' );
502 }
503
504 $ret['parameters'][] = $item;
505 }
506 ApiResult::setIndexedTagName( $ret['parameters'], 'param' );
507
508 $dynamicParams = $module->dynamicParameterDocumentation();
509 if ( $dynamicParams !== null ) {
510 if ( $this->helpFormat === 'none' ) {
511 $ret['dynamicparameters'] = true;
512 } else {
513 $dynamicParams = ApiBase::makeMessage( $dynamicParams, $this->context, [
514 $module->getModulePrefix(),
515 $module->getModuleName(),
516 $module->getModulePath()
517 ] );
518 $this->formatHelpMessages( $ret, 'dynamicparameters', [ $dynamicParams ] );
519 }
520 }
521
522 return $ret;
523 }
524
525 public function isReadMode() {
526 return false;
527 }
528
529 public function getAllowedParams() {
530 // back compat
531 $querymodules = $this->getMain()->getModuleManager()
532 ->getModule( 'query' )->getModuleManager()->getNames();
533 sort( $querymodules );
534 $formatmodules = $this->getMain()->getModuleManager()->getNames( 'format' );
535 sort( $formatmodules );
536
537 return [
538 'modules' => [
539 ApiBase::PARAM_ISMULTI => true,
540 ],
541 'helpformat' => [
542 ApiBase::PARAM_DFLT => 'none',
543 ApiBase::PARAM_TYPE => [ 'html', 'wikitext', 'raw', 'none' ],
544 ],
545
546 'querymodules' => [
547 ApiBase::PARAM_DEPRECATED => true,
548 ApiBase::PARAM_ISMULTI => true,
549 ApiBase::PARAM_TYPE => $querymodules,
550 ],
551 'mainmodule' => [
552 ApiBase::PARAM_DEPRECATED => true,
553 ],
554 'pagesetmodule' => [
555 ApiBase::PARAM_DEPRECATED => true,
556 ],
557 'formatmodules' => [
558 ApiBase::PARAM_DEPRECATED => true,
559 ApiBase::PARAM_ISMULTI => true,
560 ApiBase::PARAM_TYPE => $formatmodules,
561 ]
562 ];
563 }
564
565 protected function getExamplesMessages() {
566 return [
567 'action=paraminfo&modules=parse|phpfm|query%2Ballpages|query%2Bsiteinfo'
568 => 'apihelp-paraminfo-example-1',
569 'action=paraminfo&modules=query%2B*'
570 => 'apihelp-paraminfo-example-2',
571 ];
572 }
573
574 public function getHelpUrls() {
575 return 'https://www.mediawiki.org/wiki/Special:MyLanguage/API:Parameter_information';
576 }
577 }