This is the main API class, used for both external and internal processing. More...

Inheritance diagram for ApiMain:

Collaboration diagram for ApiMain:

Public Member Functions
	__construct ($context=null, $enableWrite=false)
	Constructs an instance of ApiMain that utilizes the module and format specified by $request.
	canApiHighLimits ()
	Check whether the current user is allowed to use high limits.
	createPrinterByName ($format)
	Create an instance of an output formatter by its name.
	execute ()
	Execute api request.
	getAllowedParams ()
	See ApiBase for description.
	getDescription ()
	See ApiBase for description.
	getFormats ()
	Returns the list of supported formats in form ( 'format' => 'ClassName' )
	getModule ()
	Get the API module object.
	getModules ()
	Get the array mapping module names to class names.
	getParamDescription ()
	See ApiBase for description.
	getPossibleErrors ()
	getPrinter ()
	Get the result formatter object.
	getResult ()
	Get the ApiResult object associated with current request.
	getShowVersions ()
	Check whether the user wants us to show version information in the API help.
	getVersion ()
	Returns the version information of this file, plus it includes the versions for all files that are not callable proper API modules.
	isInternalMode ()
	Return true if the API was started by other PHP code using FauxRequest.
	isReadMode ()
	makeHelpMsg ()
	Override the parent to generate help messages for all available modules.
	reallyMakeHelpMsg ()
	setCacheControl ($directives)
	Set directives (key/value pairs) for the Cache-Control header.
	setCacheMaxAge ($maxage)
	Set how long the response should be cached.
	setCacheMode ($mode)
	Set the type of caching headers which will be sent.
	setCachePrivate ()
	setHelp ($help=true)
	Sets whether the pretty-printer should format bold and $italics$.
	setVaryCookie ()
	Make sure Vary: Cookie and friends are set.
Static Public Member Functions
static	makeHelpMsgHeader ($module, $paramName)
Public Attributes
	$mAction
	$mEnableWrite
	$mFormatNames
	$mFormats
	$mModule
	$mModuleNames
	$mShowVersions
	$mSquidMaxage
const	API_DEFAULT_FORMAT = 'xmlfm'
	When no format parameter is given, this format will be used.
Protected Member Functions
	addFormat ($fmtName, $fmtClass)
	Add or overwrite an output format for this ApiMain.
	addModule ($mdlName, $mdlClass)
	Add or overwrite a module in this ApiMain instance.
	checkExecutePermissions ($module)
	Check for sufficient permissions to execute.
	checkMaxLag ($module, $params)
	Check the max lag if necessary.
	executeAction ()
	Execute the actual module, without any error handling.
	executeActionWithErrorHandling ()
	Execute an action, and in case of an error, erase whatever partial results have been accumulated, and replace it with an error message and a help screen.
	getCredits ()
	Returns an array of strings with credits for the API.
	printResult ($isError)
	Print results using the current printer.
	sendCacheHeaders ()
	setupExecuteAction ()
	Set up for the execution.
	setupExternalResponse ($module, $params)
	Check POST for external response and setup result printer.
	setupModule ()
	Set up the module for response.
	substituteResultWithError ($e)
	Replace the result data with the information about an exception.
Private Attributes
	$mCacheControl = array()
	$mCacheMode = 'private'
	$mCanApiHighLimits = null
	$mInternalMode
	$mModules
	$mPrinter
	$mResult
Static Private Attributes
static	$Formats
	List of available formats: format name => format class.
static	$Modules
	List of available modules: action name => module class.
static	$mRights
	List of user roles that are specifically relevant to the API.

Detailed Description

This is the main API class, used for both external and internal processing.

When executed, it will create the requested formatter object, instantiate and execute an object associated with the needed action, and use formatter to print results. In case of an exception, an error message will be printed using the same formatter.

To use API from another application, run it using FauxRequest object, in which case any internal exceptions will not be handled but passed up to the caller. After successful execution, use getResult() for the resulting data.

Definition at line 41 of file ApiMain.php.

Constructor & Destructor Documentation

ApiMain::__construct	(	$	context = `null`,
		$	enableWrite = `false`
	)

Constructs an instance of ApiMain that utilizes the module and format specified by $request.

Parameters:

