summaryrefslogtreecommitdiff
path: root/includes/api/ApiMain.php
diff options
context:
space:
mode:
Diffstat (limited to 'includes/api/ApiMain.php')
-rw-r--r--includes/api/ApiMain.php541
1 files changed, 349 insertions, 192 deletions
diff --git a/includes/api/ApiMain.php b/includes/api/ApiMain.php
index 119d7b48..3bf066cf 100644
--- a/includes/api/ApiMain.php
+++ b/includes/api/ApiMain.php
@@ -42,7 +42,7 @@ class ApiMain extends ApiBase {
/**
* When no format parameter is given, this format will be used
*/
- const API_DEFAULT_FORMAT = 'xmlfm';
+ const API_DEFAULT_FORMAT = 'jsonfm';
/**
* List of available modules: action name => module class
@@ -54,6 +54,7 @@ class ApiMain extends ApiBase {
'query' => 'ApiQuery',
'expandtemplates' => 'ApiExpandTemplates',
'parse' => 'ApiParse',
+ 'stashedit' => 'ApiStashEdit',
'opensearch' => 'ApiOpenSearch',
'feedcontributions' => 'ApiFeedContributions',
'feedrecentchanges' => 'ApiFeedRecentChanges',
@@ -63,6 +64,7 @@ class ApiMain extends ApiBase {
'rsd' => 'ApiRsd',
'compare' => 'ApiComparePages',
'tokens' => 'ApiTokens',
+ 'checktoken' => 'ApiCheckToken',
// Write modules
'purge' => 'ApiPurge',
@@ -86,6 +88,8 @@ class ApiMain extends ApiBase {
'options' => 'ApiOptions',
'imagerotate' => 'ApiImageRotate',
'revisiondelete' => 'ApiRevisionDelete',
+ 'managetags' => 'ApiManageTags',
+ 'tag' => 'ApiTag',
);
/**
@@ -121,11 +125,11 @@ class ApiMain extends ApiBase {
*/
private static $mRights = array(
'writeapi' => array(
- 'msg' => 'Use of the write API',
+ 'msg' => 'right-writeapi',
'params' => array()
),
'apihighlimits' => array(
- 'msg' => 'Use higher limits in API queries (Slow queries: $1 results; Fast queries: $2 results). The limits for slow queries also apply to multivalue parameters.',
+ 'msg' => 'api-help-right-apihighlimits',
'params' => array( ApiBase::LIMIT_SML2, ApiBase::LIMIT_BIG2 )
)
);
@@ -136,7 +140,7 @@ class ApiMain extends ApiBase {
*/
private $mPrinter;
- private $mModuleMgr, $mResult;
+ private $mModuleMgr, $mResult, $mErrorFormatter, $mContinuationManager;
private $mAction;
private $mEnableWrite;
private $mInternalMode, $mSquidMaxage, $mModule;
@@ -178,15 +182,33 @@ class ApiMain extends ApiBase {
// Remove all modules other than login
global $wgUser;
- if ( $this->getVal( 'callback' ) !== null ) {
- // JSON callback allows cross-site reads.
- // For safety, strip user credentials.
- wfDebug( "API: stripping user credentials for JSON callback\n" );
+ if ( $this->lacksSameOriginSecurity() ) {
+ // If we're in a mode that breaks the same-origin policy, strip
+ // user credentials for security.
+ wfDebug( "API: stripping user credentials when the same-origin policy is not applied\n" );
$wgUser = new User();
$this->getContext()->setUser( $wgUser );
}
}
+ $uselang = $this->getParameter( 'uselang' );
+ if ( $uselang === 'user' ) {
+ // Assume the parent context is going to return the user language
+ // for uselang=user (see T85635).
+ } else {
+ if ( $uselang === 'content' ) {
+ global $wgContLang;
+ $uselang = $wgContLang->getCode();
+ }
+ $code = RequestContext::sanitizeLangCode( $uselang );
+ $this->getContext()->setLanguage( $code );
+ if ( !$this->mInternalMode ) {
+ global $wgLang;
+ $wgLang = $this->getContext()->getLanguage();
+ RequestContext::getMain()->setLanguage( $wgLang );
+ }
+ }
+
$config = $this->getConfig();
$this->mModuleMgr = new ApiModuleManager( $this );
$this->mModuleMgr->addModules( self::$Modules, 'action' );
@@ -194,7 +216,13 @@ class ApiMain extends ApiBase {
$this->mModuleMgr->addModules( self::$Formats, 'format' );
$this->mModuleMgr->addModules( $config->get( 'APIFormatModules' ), 'format' );
- $this->mResult = new ApiResult( $this );
+ Hooks::run( 'ApiMain::moduleManager', array( $this->mModuleMgr ) );
+
+ $this->mResult = new ApiResult( $this->getConfig()->get( 'APIMaxResultSize' ) );
+ $this->mErrorFormatter = new ApiErrorFormatter_BackCompat( $this->mResult );
+ $this->mResult->setErrorFormatter( $this->mErrorFormatter );
+ $this->mResult->setMainForContinuation( $this );
+ $this->mContinuationManager = null;
$this->mEnableWrite = $enableWrite;
$this->mSquidMaxage = -1; // flag for executeActionWithErrorHandling()
@@ -219,6 +247,43 @@ class ApiMain extends ApiBase {
}
/**
+ * Get the ApiErrorFormatter object associated with current request
+ * @return ApiErrorFormatter
+ */
+ public function getErrorFormatter() {
+ return $this->mErrorFormatter;
+ }
+
+ /**
+ * Get the continuation manager
+ * @return ApiContinuationManager|null
+ */
+ public function getContinuationManager() {
+ return $this->mContinuationManager;
+ }
+
+ /**
+ * Set the continuation manager
+ * @param ApiContinuationManager|null
+ */
+ public function setContinuationManager( $manager ) {
+ if ( $manager !== null ) {
+ if ( !$manager instanceof ApiContinuationManager ) {
+ throw new InvalidArgumentException( __METHOD__ . ': Was passed ' .
+ is_object( $manager ) ? get_class( $manager ) : gettype( $manager )
+ );
+ }
+ if ( $this->mContinuationManager !== null ) {
+ throw new UnexpectedValueException(
+ __METHOD__ . ': tried to set manager from ' . $manager->getSource() .
+ ' when a manager is already set from ' . $this->mContinuationManager->getSource()
+ );
+ }
+ }
+ $this->mContinuationManager = $manager;
+ }
+
+ /**
* Get the API module object. Only works after executeAction()
*
* @return ApiBase
@@ -290,6 +355,16 @@ class ApiMain extends ApiBase {
}
}
+ if ( $mode === 'public' && $this->getParameter( 'uselang' ) === 'user' ) {
+ // User language is used for i18n, so we don't want to publicly
+ // cache. Anons are ok, because if they have non-default language
+ // then there's an appropriate Vary header set by whatever set
+ // their non-default language.
+ wfDebug( __METHOD__ . ": downgrading cache mode 'public' to " .
+ "'anon-public-user-private' due to uselang=user\n" );
+ $mode = 'anon-public-user-private';
+ }
+
wfDebug( __METHOD__ . ": setting cache mode $mode\n" );
$this->mCacheMode = $mode;
}
@@ -328,14 +403,11 @@ class ApiMain extends ApiBase {
* Execute api request. Any errors will be handled if the API was called by the remote client.
*/
public function execute() {
- $this->profileIn();
if ( $this->mInternalMode ) {
$this->executeAction();
} else {
$this->executeActionWithErrorHandling();
}
-
- $this->profileOut();
}
/**
@@ -373,10 +445,6 @@ class ApiMain extends ApiBase {
// avoid sending public cache headers for errors.
$this->sendCacheHeaders();
- if ( $this->mPrinter->getIsHtml() && !$this->mPrinter->isDisabled() ) {
- echo wfReportTime();
- }
-
ob_end_flush();
}
@@ -390,11 +458,17 @@ class ApiMain extends ApiBase {
// Bug 63145: Rollback any open database transactions
if ( !( $e instanceof UsageException ) ) {
// UsageExceptions are intentional, so don't rollback if that's the case
- MWExceptionHandler::rollbackMasterChangesAndLog( $e );
+ try {
+ MWExceptionHandler::rollbackMasterChangesAndLog( $e );
+ } catch ( DBError $e2 ) {
+ // Rollback threw an exception too. Log it, but don't interrupt
+ // our regularly scheduled exception handling.
+ MWExceptionHandler::logException( $e2 );
+ }
}
// Allow extra cleanup and logging
- wfRunHooks( 'ApiMain::onException', array( $this, $e ) );
+ Hooks::run( 'ApiMain::onException', array( $this, $e ) );
// Log it
if ( !( $e instanceof UsageException ) ) {
@@ -421,9 +495,22 @@ class ApiMain extends ApiBase {
// Reset and print just the error message
ob_clean();
- // If the error occurred during printing, do a printer->profileOut()
- $this->mPrinter->safeProfileOut();
- $this->printResult( true );
+ // Printer may not be initialized if the extractRequestParams() fails for the main module
+ $this->createErrorPrinter();
+
+ try {
+ $this->printResult( true );
+ } catch ( UsageException $ex ) {
+ // The error printer itself is failing. Try suppressing its request
+ // parameters and redo.
+ $this->setWarning(
+ 'Error printer failed (will retry without params): ' . $ex->getMessage()
+ );
+ $this->mPrinter = null;
+ $this->createErrorPrinter();
+ $this->mPrinter->forceDefaultParams();
+ $this->printResult( true );
+ }
}
/**
@@ -434,6 +521,7 @@ class ApiMain extends ApiBase {
*
* @since 1.23
* @param Exception $e
+ * @throws Exception
*/
public static function handleApiBeforeMainException( Exception $e ) {
ob_start();
@@ -462,6 +550,8 @@ class ApiMain extends ApiBase {
* If the parameter and the header do match, the header is checked against $wgCrossSiteAJAXdomains
* and $wgCrossSiteAJAXdomainExceptions, and if the origin qualifies, the appropriate CORS
* headers are set.
+ * http://www.w3.org/TR/cors/#resource-requests
+ * http://www.w3.org/TR/cors/#resource-preflight-requests
*
* @return bool False if the caller should abort (403 case), true otherwise (all other cases)
*/
@@ -474,12 +564,14 @@ class ApiMain extends ApiBase {
$request = $this->getRequest();
$response = $request->response();
+
// Origin: header is a space-separated list of origins, check all of them
$originHeader = $request->getHeader( 'Origin' );
if ( $originHeader === false ) {
$origins = array();
} else {
- $origins = explode( ' ', $originHeader );
+ $originHeader = trim( $originHeader );
+ $origins = preg_split( '/\s+/', $originHeader );
}
if ( !in_array( $originParam, $origins ) ) {
@@ -494,18 +586,44 @@ class ApiMain extends ApiBase {
}
$config = $this->getConfig();
- $matchOrigin = self::matchOrigin(
+ $matchOrigin = count( $origins ) === 1 && self::matchOrigin(
$originParam,
$config->get( 'CrossSiteAJAXdomains' ),
$config->get( 'CrossSiteAJAXdomainExceptions' )
);
if ( $matchOrigin ) {
- $response->header( "Access-Control-Allow-Origin: $originParam" );
+ $requestedMethod = $request->getHeader( 'Access-Control-Request-Method' );
+ $preflight = $request->getMethod() === 'OPTIONS' && $requestedMethod !== false;
+ if ( $preflight ) {
+ // This is a CORS preflight request
+ if ( $requestedMethod !== 'POST' && $requestedMethod !== 'GET' ) {
+ // If method is not a case-sensitive match, do not set any additional headers and terminate.
+ return true;
+ }
+ // We allow the actual request to send the following headers
+ $requestedHeaders = $request->getHeader( 'Access-Control-Request-Headers' );
+ if ( $requestedHeaders !== false ) {
+ if ( !self::matchRequestedHeaders( $requestedHeaders ) ) {
+ return true;
+ }
+ $response->header( 'Access-Control-Allow-Headers: ' . $requestedHeaders );
+ }
+
+ // We only allow the actual request to be GET or POST
+ $response->header( 'Access-Control-Allow-Methods: POST, GET' );
+ }
+
+ $response->header( "Access-Control-Allow-Origin: $originHeader" );
$response->header( 'Access-Control-Allow-Credentials: true' );
- $this->getOutput()->addVaryHeader( 'Origin' );
+ $response->header( "Timing-Allow-Origin: $originHeader" ); # http://www.w3.org/TR/resource-timing/#timing-allow-origin
+
+ if ( !$preflight ) {
+ $response->header( 'Access-Control-Expose-Headers: MediaWiki-API-Error, Retry-After, X-Database-Lag' );
+ }
}
+ $this->getOutput()->addVaryHeader( 'Origin' );
return true;
}
@@ -535,6 +653,41 @@ class ApiMain extends ApiBase {
}
/**
+ * Attempt to validate the value of Access-Control-Request-Headers against a list
+ * of headers that we allow the follow up request to send.
+ *
+ * @param string $requestedHeaders Comma seperated list of HTTP headers
+ * @return bool True if all requested headers are in the list of allowed headers
+ */
+ protected static function matchRequestedHeaders( $requestedHeaders ) {
+ if ( trim( $requestedHeaders ) === '' ) {
+ return true;
+ }
+ $requestedHeaders = explode( ',', $requestedHeaders );
+ $allowedAuthorHeaders = array_flip( array(
+ /* simple headers (see spec) */
+ 'accept',
+ 'accept-language',
+ 'content-language',
+ 'content-type',
+ /* non-authorable headers in XHR, which are however requested by some UAs */
+ 'accept-encoding',
+ 'dnt',
+ 'origin',
+ /* MediaWiki whitelist */
+ 'api-user-agent',
+ ) );
+ foreach ( $requestedHeaders as $rHeader ) {
+ $rHeader = strtolower( trim( $rHeader ) );
+ if ( !isset( $allowedAuthorHeaders[$rHeader] ) ) {
+ wfDebugLog( 'api', 'CORS preflight failed on requested header: ' . $rHeader );
+ return false;
+ }
+ }
+ return true;
+ }
+
+ /**
* Helper function to convert wildcard string into a regex
* '*' => '.*?'
* '?' => '.'
@@ -563,8 +716,24 @@ class ApiMain extends ApiBase {
$out->addVaryHeader( 'X-Forwarded-Proto' );
}
+ // The logic should be:
+ // $this->mCacheControl['max-age'] is set?
+ // Use it, the module knows better than our guess.
+ // !$this->mModule || $this->mModule->isWriteMode(), and mCacheMode is private?
+ // Use 0 because we can guess caching is probably the wrong thing to do.
+ // Use $this->getParameter( 'maxage' ), which already defaults to 0.
+ $maxage = 0;
+ if ( isset( $this->mCacheControl['max-age'] ) ) {
+ $maxage = $this->mCacheControl['max-age'];
+ } elseif ( ( $this->mModule && !$this->mModule->isWriteMode() ) ||
+ $this->mCacheMode !== 'private'
+ ) {
+ $maxage = $this->getParameter( 'maxage' );
+ }
+ $privateCache = 'private, must-revalidate, max-age=' . $maxage;
+
if ( $this->mCacheMode == 'private' ) {
- $response->header( 'Cache-Control: private' );
+ $response->header( "Cache-Control: $privateCache" );
return;
}
@@ -576,14 +745,14 @@ class ApiMain extends ApiBase {
$response->header( $out->getXVO() );
if ( $out->haveCacheVaryCookies() ) {
// Logged in, mark this request private
- $response->header( 'Cache-Control: private' );
+ $response->header( "Cache-Control: $privateCache" );
return;
}
// Logged out, send normal public headers below
} elseif ( session_id() != '' ) {
// Logged in or otherwise has session (e.g. anonymous users who have edited)
// Mark request private
- $response->header( 'Cache-Control: private' );
+ $response->header( "Cache-Control: $privateCache" );
return;
} // else no XVO and anonymous, send public headers below
@@ -607,7 +776,7 @@ class ApiMain extends ApiBase {
// Public cache not requested
// Sending a Vary header in this case is harmless, and protects us
// against conditional calls of setCacheMaxAge().
- $response->header( 'Cache-Control: private' );
+ $response->header( "Cache-Control: $privateCache" );
return;
}
@@ -638,45 +807,39 @@ class ApiMain extends ApiBase {
}
/**
- * Replace the result data with the information about an exception.
- * Returns the error code
- * @param Exception $e
- * @return string
+ * Create the printer for error output
*/
- protected function substituteResultWithError( $e ) {
- $result = $this->getResult();
-
- // Printer may not be initialized if the extractRequestParams() fails for the main module
+ private function createErrorPrinter() {
if ( !isset( $this->mPrinter ) ) {
- // The printer has not been created yet. Try to manually get formatter value.
$value = $this->getRequest()->getVal( 'format', self::API_DEFAULT_FORMAT );
if ( !$this->mModuleMgr->isDefined( $value, 'format' ) ) {
$value = self::API_DEFAULT_FORMAT;
}
-
$this->mPrinter = $this->createPrinterByName( $value );
}
// Printer may not be able to handle errors. This is particularly
// likely if the module returns something for getCustomPrinter().
if ( !$this->mPrinter->canPrintErrors() ) {
- $this->mPrinter->safeProfileOut();
$this->mPrinter = $this->createPrinterByName( self::API_DEFAULT_FORMAT );
}
+ }
- // Update raw mode flag for the selected printer.
- $result->setRawMode( $this->mPrinter->getNeedsRawData() );
-
+ /**
+ * Replace the result data with the information about an exception.
+ * Returns the error code
+ * @param Exception $e
+ * @return string
+ */
+ protected function substituteResultWithError( $e ) {
+ $result = $this->getResult();
$config = $this->getConfig();
if ( $e instanceof UsageException ) {
- // User entered incorrect parameters - print usage screen
+ // User entered incorrect parameters - generate error response
$errMessage = $e->getMessageArray();
-
- // Only print the help message when this is for the developer, not runtime
- if ( $this->mPrinter->getWantsHelp() || $this->mAction == 'help' ) {
- ApiResult::setContent( $errMessage, $this->makeHelpMsg() );
- }
+ $link = wfExpandUrl( wfScript( 'api' ) );
+ ApiResult::setContentValue( $errMessage, 'docref', "See $link for API usage" );
} else {
// Something is seriously wrong
if ( ( $e instanceof DBQueryError ) && !$config->get( 'ShowSQLErrors' ) ) {
@@ -687,17 +850,19 @@ class ApiMain extends ApiBase {
$errMessage = array(
'code' => 'internal_api_error_' . get_class( $e ),
- 'info' => $info,
- );
- ApiResult::setContent(
- $errMessage,
- $config->get( 'ShowExceptionDetails' ) ? "\n\n{$e->getTraceAsString()}\n\n" : ''
+ 'info' => '[' . MWExceptionHandler::getLogId( $e ) . '] ' . $info,
);
+ if ( $config->get( 'ShowExceptionDetails' ) ) {
+ ApiResult::setContentValue(
+ $errMessage,
+ 'trace',
+ MWExceptionHandler::getRedactedTraceAsString( $e )
+ );
+ }
}
// Remember all the warnings to re-add them later
- $oldResult = $result->getData();
- $warnings = isset( $oldResult['warnings'] ) ? $oldResult['warnings'] : null;
+ $warnings = $result->getResultData( array( 'warnings' ) );
$result->reset();
// Re-add the id
@@ -756,6 +921,8 @@ class ApiMain extends ApiBase {
/**
* Set up the module for response
* @return ApiBase The module that will handle this action
+ * @throws MWException
+ * @throws UsageException
*/
protected function setupModule() {
// Instantiate the module requested by the user
@@ -856,7 +1023,7 @@ class ApiMain extends ApiBase {
// Allow extensions to stop execution for arbitrary reasons.
$message = false;
- if ( !wfRunHooks( 'ApiCheckCanExecute', array( $module, $user, &$message ) ) ) {
+ if ( !Hooks::run( 'ApiCheckCanExecute', array( $module, $user, &$message ) ) ) {
$this->dieUsageMsg( $message );
}
}
@@ -928,10 +1095,8 @@ class ApiMain extends ApiBase {
$this->checkAsserts( $params );
// Execute
- $module->profileIn();
$module->execute();
- wfRunHooks( 'APIAfterExecute', array( &$module ) );
- $module->profileOut();
+ Hooks::run( 'APIAfterExecute', array( &$module ) );
$this->reportUnusedParams();
@@ -1080,23 +1245,10 @@ class ApiMain extends ApiBase {
$this->setWarning( 'SECURITY WARNING: $wgDebugAPI is enabled' );
}
- $this->getResult()->cleanUpUTF8();
$printer = $this->mPrinter;
- $printer->profileIn();
-
- /**
- * If the help message is requested in the default (xmlfm) format,
- * tell the printer not to escape ampersands so that our links do
- * not break.
- */
- $isHelp = $isError || $this->mAction == 'help';
- $printer->setUnescapeAmps( $isHelp && $printer->getFormat() == 'XML' && $printer->getIsHtml() );
-
- $printer->initPrinter( $isHelp );
-
+ $printer->initPrinter( false );
$printer->execute();
$printer->closePrinter();
- $printer->profileOut();
}
/**
@@ -1113,14 +1265,14 @@ class ApiMain extends ApiBase {
*/
public function getAllowedParams() {
return array(
- 'format' => array(
- ApiBase::PARAM_DFLT => ApiMain::API_DEFAULT_FORMAT,
- ApiBase::PARAM_TYPE => 'submodule',
- ),
'action' => array(
ApiBase::PARAM_DFLT => 'help',
ApiBase::PARAM_TYPE => 'submodule',
),
+ 'format' => array(
+ ApiBase::PARAM_DFLT => ApiMain::API_DEFAULT_FORMAT,
+ ApiBase::PARAM_TYPE => 'submodule',
+ ),
'maxlag' => array(
ApiBase::PARAM_TYPE => 'integer'
),
@@ -1139,126 +1291,136 @@ class ApiMain extends ApiBase {
'servedby' => false,
'curtimestamp' => false,
'origin' => null,
+ 'uselang' => array(
+ ApiBase::PARAM_DFLT => 'user',
+ ),
);
}
- /**
- * See ApiBase for description.
- *
- * @return array
- */
- public function getParamDescription() {
+ /** @see ApiBase::getExamplesMessages() */
+ protected function getExamplesMessages() {
return array(
- 'format' => 'The format of the output',
- 'action' => 'What action you would like to perform. See below for module help',
- 'maxlag' => array(
- 'Maximum lag can be used when MediaWiki is installed on a database replicated cluster.',
- 'To save actions causing any more site replication lag, this parameter can make the client',
- 'wait until the replication lag is less than the specified value.',
- 'In case of a replag error, error code "maxlag" is returned, with the message like',
- '"Waiting for $host: $lag seconds lagged\n".',
- 'See https://www.mediawiki.org/wiki/Manual:Maxlag_parameter for more information',
- ),
- 'smaxage' => 'Set the s-maxage header to this many seconds. Errors are never cached',
- 'maxage' => 'Set the max-age header to this many seconds. Errors are never cached',
- 'assert' => 'Verify the user is logged in if set to "user", or has the bot userright if "bot"',
- 'requestid' => 'Request ID to distinguish requests. This will just be output back to you',
- 'servedby' => 'Include the hostname that served the request in the ' .
- 'results. Unconditionally shown on error',
- 'curtimestamp' => 'Include the current timestamp in the result.',
- 'origin' => array(
- 'When accessing the API using a cross-domain AJAX request (CORS), set this to the',
- 'originating domain. This must be included in any pre-flight request, and',
- 'therefore must be part of the request URI (not the POST body). This must match',
- 'one of the origins in the Origin: header exactly, so it has to be set to ',
- 'something like http://en.wikipedia.org or https://meta.wikimedia.org . If this',
- 'parameter does not match the Origin: header, a 403 response will be returned. If',
- 'this parameter matches the Origin: header and the origin is whitelisted, an',
- 'Access-Control-Allow-Origin header will be set.',
- ),
+ 'action=help'
+ => 'apihelp-help-example-main',
+ 'action=help&recursivesubmodules=1'
+ => 'apihelp-help-example-recursive',
);
}
+ public function modifyHelp( array &$help, array $options ) {
+ // Wish PHP had an "array_insert_before". Instead, we have to manually
+ // reindex the array to get 'permissions' in the right place.
+ $oldHelp = $help;
+ $help = array();
+ foreach ( $oldHelp as $k => $v ) {
+ if ( $k === 'submodules' ) {
+ $help['permissions'] = '';
+ }
+ $help[$k] = $v;
+ }
+ $help['credits'] = '';
+
+ // Fill 'permissions'
+ $help['permissions'] .= Html::openElement( 'div',
+ array( 'class' => 'apihelp-block apihelp-permissions' ) );
+ $m = $this->msg( 'api-help-permissions' );
+ if ( !$m->isDisabled() ) {
+ $help['permissions'] .= Html::rawElement( 'div', array( 'class' => 'apihelp-block-head' ),
+ $m->numParams( count( self::$mRights ) )->parse()
+ );
+ }
+ $help['permissions'] .= Html::openElement( 'dl' );
+ foreach ( self::$mRights as $right => $rightMsg ) {
+ $help['permissions'] .= Html::element( 'dt', null, $right );
+
+ $rightMsg = $this->msg( $rightMsg['msg'], $rightMsg['params'] )->parse();
+ $help['permissions'] .= Html::rawElement( 'dd', null, $rightMsg );
+
+ $groups = array_map( function ( $group ) {
+ return $group == '*' ? 'all' : $group;
+ }, User::getGroupsWithPermission( $right ) );
+
+ $help['permissions'] .= Html::rawElement( 'dd', null,
+ $this->msg( 'api-help-permissions-granted-to' )
+ ->numParams( count( $groups ) )
+ ->params( $this->getLanguage()->commaList( $groups ) )
+ ->parse()
+ );
+ }
+ $help['permissions'] .= Html::closeElement( 'dl' );
+ $help['permissions'] .= Html::closeElement( 'div' );
+
+ // Fill 'credits', if applicable
+ if ( empty( $options['nolead'] ) ) {
+ $help['credits'] .= Html::element( 'h' . min( 6, $options['headerlevel'] + 1 ),
+ array( 'id' => '+credits', 'class' => 'apihelp-header' ),
+ $this->msg( 'api-credits-header' )->parse()
+ );
+ $help['credits'] .= $this->msg( 'api-credits' )->useDatabase( false )->parseAsBlock();
+ }
+ }
+
+ private $mCanApiHighLimits = null;
+
/**
- * See ApiBase for description.
- *
- * @return array
+ * Check whether the current user is allowed to use high limits
+ * @return bool
*/
- public function getDescription() {
- return array(
- '',
- '',
- '**********************************************************************************************',
- '** **',
- '** This is an auto-generated MediaWiki API documentation page **',
- '** **',
- '** Documentation and Examples: **',
- '** https://www.mediawiki.org/wiki/API **',
- '** **',
- '**********************************************************************************************',
- '',
- 'Status: All features shown on this page should be working, but the API',
- ' is still in active development, and may change at any time.',
- ' Make sure to monitor our mailing list for any updates.',
- '',
- 'Erroneous requests: When erroneous requests are sent to the API, a HTTP header will be sent',
- ' with the key "MediaWiki-API-Error" and then both the value of the',
- ' header and the error code sent back will be set to the same value.',
- '',
- ' In the case of an invalid action being passed, these will have a value',
- ' of "unknown_action".',
- '',
- ' For more information see https://www.mediawiki.org' .
- '/wiki/API:Errors_and_warnings',
- '',
- 'Documentation: https://www.mediawiki.org/wiki/API:Main_page',
- 'FAQ https://www.mediawiki.org/wiki/API:FAQ',
- 'Mailing list: https://lists.wikimedia.org/mailman/listinfo/mediawiki-api',
- 'Api Announcements: https://lists.wikimedia.org/mailman/listinfo/mediawiki-api-announce',
- 'Bugs & Requests: https://bugzilla.wikimedia.org/buglist.cgi?component=API&' .
- 'bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&order=bugs.delta_ts',
- '',
- '',
- '',
- '',
- '',
- );
+ public function canApiHighLimits() {
+ if ( !isset( $this->mCanApiHighLimits ) ) {
+ $this->mCanApiHighLimits = $this->getUser()->isAllowed( 'apihighlimits' );
+ }
+
+ return $this->mCanApiHighLimits;
}
/**
- * Returns an array of strings with credits for the API
- * @return array
+ * Overrides to return this instance's module manager.
+ * @return ApiModuleManager
*/
- protected function getCredits() {
- return array(
- 'API developers:',
- ' Roan Kattouw (lead developer Sep 2007-2009)',
- ' Victor Vasiliev',
- ' Bryan Tong Minh',
- ' Sam Reed',
- ' Yuri Astrakhan (creator, lead developer Sep 2006-Sep 2007, 2012-2013)',
- ' Brad Jorsch (lead developer 2013-now)',
- '',
- 'Please send your comments, suggestions and questions to mediawiki-api@lists.wikimedia.org',
- 'or file a bug report at https://bugzilla.wikimedia.org/'
+ public function getModuleManager() {
+ return $this->mModuleMgr;
+ }
+
+ /**
+ * Fetches the user agent used for this request
+ *
+ * The value will be the combination of the 'Api-User-Agent' header (if
+ * any) and the standard User-Agent header (if any).
+ *
+ * @return string
+ */
+ public function getUserAgent() {
+ return trim(
+ $this->getRequest()->getHeader( 'Api-user-agent' ) . ' ' .
+ $this->getRequest()->getHeader( 'User-agent' )
);
}
+ /************************************************************************//**
+ * @name Deprecated
+ * @{
+ */
+
/**
* Sets whether the pretty-printer should format *bold* and $italics$
*
+ * @deprecated since 1.25
* @param bool $help
*/
public function setHelp( $help = true ) {
+ wfDeprecated( __METHOD__, '1.25' );
$this->mPrinter->setHelp( $help );
}
/**
* Override the parent to generate help messages for all available modules.
*
+ * @deprecated since 1.25
* @return string
*/
public function makeHelpMsg() {
+ wfDeprecated( __METHOD__, '1.25' );
global $wgMemc;
$this->setHelp();
// Get help text from cache if present
@@ -1281,9 +1443,11 @@ class ApiMain extends ApiBase {
}
/**
+ * @deprecated since 1.25
* @return mixed|string
*/
public function reallyMakeHelpMsg() {
+ wfDeprecated( __METHOD__, '1.25' );
$this->setHelp();
// Use parent to make default message for the main module
@@ -1305,8 +1469,12 @@ class ApiMain extends ApiBase {
$msg .= "\n$astriks Permissions $astriks\n\n";
foreach ( self::$mRights as $right => $rightMsg ) {
+ $rightsMsg = $this->msg( $rightMsg['msg'], $rightMsg['params'] )
+ ->useDatabase( false )
+ ->inLanguage( 'en' )
+ ->text();
$groups = User::getGroupsWithPermission( $right );
- $msg .= "* " . $right . " *\n " . wfMsgReplaceArgs( $rightMsg['msg'], $rightMsg['params'] ) .
+ $msg .= "* " . $right . " *\n $rightsMsg" .
"\nGranted to:\n " . str_replace( '*', 'all', implode( ', ', $groups ) ) . "\n\n";
}
@@ -1321,18 +1489,22 @@ class ApiMain extends ApiBase {
$msg .= "\n";
}
- $msg .= "\n*** Credits: ***\n " . implode( "\n ", $this->getCredits() ) . "\n";
+ $credits = $this->msg( 'api-credits' )->useDatabase( 'false' )->inLanguage( 'en' )->text();
+ $credits = str_replace( "\n", "\n ", $credits );
+ $msg .= "\n*** Credits: ***\n $credits\n";
return $msg;
}
/**
+ * @deprecated since 1.25
* @param ApiBase $module
* @param string $paramName What type of request is this? e.g. action,
* query, list, prop, meta, format
* @return string
*/
public static function makeHelpMsgHeader( $module, $paramName ) {
+ wfDeprecated( __METHOD__, '1.25' );
$modulePrefix = $module->getModulePrefix();
if ( strval( $modulePrefix ) !== '' ) {
$modulePrefix = "($modulePrefix) ";
@@ -1341,20 +1513,6 @@ class ApiMain extends ApiBase {
return "* $paramName={$module->getModuleName()} $modulePrefix*";
}
- private $mCanApiHighLimits = null;
-
- /**
- * Check whether the current user is allowed to use high limits
- * @return bool
- */
- public function canApiHighLimits() {
- if ( !isset( $this->mCanApiHighLimits ) ) {
- $this->mCanApiHighLimits = $this->getUser()->isAllowed( 'apihighlimits' );
- }
-
- return $this->mCanApiHighLimits;
- }
-
/**
* Check whether the user wants us to show version information in the API help
* @return bool
@@ -1367,14 +1525,6 @@ class ApiMain extends ApiBase {
}
/**
- * Overrides to return this instance's module manager.
- * @return ApiModuleManager
- */
- public function getModuleManager() {
- return $this->mModuleMgr;
- }
-
- /**
* Add or overwrite a module in this ApiMain instance. Intended for use by extending
* classes who wish to add their own modules to their lexicon or override the
* behavior of inherent ones.
@@ -1418,11 +1568,13 @@ class ApiMain extends ApiBase {
public function getFormats() {
return $this->getModuleManager()->getNamesWithClasses( 'format' );
}
+
+ /**@}*/
+
}
/**
* This exception will be thrown when dieUsage is called to stop module execution.
- * The exception handling code will print a help screen explaining how this API may be used.
*
* @ingroup API
*/
@@ -1476,3 +1628,8 @@ class UsageException extends MWException {
return "{$this->getCodeString()}: {$this->getMessage()}";
}
}
+
+/**
+ * For really cool vim folding this needs to be at the end:
+ * vim: foldmarker=@{,@} foldmethod=marker
+ */