df457f3809
The existing API help, formatted as basically a plain-text document embedded in XML and with a little bolding and a few links syntax-highlighted in after the fact, works ok for experienced programmers but isn't at all newbie-friendly. Further, all the help is hard-coded in English, which isn't very friendly to non-English speakers. So let's rewrite it. The help text is now obtained from i18n messages and output in HTML, with the default display consisting of help for a single module with links to help for other modules. This, of course, necessitates deprecating many of the existing help-related methods and hooks and replacing them with new ones, but backwards compatibility is maintained for almost everything. At the same time, action=paraminfo also needs to support the 'description' and other help-related fields being output in wikitext or HTML, and I11cb063d (to access all modules via the 'modules' parameter instead of having 'modules', 'formatmodules', 'querymodules', and so on) is folded in. And we also add Special:ApiHelp. When directly accessed, it simply redirects to api.php with appropriate parameters. But it's also transcludable to allow up-to-date API help text to be included within the on-wiki documentation. Note this patch doesn't actually add i18n messages for any API modules besides ApiMain and ApiHelp. That will come in a followup patch, but for the moment the backwards-compatibility code handles them nicely. While we're messing with the documentation, we may as well add the "internal" flag requested in bug 62905 (although the 'includeinternal' parameter it also requests doesn't make much sense anymore) and a "deprecated" flag that's needed by several modules now. Bug: 30936 Bug: 38126 Bug: 42343 Bug: 45641 Bug: 62905 Bug: 63211 Change-Id: Ib14c00df06d85c2f6364d83b2b10ce34c7f513cc
104 lines
2.8 KiB
PHP
104 lines
2.8 KiB
PHP
<?php
|
|
/**
|
|
*
|
|
*
|
|
* Created on Sep 19, 2006
|
|
*
|
|
* Copyright © 2006 Yuri Astrakhan "<Firstname><Lastname>@gmail.com"
|
|
*
|
|
* This program is free software; you can redistribute it and/or modify
|
|
* it under the terms of the GNU General Public License as published by
|
|
* the Free Software Foundation; either version 2 of the License, or
|
|
* (at your option) any later version.
|
|
*
|
|
* This program is distributed in the hope that it will be useful,
|
|
* but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
* GNU General Public License for more details.
|
|
*
|
|
* You should have received a copy of the GNU General Public License along
|
|
* with this program; if not, write to the Free Software Foundation, Inc.,
|
|
* 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
|
|
* http://www.gnu.org/copyleft/gpl.html
|
|
*
|
|
* @file
|
|
*/
|
|
|
|
/**
|
|
* API JSON output formatter
|
|
* @ingroup API
|
|
*/
|
|
class ApiFormatJson extends ApiFormatBase {
|
|
|
|
private $mIsRaw;
|
|
|
|
public function __construct( ApiMain $main, $format ) {
|
|
parent::__construct( $main, $format );
|
|
$this->mIsRaw = ( $format === 'rawfm' );
|
|
}
|
|
|
|
public function getMimeType() {
|
|
$params = $this->extractRequestParams();
|
|
// callback:
|
|
if ( $params['callback'] ) {
|
|
return 'text/javascript';
|
|
}
|
|
|
|
return 'application/json';
|
|
}
|
|
|
|
public function getNeedsRawData() {
|
|
return $this->mIsRaw;
|
|
}
|
|
|
|
/**
|
|
* @deprecated since 1.25
|
|
*/
|
|
public function getWantsHelp() {
|
|
wfDeprecated( __METHOD__, '1.25' );
|
|
// Help is always ugly in JSON
|
|
return false;
|
|
}
|
|
|
|
public function execute() {
|
|
$params = $this->extractRequestParams();
|
|
$json = FormatJson::encode(
|
|
$this->getResultData(),
|
|
$this->getIsHtml(),
|
|
$params['utf8'] ? FormatJson::ALL_OK : FormatJson::XMLMETA_OK
|
|
);
|
|
$callback = $params['callback'];
|
|
if ( $callback !== null ) {
|
|
$callback = preg_replace( "/[^][.\\'\\\"_A-Za-z0-9]/", '', $callback );
|
|
# Prepend a comment to try to avoid attacks against content
|
|
# sniffers, such as bug 68187.
|
|
$this->printText( "/**/$callback($json)" );
|
|
} else {
|
|
$this->printText( $json );
|
|
}
|
|
}
|
|
|
|
public function getAllowedParams() {
|
|
return array(
|
|
'callback' => null,
|
|
'utf8' => false,
|
|
);
|
|
}
|
|
|
|
public function getParamDescription() {
|
|
return array(
|
|
'callback' => 'If specified, wraps the output into a given function ' .
|
|
'call. For safety, all user-specific data will be restricted.',
|
|
'utf8' => 'If specified, encodes most (but not all) non-ASCII ' .
|
|
'characters as UTF-8 instead of replacing them with hexadecimal escape sequences.',
|
|
);
|
|
}
|
|
|
|
public function getDescription() {
|
|
if ( $this->mIsRaw ) {
|
|
return 'Output data with the debugging elements in JSON format' . parent::getDescription();
|
|
}
|
|
|
|
return 'Output data in JSON format' . parent::getDescription();
|
|
}
|
|
}
|