$context	IContextSource\|WebRequest - if this is an instance of FauxRequest, errors are thrown and no printing occurs
$enableWrite	bool should be set to true if the api may modify data

Definition at line 142 of file ApiMain.php.

References ContextSource\$context, $Formats, $Modules, $wgAPIModules, $wgUser, ContextSource\getContext(), ApiBase\getMain(), ContextSource\getRequest(), ContextSource\setContext(), and wfDebug().

Here is the call graph for this function:

Member Function Documentation

ApiMain::addFormat	(	$	fmtName,
		$	fmtClass
	)		`[protected]`

Add or overwrite an output format for this ApiMain.

Intended for use by extending classes who wish to add to or modify current formatters.

Parameters:

$fmtName	string The identifier for this format.
$fmtClass	ApiFormatBase The class implementing this format.

Definition at line 1035 of file ApiMain.php.

ApiMain::addModule	(	$	mdlName,
		$	mdlClass
	)		`[protected]`

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.

Parameters:

$mdlName	String The identifier for this module.
$mdlClass	String The class where this module is implemented.

Definition at line 1024 of file ApiMain.php.

ApiMain::canApiHighLimits ( )

Check whether the current user is allowed to use high limits.

Returns:: bool

Definition at line 984 of file ApiMain.php.

References ContextSource\getUser().

Here is the call graph for this function:

ApiMain::checkExecutePermissions ( $ module ) [protected]

Check for sufficient permissions to execute.

Parameters:

$module ApiBase An Api module

Definition at line 649 of file ApiMain.php.

References $user, ApiBase\dieReadOnly(), ApiBase\dieUsageMsg(), User\getGroupPermissions(), ContextSource\getUser(), and wfReadOnly().

Referenced by executeAction().

Here is the call graph for this function:

Here is the caller graph for this function:

ApiMain::checkMaxLag	(	$	module,
		$	params
	)		`[protected]`

Check the max lag if necessary.

Parameters:

$module	ApiBase object: Api module being used
$params	Array an array containing the request parameters.

Returns:: boolean True on success, false should exit immediately

Definition at line 622 of file ApiMain.php.

References $wgShowHostnames, ApiBase\dieUsage(), ContextSource\getRequest(), and wfGetLB().

Referenced by executeAction().

Here is the call graph for this function:

Here is the caller graph for this function:

ApiMain::createPrinterByName ( $ format )

Create an instance of an output formatter by its name.

Parameters:

$format string

Returns:: ApiFormatBase

Definition at line 329 of file ApiMain.php.

References ApiBase\dieUsage().

Referenced by reallyMakeHelpMsg(), setupExternalResponse(), and substituteResultWithError().

Here is the call graph for this function:

Here is the caller graph for this function:

ApiMain::execute ( )

Execute api request.

Any errors will be handled if the API was called by the remote client.

Reimplemented from ApiBase.

Definition at line 339 of file ApiMain.php.

References executeAction(), executeActionWithErrorHandling(), ApiBase\profileIn(), and ApiBase\profileOut().

Here is the call graph for this function:

ApiMain::executeAction ( ) [protected]

Execute the actual module, without any error handling.

Definition at line 695 of file ApiMain.php.

References checkExecutePermissions(), checkMaxLag(), printResult(), setupExecuteAction(), setupExternalResponse(), setupModule(), and wfRunHooks().

Referenced by execute(), and executeActionWithErrorHandling().

Here is the call graph for this function:

Here is the caller graph for this function:

ApiMain::executeActionWithErrorHandling ( ) [protected]

Execute an action, and in case of an error, erase whatever partial results have been accumulated, and replace it with an error message and a help screen.

Definition at line 354 of file ApiMain.php.

References echo, executeAction(), ContextSource\getRequest(), printResult(), sendCacheHeaders(), setCacheMode(), substituteResultWithError(), wfDebugLog(), and wfReportTime().

Referenced by execute().

Here is the call graph for this function:

Here is the caller graph for this function:

ApiMain::getAllowedParams ( )

See ApiBase for description.

Returns:: array

Reimplemented from ApiBase.

Definition at line 758 of file ApiMain.php.

References API_DEFAULT_FORMAT, ApiBase\PARAM_DFLT, and ApiBase\PARAM_TYPE.

ApiMain::getCredits ( ) [protected]

Returns an array of strings with credits for the API.

Returns:: array

