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.
	getCheck ($name)
	Get a boolean request value, and register the fact that the parameter was used, for logging.
	getDescription ()
	See ApiBase for description.
	getFormats ()
	Returns the list of supported formats in form ( 'format' => 'ClassName' )
	getModule ()
	Get the API module object.
	getModuleManager ()
	Overrides to return this instance's module manager.
	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.
	getUpload ($name)
	Get a request upload, and register the fact that it was used, for logging.
	getVal ($name, $default=null)
	Get a request value, and register the fact that it was used, for logging.
	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
	$mModule
	$mResult
	$mSquidMaxage
const	API_DEFAULT_FORMAT = 'xmlfm'
	When no format parameter is given, this format will be used.
Protected Member Functions
	addFormat ($name, $class)
	Add or overwrite an output format for this ApiMain.
	addModule ($name, $class)
	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.
	encodeRequestLogValue ($s)
	Encode a value in a format suitable for a space-separated log line.
	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.
	getParamsUsed ()
	Get the request parameters used in the course of the preceding execute() request.
	handleCORS ()
	Check the &origin= query parameter against the Origin: HTTP header and respond appropriately.
	logRequest ($time)
	Log the preceding request.
	printResult ($isError)
	Print results using the current printer.
	reportUnusedParams ()
	Report unused parameters, so the client gets a hint in case it gave us parameters we don't know, for example in case of spelling mistakes or a missing 'g' prefix for generators.
	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.
Static Protected Member Functions
static	matchOrigin ($value, $rules, $exceptions)
	Attempt to match an Origin header against a set of rules and a set of exceptions.
static	wildcardToRegex ($wildcard)
	Helper function to convert wildcard string into a regex '*' => '.
Private Attributes
	$mAction
	$mCacheControl = array()
	$mCacheMode = 'private'
	$mCanApiHighLimits = null
	$mEnableWrite
	$mInternalMode
	$mModuleMgr
	$mParamsUsed = array()
ApiFormatBase	$mPrinter
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
bool	$enableWrite	should be set to true if the api may modify data

Definition at line 149 of file ApiMain.php.

Member Function Documentation

