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.
	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.
	getVal ($name, $default=null)
	Get a request value, and register the fact that it was used, for logging.
	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.
	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
	$mCacheControl = array()
	$mCacheMode = 'private'
	$mCanApiHighLimits = null
	$mInternalMode
	$mModules
	$mParamsUsed = array()
ApiFormatBase	$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 146 of file ApiMain.php.

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

ApiMain::canApiHighLimits ( )

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

Returns:: bool

Definition at line 1192 of file ApiMain.php.

ApiMain::checkExecutePermissions ( $ module ) [protected]

Check for sufficient permissions to execute.

Parameters:

$module ApiBase An Api module

Definition at line 756 of file ApiMain.php.

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

ApiMain::encodeRequestLogValue ( $ s ) [protected]

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

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

ApiMain::executeAction ( ) [protected]

Execute the actual module, without any error handling.

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

ApiMain::getAllowedParams ( )

See ApiBase for description.

Returns:: array

Reimplemented from ApiBase.

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

ApiMain::getCredits ( ) [protected]

Returns an array of strings with credits for the API.

Returns:: array

Definition at line 1079 of file ApiMain.php.

ApiMain::getDescription ( )

See ApiBase for description.

Returns:: array

Reimplemented from ApiBase.

Definition at line 1023 of file ApiMain.php.

ApiMain::getFormats ( )

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

Since:: 1.18

Returns:: array

Definition at line 1261 of file ApiMain.php.

ApiMain::getModule ( )

Get the API module object.

Only works after executeAction()

Returns:: ApiBase

Definition at line 218 of file ApiMain.php.

ApiMain::getModules ( )

Get the array mapping module names to class names.

Returns:: array

Definition at line 1251 of file ApiMain.php.

ApiMain::getParamDescription ( )

See ApiBase for description.

Returns:: array

Reimplemented from ApiBase.

Definition at line 992 of file ApiMain.php.

ApiMain::getParamsUsed ( ) [protected]

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

Definition at line 886 of file ApiMain.php.

ApiMain::getPossibleErrors ( )

Returns:: array

Reimplemented from ApiBase.

Definition at line 1065 of file ApiMain.php.

ApiMain::getPrinter ( )

Get the result formatter object.

Only works after setupExecuteAction()

Returns:: ApiFormatBase

Definition at line 227 of file ApiMain.php.

ApiMain::getResult ( )

Get the ApiResult object associated with current request.

Returns:: ApiResult

Reimplemented from ApiBase.

Definition at line 209 of file ApiMain.php.

ApiMain::getShowVersions ( )

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

Returns:: bool

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

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

ApiMain::isInternalMode ( )

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

Returns:: bool

Definition at line 200 of file ApiMain.php.

ApiMain::isReadMode ( )

Returns:: bool

Reimplemented from ApiBase.

Definition at line 950 of file ApiMain.php.

ApiMain::logRequest ( $ time ) [protected]

Log the preceding request.

Parameters:

$time Time in seconds

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

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 1177 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:

$value	string Origin header
$rules	array Set of wildcard rules
$exceptions	array 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 479 of file ApiMain.php.

ApiMain::printResult ( $ isError ) [protected]

Print results using the current printer.

Parameters:

$isError bool

Definition at line 927 of file ApiMain.php.

ApiMain::reallyMakeHelpMsg ( )

Returns:: mixed|string

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

ApiMain::sendCacheHeaders ( ) [protected]

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

ApiMain::setCacheMaxAge ( $ maxage )

Set how long the response should be cached.

Parameters:

$maxage

Definition at line 236 of file ApiMain.php.

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

ApiMain::setHelp ( $ help = true )

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

Parameters:

$help bool

Definition at line 1098 of file ApiMain.php.

ApiMain::setupExecuteAction ( ) [protected]

Set up for the execution.

Returns:: array

Definition at line 663 of file ApiMain.php.

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 787 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 696 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 321 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 598 of file ApiMain.php.

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

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

*?' '?' => '.'

Parameters:

$wildcard string String with wildcards

Returns:: string Regular expression

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

ApiMain::$mAction

Definition at line 133 of file ApiMain.php.

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

Definition at line 137 of file ApiMain.php.

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

Definition at line 136 of file ApiMain.php.

ApiMain::$mCanApiHighLimits = null [private]

Definition at line 1186 of file ApiMain.php.

ApiMain::$mEnableWrite

Definition at line 133 of file ApiMain.php.

ApiMain::$mFormatNames

Definition at line 132 of file ApiMain.php.

ApiMain::$mFormats

Definition at line 132 of file ApiMain.php.

ApiMain::$mInternalMode [private]

Definition at line 134 of file ApiMain.php.

ApiMain::$mModule

Definition at line 134 of file ApiMain.php.

ApiMain::$mModuleNames

Definition at line 132 of file ApiMain.php.

ApiMain::$mModules [private]

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

ApiFormatBase ApiMain::$mPrinter [private]

Definition at line 130 of file ApiMain.php.

ApiMain::$mResult [private]

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

ApiMain::$mShowVersions

Definition at line 133 of file ApiMain.php.

ApiMain::$mSquidMaxage

Definition at line 134 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