Definition at line 871 of file ApiMain.php.

Referenced by reallyMakeHelpMsg().

Here is the caller graph for this function:

ApiMain::getDescription ( )

See ApiBase for description.

Returns:: array

Reimplemented from ApiBase.

Definition at line 815 of file ApiMain.php.

ApiMain::getFormats ( )

Returns the list of supported formats in form ( 'format' => 'ClassName' )

Since:: 1.18

Returns:: array

Definition at line 1053 of file ApiMain.php.

ApiMain::getModule ( )

Get the API module object.

Only works after executeAction()

Returns:: ApiBase

Definition at line 214 of file ApiMain.php.

ApiMain::getModules ( )

Get the array mapping module names to class names.

Returns:: array

Definition at line 1043 of file ApiMain.php.

ApiMain::getParamDescription ( )

See ApiBase for description.

Returns:: array

Reimplemented from ApiBase.

Definition at line 790 of file ApiMain.php.

ApiMain::getPossibleErrors ( )

Returns:: array

Reimplemented from ApiBase.

Definition at line 857 of file ApiMain.php.

ApiMain::getPrinter ( )

Get the result formatter object.

Only works after setupExecuteAction()

Returns:: ApiFormatBase

Definition at line 223 of file ApiMain.php.

ApiMain::getResult ( )

Get the ApiResult object associated with current request.

Returns:: ApiResult

Reimplemented from ApiBase.

Definition at line 205 of file ApiMain.php.

Referenced by printResult(), setupExecuteAction(), setupExternalResponse(), and substituteResultWithError().

Here is the caller graph for this function:

ApiMain::getShowVersions ( )

Check whether the user wants us to show version information in the API help.

Returns:: bool

Definition at line 996 of file ApiMain.php.

Referenced by makeHelpMsg().

Here is the caller graph for this function:

ApiMain::getVersion ( )

Returns the version information of this file, plus it includes the versions for all files that are not callable proper API modules.

Returns:: array

Reimplemented from ApiBase.

Definition at line 1006 of file ApiMain.php.

References ApiBase\getBaseVersion().

Here is the call graph for this function:

ApiMain::isInternalMode ( )

Return true if the API was started by other PHP code using FauxRequest.

Returns:: bool

Definition at line 196 of file ApiMain.php.

ApiMain::isReadMode ( )

Returns:: bool

Reimplemented from ApiBase.

Definition at line 749 of file ApiMain.php.

ApiMain::makeHelpMsg ( )

Override the parent to generate help messages for all available modules.

Returns:: string

Reimplemented from ApiBase.

Definition at line 899 of file ApiMain.php.

References $wgAPICacheHelpTimeout, $wgMemc, ApiBase\getModuleName(), getShowVersions(), SpecialVersion\getVersion(), reallyMakeHelpMsg(), setHelp(), and wfMemcKey().

Referenced by reallyMakeHelpMsg(), and substituteResultWithError().

Here is the call graph for this function:

Here is the caller graph for this function:

static ApiMain::makeHelpMsgHeader	(	$	module,
		$	paramName
	)		`[static]`

Parameters:

$module	ApiBase
$paramName	String What type of request is this? e.g. action, query, list, prop, meta, format

Returns:: string

Definition at line 969 of file ApiMain.php.

Referenced by ApiHelp\buildModuleHelp(), ApiQuery\makeHelpMsgHelper(), and reallyMakeHelpMsg().

Here is the caller graph for this function:

ApiMain::printResult ( $ isError ) [protected]

Print results using the current printer.

Parameters:

$isError bool

Definition at line 726 of file ApiMain.php.

References getResult().

Referenced by executeAction(), and executeActionWithErrorHandling().

Here is the call graph for this function:

Here is the caller graph for this function:

ApiMain::reallyMakeHelpMsg ( )

Returns:: mixed|string

Definition at line 922 of file ApiMain.php.

References createPrinterByName(), getCredits(), User\getGroupsWithPermission(), makeHelpMsg(), makeHelpMsgHeader(), setHelp(), and wfMsgReplaceArgs().

Referenced by makeHelpMsg().

Here is the call graph for this function:

Here is the caller graph for this function:

ApiMain::sendCacheHeaders ( ) [protected]

Definition at line 403 of file ApiMain.php.

References $out, $wgUseXVO, $wgVaryOnXFP, ContextSource\getOutput(), ApiBase\getParameter(), ContextSource\getRequest(), and wfTimestamp().

Referenced by executeActionWithErrorHandling().

Here is the call graph for this function:

Here is the caller graph for this function:

ApiMain::setCacheControl ( $ directives )

Set directives (key/value pairs) for the Cache-Control header.

Boolean values will be formatted as such, by including or omitting without an equals sign.

Cache control values set here will only be used if the cache mode is not private, see setCacheMode().

Parameters:

$directives array

Definition at line 303 of file ApiMain.php.

Referenced by setCacheMaxAge().

Here is the caller graph for this function:

ApiMain::setCacheMaxAge ( $ maxage )

Set how long the response should be cached.

Parameters:

$maxage

Definition at line 232 of file ApiMain.php.

References setCacheControl().

Here is the call graph for this function:

ApiMain::setCacheMode ( $ mode )

Set the type of caching headers which will be sent.

Parameters:

$mode

String One of:

'public': Cache this object in public caches, if the maxage or smaxage parameter is set, or if setCacheMaxAge() was called. If a maximum age is not provided by any of these means, the object will be private.
'private': Cache this object only in private client-side caches.
'anon-public-user-private': Make this object cacheable for logged-out users, but private for logged-in users. IMPORTANT: If this is set, it must be set consistently for a given URL, it cannot be set differently depending on things like the contents of the database, or whether the user is logged in.

If the wiki does not allow anonymous users to read it, the mode set here will be ignored, and private caching headers will always be sent. In other words, the "public" mode is equivalent to saying that the data sent is as public as a page view.

For user-dependent data, the private mode should generally be used. The anon-public-user-private mode should only be used where there is a particularly good performance reason for caching the anonymous response, but where the response to logged-in users may differ, or may contain private data.

If this function is never called, then the default will be the private mode.

Definition at line 264 of file ApiMain.php.

References User\getGroupPermissions(), and wfDebug().

Referenced by executeActionWithErrorHandling(), setCachePrivate(), and setVaryCookie().

Here is the call graph for this function:

Here is the caller graph for this function:

ApiMain::setCachePrivate ( )

Deprecated:: since 1.17 Private caching is now the default, so there is usually no need to call this function.

If there is a need, you can use $this->setCacheMode('private')

Definition at line 288 of file ApiMain.php.

References setCacheMode(), and wfDeprecated().

Here is the call graph for this function:

ApiMain::setHelp ( $ help = true )

Sets whether the pretty-printer should format *bold* and $italics$.

Parameters:

$help bool

Definition at line 890 of file ApiMain.php.

Referenced by makeHelpMsg(), and reallyMakeHelpMsg().

Here is the caller graph for this function:

ApiMain::setupExecuteAction ( ) [protected]

Set up for the execution.

Returns:: array

Definition at line 556 of file ApiMain.php.

References $result, $wgShowHostnames, ApiBase\dieUsage(), ApiBase\extractRequestParams(), ApiBase\getParameter(), and getResult().

Referenced by executeAction().

Here is the call graph for this function:

Here is the caller graph for this function:

ApiMain::setupExternalResponse	(	$	module,
		$	params
	)		`[protected]`

Check POST for external response and setup result printer.

Parameters:

$module	ApiBase An Api module
$params	Array an array with the request parameters

Definition at line 674 of file ApiMain.php.

References createPrinterByName(), ApiBase\dieUsageMsg(), ContextSource\getRequest(), and getResult().

Referenced by executeAction().

Here is the call graph for this function:

Here is the caller graph for this function:

ApiMain::setupModule ( ) [protected]

Set up the module for response.

Returns:: ApiBase The module that will handle this action

Definition at line 589 of file ApiMain.php.

References ApiBase\dieUsageMsg(), ContextSource\getRequest(), and ContextSource\getUser().

Referenced by executeAction().

Here is the call graph for this function:

Here is the caller graph for this function:

ApiMain::setVaryCookie ( )

Make sure Vary: Cookie and friends are set.

Use this when the output of a request may be cached for anons but may not be cached for logged-in users.

WARNING: This function must be called CONSISTENTLY for a given URL. This means that a given URL must either always or never call this function; if it sometimes does and sometimes doesn't, stuff will break.