ApiMain::addFormat	(	$	name,
		$	class
	)		`[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.

Deprecated:: since 1.21, Use getModuleManager()->addModule() instead.

Parameters:

string	$name	The identifier for this format.
	$class	ApiFormatBase The class implementing this format.

Definition at line 1268 of file ApiMain.php.

ApiMain::addModule	(	$	name,
		$	class
	)		`[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.

Deprecated:: since 1.21, Use getModuleManager()->addModule() instead.

Parameters:

string	$name	The identifier for this module.
	$class	ApiBase The class where this module is implemented.

Definition at line 1256 of file ApiMain.php.

ApiMain::canApiHighLimits ( )

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

Returns:: bool

Definition at line 1221 of file ApiMain.php.

ApiMain::checkExecutePermissions ( $ module ) [protected]

Check for sufficient permissions to execute.

Parameters:

$module ApiBase An Api module

Definition at line 758 of file ApiMain.php.

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

Check the max lag if necessary.

Parameters:

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

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

Definition at line 731 of file ApiMain.php.

ApiMain::createPrinterByName ( $ format )

Create an instance of an output formatter by its name.

Parameters:

$format string

Returns:: ApiFormatBase

Definition at line 334 of file ApiMain.php.

ApiMain::encodeRequestLogValue ( $ s ) [protected]

Encode a value in a format suitable for a space-separated log line.

Definition at line 875 of file ApiMain.php.

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 345 of file ApiMain.php.

ApiMain::executeAction ( ) [protected]

Execute the actual module, without any error handling.

Definition at line 811 of file ApiMain.php.

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 360 of file ApiMain.php.

ApiMain::getAllowedParams ( )

See ApiBase for description.

Returns:: array

Reimplemented from ApiBase.

Definition at line 989 of file ApiMain.php.

ApiMain::getCheck ( $ name )

Get a boolean request value, and register the fact that the parameter was used, for logging.

Definition at line 905 of file ApiMain.php.

ApiMain::getCredits ( ) [protected]

Returns an array of strings with credits for the API.

Returns:: array

Definition at line 1108 of file ApiMain.php.

ApiMain::getDescription ( )

See ApiBase for description.

Returns:: array

Reimplemented from ApiBase.

Definition at line 1052 of file ApiMain.php.

ApiMain::getFormats ( )

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

Since:: 1.18

Deprecated:: since 1.21, Use getModuleManager()'s methods instead.

Returns:: array

Definition at line 1288 of file ApiMain.php.

ApiMain::getModule ( )

Get the API module object.

Only works after executeAction()

Returns:: ApiBase

Definition at line 219 of file ApiMain.php.

ApiMain::getModuleManager ( )

Overrides to return this instance's module manager.

Returns:: ApiModuleManager

Reimplemented from ApiBase.

Definition at line 1243 of file ApiMain.php.

ApiMain::getModules ( )

Get the array mapping module names to class names.

Deprecated:: since 1.21, Use getModuleManager()'s methods instead.

Returns:: array

Definition at line 1277 of file ApiMain.php.

ApiMain::getParamDescription ( )

See ApiBase for description.

Returns:: array

Reimplemented from ApiBase.

Definition at line 1021 of file ApiMain.php.

ApiMain::getParamsUsed ( ) [protected]

Get the request parameters used in the course of the preceding execute() request.

Definition at line 889 of file ApiMain.php.

ApiMain::getPossibleErrors ( )

Returns:: array

Reimplemented from ApiBase.

Definition at line 1094 of file ApiMain.php.

ApiMain::getPrinter ( )

Get the result formatter object.

Only works after setupExecuteAction()

Returns:: ApiFormatBase

Definition at line 228 of file ApiMain.php.

ApiMain::getResult ( )

Get the ApiResult object associated with current request.

Returns:: ApiResult

Reimplemented from ApiBase.

Definition at line 210 of file ApiMain.php.

ApiMain::getShowVersions ( )

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

Returns:: bool

Deprecated:: since 1.21, always returns false

Definition at line 1234 of file ApiMain.php.

ApiMain::getUpload ( $ name )

Get a request upload, and register the fact that it was used, for logging.

Since:: 1.21

Parameters:

string $name Parameter name

Returns:: WebRequestUpload

Definition at line 917 of file ApiMain.php.

ApiMain::getVal	(	$	name,
		$	default = `null`
	)

Get a request value, and register the fact that it was used, for logging.

Definition at line 896 of file ApiMain.php.

ApiMain::handleCORS ( ) [protected]

Check the &origin= query parameter against the Origin: HTTP header and respond appropriately.

If no origin parameter is present, nothing happens. If an origin parameter is present but doesn't match the Origin header, a 403 status code is set and false is returned. 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.

Returns:: bool False if the caller should abort (403 case), true otherwise (all other cases)

Definition at line 440 of file ApiMain.php.

ApiMain::isInternalMode ( )

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

Returns:: bool

Definition at line 201 of file ApiMain.php.

ApiMain::isReadMode ( )

Returns:: bool

Reimplemented from ApiBase.

Definition at line 980 of file ApiMain.php.

ApiMain::logRequest ( $ time ) [protected]

Log the preceding request.

Parameters:

$time Time in seconds

Definition at line 847 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 1136 of file ApiMain.php.

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

Parameters:

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

Returns:: string

Definition at line 1206 of file ApiMain.php.

Referenced by ApiHelp\buildModuleHelp().

static ApiMain::matchOrigin	(	$	value,
		$	rules,
		$	exceptions
	)		`[static, protected]`

Attempt to match an Origin header against a set of rules and a set of exceptions.

Parameters:

string	$value	Origin header
array	$rules	Set of wildcard rules
array	$exceptions	Set of wildcard rules

Returns:: bool True if $value matches a rule in $rules and doesn't match any rules in $exceptions, false otherwise

Definition at line 482 of file ApiMain.php.

ApiMain::printResult ( $ isError ) [protected]

Print results using the current printer.

Parameters:

$isError bool

Definition at line 952 of file ApiMain.php.

ApiMain::reallyMakeHelpMsg ( )

Returns:: mixed|string

Definition at line 1158 of file ApiMain.php.

ApiMain::reportUnusedParams ( ) [protected]

Report unused parameters, so the client gets a hint in case it gave us parameters we don't know, for example in case of spelling mistakes or a missing 'g' prefix for generators.

Definition at line 926 of file ApiMain.php.

ApiMain::sendCacheHeaders ( ) [protected]

Definition at line 515 of file ApiMain.php.

References $name, $out, $response, $value, as, ContextSource\getOutput(), ApiBase\getParameter(), ContextSource\getRequest(), global, and wfTimestamp().

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 308 of file ApiMain.php.

ApiMain::setCacheMaxAge ( $ maxage )

Set how long the response should be cached.

Parameters:

$maxage

Definition at line 237 of file ApiMain.php.

ApiMain::setCacheMode ( $ mode )

Set the type of caching headers which will be sent.

Parameters:

string

$mode

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 269 of file ApiMain.php.

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 293 of file ApiMain.php.

ApiMain::setHelp ( $ help = true )

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

Parameters:

$help bool

Definition at line 1127 of file ApiMain.php.

ApiMain::setupExecuteAction ( ) [protected]

Set up for the execution.

Returns:: array

Definition at line 671 of file ApiMain.php.

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

Check POST for external response and setup result printer.

Parameters:

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

Definition at line 789 of file ApiMain.php.

ApiMain::setupModule ( ) [protected]

Set up the module for response.

Returns:: ApiBase The module that will handle this action

Definition at line 703 of file ApiMain.php.

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 322 of file ApiMain.php.

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 601 of file ApiMain.php.

static ApiMain::wildcardToRegex ( $ wildcard ) [static, protected]

Helper function to convert wildcard string into a regex '*' => '.

*?' '?' => '.'

Parameters:

string $wildcard String with wildcards

Returns:: string Regular expression

Definition at line 505 of file ApiMain.php.

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',
        'none' => 'ApiFormatNone',
    )

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

Definition at line 92 of file ApiMain.php.

ApiMain::$mAction [private]

Definition at line 135 of file ApiMain.php.

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

Definition at line 140 of file ApiMain.php.

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

Definition at line 139 of file ApiMain.php.

ApiMain::$mCanApiHighLimits = null [private]

Definition at line 1215 of file ApiMain.php.

ApiMain::$mEnableWrite [private]

Definition at line 136 of file ApiMain.php.

ApiMain::$mInternalMode [private]

Definition at line 137 of file ApiMain.php.

ApiMain::$mModule

Definition at line 137 of file ApiMain.php.

ApiMain::$mModuleMgr [private]

Definition at line 134 of file ApiMain.php.

ApiMain::$Modules [static, private]

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

Definition at line 51 of file ApiMain.php.

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

Definition at line 141 of file ApiMain.php.

ApiFormatBase ApiMain::$mPrinter [private]

Definition at line 132 of file ApiMain.php.

ApiMain::$mResult

Definition at line 134 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 119 of file ApiMain.php.

ApiMain::$mSquidMaxage

Definition at line 137 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.

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

Static Protected Member Functions

Private Attributes

Static Private Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation