BlueSpice MediaWiki REL1_27
 All Classes Namespaces Files Functions Variables Groups Pages
ApiMain Class Reference
Inheritance diagram for ApiMain:
Collaboration diagram for ApiMain:

Public Member Functions

 __construct ($context=null, $enableWrite=false)
 
 isInternalMode ()
 
 getResult ()
 
 lacksSameOriginSecurity ()
 
 getErrorFormatter ()
 
 getContinuationManager ()
 
 setContinuationManager ($manager)
 
 getModule ()
 
 getPrinter ()
 
 setCacheMaxAge ($maxage)
 
 setCacheMode ($mode)
 
 setCacheControl ($directives)
 
 createPrinterByName ($format)
 
 execute ()
 
 markParamsUsed ($params)
 
 markParamsSensitive ($params)
 
 getVal ($name, $default=null)
 
 getCheck ($name)
 
 getUpload ($name)
 
 isReadMode ()
 
 getAllowedParams ()
 
 modifyHelp (array &$help, array $options, array &$tocData)
 
 canApiHighLimits ()
 
 getModuleManager ()
 
 getUserAgent ()
 
- Public Member Functions inherited from ApiBase
 __construct (ApiMain $mainModule, $moduleName, $modulePrefix= '')
 
 execute ()
 
 getModuleManager ()
 
 getCustomPrinter ()
 
 getHelpUrls ()
 
 shouldCheckMaxlag ()
 
 isReadMode ()
 
 isWriteMode ()
 
 mustBePosted ()
 
 isDeprecated ()
 
 isInternal ()
 
 needsToken ()
 
 getConditionalRequestData ($condition)
 
 getModuleName ()
 
 getModulePrefix ()
 
 getMain ()
 
 isMain ()
 
 getParent ()
 
 lacksSameOriginSecurity ()
 
 getModulePath ()
 
 getModuleFromPath ($path)
 
 getResult ()
 
 getErrorFormatter ()
 
 getContinuationManager ()
 
 setContinuationManager ($manager)
 
 dynamicParameterDocumentation ()
 
 encodeParamName ($paramName)
 
 extractRequestParams ($parseLimit=true)
 
 requireOnlyOneParameter ($params, $required)
 
 requireMaxOneParameter ($params, $required)
 
 requireAtLeastOneParameter ($params, $required)
 
 requirePostedParameters ($params, $prefix= 'prefix')
 
 getTitleOrPageId ($params, $load=false)
 
 validateToken ($token, array $params)
 
 getWatchlistUser ($params)
 
 setWarning ($warning)
 
 dieUsage ($description, $errorCode, $httpRespCode=0, $extradata=null)
 
 dieBlocked (Block $block)
 
 getErrorFromStatus ($status, &$extraData=null)
 
 dieStatus ($status)
 
static dieReadOnly ()
 
 dieUsageMsg ($error)
 
 dieUsageMsgOrDebug ($error)
 
 parseMsg ($error)
 
 logFeatureUsage ($feature)
 
 getFinalDescription ()
 
 getFinalParams ($flags=0)
 
 getFinalParamDescription ()
 
 modifyHelp (array &$help, array $options, array &$tocData)
 
 makeHelpMsg ()
 
 makeHelpMsgParameters ()
 
 getModuleProfileName ($db=false)
 
 profileIn ()
 
 profileOut ()
 
 safeProfileOut ()
 
 getProfileTime ()
 
 profileDBIn ()
 
 profileDBOut ()
 
 getProfileDBTime ()
 
 getResultData ()
 
- Public Member Functions inherited from ContextSource
 getContext ()
 
 setContext (IContextSource $context)
 
 getConfig ()
 
 getRequest ()
 
 getTitle ()
 
 canUseWikiPage ()
 
 getWikiPage ()
 
 getOutput ()
 
 getUser ()
 
 getLanguage ()
 
 getSkin ()
 
 getTiming ()
 
 getStats ()
 
 msg ()
 
 exportSession ()
 

Static Public Member Functions

static handleApiBeforeMainException (Exception $e)
 
- Static Public Member Functions inherited from ApiBase
static truncateArray (&$arr, $limit)
 
static makeMessage ($msg, IContextSource $context, array $params=null)
 

Public Attributes

const API_DEFAULT_FORMAT = 'jsonfm'
 
 $mResult
 
 $mErrorFormatter
 
 $mContinuationManager
 
 $mSquidMaxage
 
 $mModule
 
- Public Attributes inherited from ApiBase
const LIMIT_BIG1 = 500
 
const LIMIT_BIG2 = 5000
 
const LIMIT_SML1 = 50
 
const LIMIT_SML2 = 500
 
const GET_VALUES_FOR_HELP = 1
 
 $mModulePrefix
 
const PARAM_DFLT = 0
 
const PARAM_ISMULTI = 1
 
const PARAM_TYPE = 2
 
const PARAM_MAX = 3
 
const PARAM_MAX2 = 4
 
const PARAM_MIN = 5
 
const PARAM_ALLOW_DUPLICATES = 6
 
const PARAM_DEPRECATED = 7
 
const PARAM_REQUIRED = 8
 
const PARAM_RANGE_ENFORCE = 9
 
const PARAM_HELP_MSG = 10
 
const PARAM_HELP_MSG_APPEND = 11
 
const PARAM_HELP_MSG_INFO = 12
 
const PARAM_VALUE_LINKS = 13
 
const PARAM_HELP_MSG_PER_VALUE = 14
 
const PARAM_SUBMODULE_MAP = 15
 
const PARAM_SUBMODULE_PARAM_PREFIX = 16
 
const PARAM_SENSITIVE = 17
 

Protected Member Functions

 executeActionWithErrorHandling ()
 
 handleException (Exception $e)
 
 handleCORS ()
 
 sendCacheHeaders ($isError)
 
 errorMessageFromException ($e)
 
 substituteResultWithError ($e)
 
 setupExecuteAction ()
 
 setupModule ()
 
 checkMaxLag ($module, $params)
 
 checkConditionalRequestHeaders ($module)
 
 checkExecutePermissions ($module)
 
 checkReadOnly ($module)
 
 checkAsserts ($params)
 
 setupExternalResponse ($module, $params)
 
 executeAction ()
 
 setRequestExpectations (ApiBase $module)
 
 logRequest ($time, $e=null)
 
 encodeRequestLogValue ($s)
 
 getParamsUsed ()
 
 getSensitiveParams ()
 
 reportUnusedParams ()
 
 printResult ($isError)
 
 getExamplesMessages ()
 
- Protected Member Functions inherited from ApiBase
 getExamplesMessages ()
 
 getAllowedParams ()
 
 getWebUITokenSalt (array $params)
 
 getDB ()
 
 getParameter ($paramName, $parseLimit=true)
 
 getWatchlistValue ($watchlist, $titleObj, $userOption=null)
 
 getParameterFromSettings ($paramName, $paramSettings, $parseLimit)
 
 parseMultiValue ($valueName, $value, $allowMultiple, $allowedValues)
 
 validateLimit ($paramName, &$value, $min, $max, $botMax=null, $enforceLimits=false)
 
 validateTimestamp ($value, $encParamName)
 
 setWatch ($watch, $titleObj, $userOption=null)
 
 dieContinueUsageIf ($condition)
 
 getDescriptionMessage ()
 
 getHelpFlags ()
 
 getModuleSourceInfo ()
 
 getDescription ()
 
 getParamDescription ()
 
 getExamples ()
 
 makeHelpArrayToString ($prefix, $title, $input)
 
 useTransactionalTimeLimit ()
 

Static Protected Member Functions

static matchOrigin ($value, $rules, $exceptions)
 
static matchRequestedHeaders ($requestedHeaders)
 
static wildcardToRegex ($wildcard)
 
- Static Protected Member Functions inherited from ApiBase
static dieDebug ($method, $message)
 

Deprecated

 setHelp ($help=true)
 
 makeHelpMsg ()
 
 reallyMakeHelpMsg ()
 
static makeHelpMsgHeader ($module, $paramName)
 

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.

Constructor & Destructor Documentation

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

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

Parameters
IContextSource | WebRequest$contextIf this is an instance of FauxRequest, errors are thrown and no printing occurs
bool$enableWriteShould be set to true if the api may modify data

Member Function Documentation

ApiMain::canApiHighLimits ( )

Check whether the current user is allowed to use high limits

Returns
bool
ApiMain::checkAsserts (   $params)
protected

Check asserts of the user's rights

Parameters
array$params
ApiMain::checkConditionalRequestHeaders (   $module)
protected

Check selected RFC 7232 precondition headers

RFC 7232 envisions a particular model where you send your request to "a resource", and for write requests that you can read "the resource" by changing the method to GET. When the API receives a GET request, it works out even though "the resource" from RFC 7232's perspective might be many resources from MediaWiki's perspective. But it totally fails for a POST, since what HTTP sees as "the resource" is probably just "/api.php" with all the interesting bits in the body.

Therefore, we only support RFC 7232 precondition headers for GET (and HEAD). That means we don't need to bother with If-Match and If-Unmodified-Since since they only apply to modification requests.

And since we don't support Range, If-Range is ignored too.

Since
1.26
Parameters
ApiBase$moduleApi module being used
Returns
bool True on success, false should exit immediately
ApiMain::checkExecutePermissions (   $module)
protected

Check for sufficient permissions to execute

Parameters
ApiBase$moduleAn Api module
ApiMain::checkMaxLag (   $module,
  $params 
)
protected

Check the max lag if necessary

Parameters
ApiBase$moduleApi module being used
array$paramsArray an array containing the request parameters.
Returns
bool True on success, false should exit immediately
ApiMain::checkReadOnly (   $module)
protected

Check if the DB is read-only for this user

Parameters
ApiBase$moduleAn Api module
ApiMain::createPrinterByName (   $format)

Create an instance of an output formatter by its name

Parameters
string$format
Returns
ApiFormatBase
ApiMain::encodeRequestLogValue (   $s)
protected

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

Parameters
string$s
Returns
string
ApiMain::errorMessageFromException (   $e)
protected

Create an error message for the given exception.

If the exception is a UsageException then UsageException::getMessageArray() will be called to create the message.

Parameters
Exception$e
Returns
array ['code' => 'some string', 'info' => 'some other string']
Since
1.27
ApiMain::execute ( )

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

ApiMain::executeAction ( )
protected

Execute the actual module, without any error handling

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.

ApiMain::getAllowedParams ( )

See ApiBase for description.

Returns
array
ApiMain::getCheck (   $name)

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

Parameters
string$name
Returns
bool
ApiMain::getContinuationManager ( )

Get the continuation manager

Returns
ApiContinuationManager|null
ApiMain::getErrorFormatter ( )

Get the ApiErrorFormatter object associated with current request

Returns
ApiErrorFormatter
ApiMain::getExamplesMessages ( )
protected
ApiMain::getModule ( )

Get the API module object. Only works after executeAction()

Returns
ApiBase
ApiMain::getModuleManager ( )

Overrides to return this instance's module manager.

Returns
ApiModuleManager
ApiMain::getParamsUsed ( )
protected

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

Returns
array
ApiMain::getPrinter ( )

Get the result formatter object. Only works after setupExecuteAction()

Returns
ApiFormatBase
ApiMain::getResult ( )

Get the ApiResult object associated with current request

Returns
ApiResult
ApiMain::getSensitiveParams ( )
protected

Get the request parameters that should be considered sensitive

Since
1.28
Returns
array
ApiMain::getUpload (   $name)

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

Since
1.21
Parameters
string$nameParameter name
Returns
WebRequestUpload
ApiMain::getUserAgent ( )

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).

Returns
string
ApiMain::getVal (   $name,
  $default = null 
)

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

Parameters
string$name
mixed$default
Returns
mixed
static ApiMain::handleApiBeforeMainException ( Exception  $e)
static

Handle an exception from the ApiBeforeMain hook.

This tries to print the exception as an API response, to be more friendly to clients. If it fails, it will rethrow the exception.

Since
1.23
Parameters
Exception$e
Exceptions
Exception
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. http://www.w3.org/TR/cors/#resource-requests http://www.w3.org/TR/cors/#resource-preflight-requests

Returns
bool False if the caller should abort (403 case), true otherwise (all other cases)
ApiMain::handleException ( Exception  $e)
protected

Handle an exception as an API response

Since
1.23
Parameters
Exception$e
ApiMain::isInternalMode ( )

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

Returns
bool
ApiMain::isReadMode ( )
Returns
bool
ApiMain::lacksSameOriginSecurity ( )

Get the security flag for the current request

Returns
bool
ApiMain::logRequest (   $time,
  $e = null 
)
protected

Log the preceding request

Parameters
float$timeTime in seconds
Exception$eException caught while processing the request
ApiMain::makeHelpMsg ( )

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

Deprecated:
since 1.25
Returns
string
static ApiMain::makeHelpMsgHeader (   $module,
  $paramName 
)
static
Deprecated:
since 1.25
Parameters
ApiBase$module
string$paramNameWhat type of request is this? e.g. action, query, list, prop, meta, format
Returns
string
ApiMain::markParamsSensitive (   $params)

Mark parameters as sensitive

Since
1.28
Parameters
string|string[]$params
ApiMain::markParamsUsed (   $params)

Mark parameters as used

Parameters
string|string[]$params
static ApiMain::matchOrigin (   $value,
  $rules,
  $exceptions 
)
staticprotected

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

Parameters
string$valueOrigin header
array$rulesSet of wildcard rules
array$exceptionsSet of wildcard rules
Returns
bool True if $value matches a rule in $rules and doesn't match any rules in $exceptions, false otherwise
static ApiMain::matchRequestedHeaders (   $requestedHeaders)
staticprotected

Attempt to validate the value of Access-Control-Request-Headers against a list of headers that we allow the follow up request to send.

Parameters
string$requestedHeadersComma seperated list of HTTP headers
Returns
bool True if all requested headers are in the list of allowed headers
ApiMain::printResult (   $isError)
protected

Print results using the current printer

Parameters
bool$isError
ApiMain::reallyMakeHelpMsg ( )
Deprecated:
since 1.25
Returns
mixed|string
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.

ApiMain::sendCacheHeaders (   $isError)
protected

Send caching headers

Parameters
bool$isErrorWhether an error response is being output
Since
1.26 added $isError parameter
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
array$directives
ApiMain::setCacheMaxAge (   $maxage)

Set how long the response should be cached.

Parameters
int$maxage
ApiMain::setCacheMode (   $mode)

Set the type of caching headers which will be sent.

Parameters
string$modeOne 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.

ApiMain::setContinuationManager (   $manager)

Set the continuation manager

Parameters
ApiContinuationManager|null
ApiMain::setHelp (   $help = true)

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

Deprecated:
since 1.25
Parameters
bool$help
ApiMain::setRequestExpectations ( ApiBase  $module)
protected

Set database connection, query, and write expectations given this module request

Parameters
ApiBase$module
ApiMain::setupExecuteAction ( )
protected

Set up for the execution.

Returns
array
ApiMain::setupExternalResponse (   $module,
  $params 
)
protected

Check POST for external response and setup result printer

Parameters
ApiBase$moduleAn Api module
array$paramsAn array with the request parameters
ApiMain::setupModule ( )
protected

Set up the module for response

Returns
ApiBase The module that will handle this action
Exceptions
MWException
UsageException
ApiMain::substituteResultWithError (   $e)
protected

Replace the result data with the information about an exception. Returns the error code

Parameters
Exception$e
Returns
string
static ApiMain::wildcardToRegex (   $wildcard)
staticprotected

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

Parameters
string$wildcardString with wildcards
Returns
string Regular expression

Member Data Documentation

const ApiMain::API_DEFAULT_FORMAT = 'jsonfm'

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


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