Deprecated:: since 1.17 Use setCacheMode( 'anon-public-user-private' )

Definition at line 317 of file ApiMain.php.

References setCacheMode(), and wfDeprecated().

Here is the call graph for this function:

ApiMain::substituteResultWithError ( $ e ) [protected]

Replace the result data with the information about an exception.

Returns the error code

Parameters:

$e Exception

Returns:: string

Definition at line 491 of file ApiMain.php.

References $result, $wgShowExceptionDetails, $wgShowHostnames, $wgShowSQLErrors, API_DEFAULT_FORMAT, createPrinterByName(), ApiBase\getParameter(), ContextSource\getRequest(), getResult(), makeHelpMsg(), and ApiResult\setContent().

Referenced by executeActionWithErrorHandling().

Here is the call graph for this function:

Here is the caller graph for this function:

Member Data Documentation

ApiMain::$Formats [static, private]

Initial value:

 array(
                'json' => 'ApiFormatJson',
                'jsonfm' => 'ApiFormatJson',
                'php' => 'ApiFormatPhp',
                'phpfm' => 'ApiFormatPhp',
                'wddx' => 'ApiFormatWddx',
                'wddxfm' => 'ApiFormatWddx',
                'xml' => 'ApiFormatXml',
                'xmlfm' => 'ApiFormatXml',
                'yaml' => 'ApiFormatYaml',
                'yamlfm' => 'ApiFormatYaml',
                'rawfm' => 'ApiFormatJson',
                'txt' => 'ApiFormatTxt',
                'txtfm' => 'ApiFormatTxt',
                'dbg' => 'ApiFormatDbg',
                'dbgfm' => 'ApiFormatDbg',
                'dump' => 'ApiFormatDump',
                'dumpfm' => 'ApiFormatDump',
        )

List of available formats: format name => format class.

Definition at line 87 of file ApiMain.php.

Referenced by __construct().

ApiMain::$mAction

Definition at line 130 of file ApiMain.php.

ApiMain::$mCacheControl = array() [private]

Definition at line 134 of file ApiMain.php.

ApiMain::$mCacheMode = 'private' [private]

Definition at line 133 of file ApiMain.php.

ApiMain::$mCanApiHighLimits = null [private]

Definition at line 978 of file ApiMain.php.

ApiMain::$mEnableWrite

Definition at line 130 of file ApiMain.php.

ApiMain::$mFormatNames

Definition at line 129 of file ApiMain.php.

ApiMain::$mFormats

Definition at line 129 of file ApiMain.php.

ApiMain::$mInternalMode [private]

Definition at line 131 of file ApiMain.php.

ApiMain::$mModule

Definition at line 131 of file ApiMain.php.

ApiMain::$mModuleNames

Definition at line 129 of file ApiMain.php.

ApiMain::$mModules [private]

Definition at line 129 of file ApiMain.php.

ApiMain::$Modules [static, private]

List of available modules: action name => module class.

Definition at line 51 of file ApiMain.php.

Referenced by __construct().

ApiMain::$mPrinter [private]

Definition at line 127 of file ApiMain.php.

ApiMain::$mResult [private]

Definition at line 130 of file ApiMain.php.

ApiMain::$mRights [static, private]

Initial value:

 array(
                'writeapi' => array(
                        'msg' => 'Use of the write API',
                        '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.',
                        'params' => array( ApiBase::LIMIT_SML2, ApiBase::LIMIT_BIG2 )
                )
        )

List of user roles that are specifically relevant to the API.

array( 'right' => array ( 'msg' => 'Some message with a $1', 'params' => array ( $someVarToSubst ) ), );

Definition at line 113 of file ApiMain.php.

ApiMain::$mShowVersions

Definition at line 130 of file ApiMain.php.

ApiMain::$mSquidMaxage

Definition at line 131 of file ApiMain.php.

const ApiMain::API_DEFAULT_FORMAT = 'xmlfm'

When no format parameter is given, this format will be used.

Definition at line 46 of file ApiMain.php.

Referenced by getAllowedParams(), and substituteResultWithError().

The documentation for this class was generated from the following file:

includes/api/ApiMain.php

Public Member Functions

Static Public Member Functions

Public Attributes

Protected Member Functions

Private Attributes

Static Private Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation