MediaWiki\Rest\Module\Module Class Reference

A REST module represents a collection of endpoints. More...

Inherited by MediaWiki\Rest\Module\MatcherBasedModule.

Public Member Functions
	__construct (private readonly Router $router, protected readonly string $pathPrefix, protected readonly JsonLocalizer $jsonLocalizer, private readonly BasicAuthorizerInterface $basicAuth, private readonly ObjectFactory $objectFactory, private readonly Validator $restValidator, private readonly ErrorReporter $errorReporter, HookContainer $hookContainer,)
	execute (string $path, RequestInterface $request)
	Find the handler for a request and execute it.
	getAllowedMethods (string $relPath)
	Get the allowed methods for a path.
	getCacheData ()
	Return data that can later be used to initialize a new instance of this module in a fast and efficient way.
	getDefinedPaths ()
	getDeprecatedDate ()
	Return the timestamp at which this was or will be deprecated, or null if none.
	getHandlerForPath (string $path, RequestInterface $request, bool $initForExecute=false)
	Create a Handler for the given path, taking into account the request method.
	getJsonLocalizer ()
	getModuleDescription ()
	Returns fields to be included when describing this module in the discovery document.
	getOpenApiExternalDocs ()
	Return an array with data to be included as the root-level OpenAPI "externalDocs" object describing this module's external documentation.
	getOpenApiInfo ()
	Return an array with data to be included in an OpenAPI "info" object describing this module.
	getOpenApiTags ()
	Return an array with data to be included in an OpenAPI "tags" object describing this module's tags.
	getPathPrefix ()
	getRouter ()
	initForExecute (ResponseFactory $responseFactory)
	Initialize this module for handling requests via execute().
	initFromCacheData (array $cacheData)
	Initialize from the given cache data if possible.
	setCors (CorsUtils $cors)
	setStats (StatsFactory $stats)

Public Attributes
const	CACHE_CONFIG_HASH_KEY = 'CONFIG-HASH'

Protected Member Functions
	executeHandler (Handler $handler)
	Execute a fully-constructed handler.
	findHandlerMatch (string $path, string $requestMethod)
	Determines which handler to use for the given path and returns an array describing the handler and initialization context.
	instantiateHandlerObject (array $spec)
	Creates a handler from the given spec, but does not initialize it.
	throwNoMatch (string $path, string $method, array $allowed)
	Implementations of getHandlerForPath() should call this method when they cannot handle the requested path.

Detailed Description

A REST module represents a collection of endpoints.

The module object is responsible for generating a response for a given request. This is typically done by routing requests to the appropriate request handler.

Since

1.43

Definition at line 42 of file Module.php.

Constructor & Destructor Documentation

__construct()

MediaWiki\Rest\Module\Module::__construct	(	private readonly Router	$router,
		protected readonly string	$pathPrefix,
		protected readonly JsonLocalizer	$jsonLocalizer,
		private readonly BasicAuthorizerInterface	$basicAuth,
		private readonly ObjectFactory	$objectFactory,
		private readonly Validator	$restValidator,
		private readonly ErrorReporter	$errorReporter,
		HookContainer	$hookContainer )

Definition at line 59 of file Module.php.

Member Function Documentation

execute()

MediaWiki\Rest\Module\Module::execute	(	string	$path,
		RequestInterface	$request )

Find the handler for a request and execute it.

Definition at line 307 of file Module.php.

executeHandler()

MediaWiki\Rest\Module\Module::executeHandler ( Handler $handler )

protected

Execute a fully-constructed handler.

Exceptions

HttpException

Definition at line 502 of file Module.php.

findHandlerMatch()

MediaWiki\Rest\Module\Module::findHandlerMatch ( string $path, string $requestMethod )

abstractprotected

Determines which handler to use for the given path and returns an array describing the handler and initialization context.

Parameters

string	$path
string	$requestMethod

Returns

array<string,mixed>

• bool "found": Whether a match was found. If true, the handler or spec field must be set.
• Handler handler: the Handler object to use. Either "handler" or "spec" must be given.
• array "spec":" an object spec for use with ObjectFactory - array "config": the route config, to be passed to Handler::initContext() - string "path": the path the handler is responsible for, including placeholders for path parameters. - string[] "params": path parameters, to be passed the Request::setPathPrams() - string[] "methods": supported methods, if the path is known but the method did not match. Only meaningful if "found" is false. To be used in the Allow header of a 405 response and included in CORS pre-flight.

Reimplemented in MediaWiki\Rest\Module\MatcherBasedModule.

getAllowedMethods()

MediaWiki\Rest\Module\Module::getAllowedMethods ( string $relPath )

abstract

Get the allowed methods for a path.

Useful to check for 405 wrong method and for generating OpenAPI specs.

Parameters

string

$relPath

A concrete request path.

Returns

string[] A list of allowed HTTP request methods for the path. If the path is not supported, the list will be empty.

Reimplemented in MediaWiki\Rest\Module\MatcherBasedModule.

getCacheData()

MediaWiki\Rest\Module\Module::getCacheData ( )

abstract

Return data that can later be used to initialize a new instance of this module in a fast and efficient way.

See also

initFromCacheData()

Returns

array An associative array suitable to be processed by initFromCacheData. Implementations are free to choose the format.

Reimplemented in MediaWiki\Rest\Module\MatcherBasedModule.

getDefinedPaths()

MediaWiki\Rest\Module\Module::getDefinedPaths ( )

abstract

Access: internal

for testing

Returns

array[] An associative array, mapping path patterns to a list of request methods supported for the path.

Reimplemented in MediaWiki\Rest\Module\ExtraRoutesModule, and MediaWiki\Rest\Module\SpecBasedModule.

getDeprecatedDate()

MediaWiki\Rest\Module\Module::getDeprecatedDate

(

)

Return the timestamp at which this was or will be deprecated, or null if none.

See also

Handler::getDeprecatedDate()

Since

1.47

Reimplemented in MediaWiki\Rest\Module\ExtraRoutesModule.

Definition at line 603 of file Module.php.

getHandlerForPath()

MediaWiki\Rest\Module\Module::getHandlerForPath	(	string	$path,
		RequestInterface	$request,
		bool	$initForExecute = false )

Create a Handler for the given path, taking into account the request method.

If $prepExecution is true, the handler's prepareForExecute() method will be called, which will call postInitSetup(). The $request object will be updated with any path parameters and parsed body data.

Stability: unstable

Parameters

string	$path
RequestInterface	$request	The request to handle. If $forExecution is true, this will be updated with the path parameters and parsed body data as appropriate.
bool	$initForExecute	Whether the handler and the request should be prepared for execution. Callers that only need the Handler object for access to meta-data should set this to false.

Returns

Handler

Exceptions

HttpException

If no handler was found

Definition at line 144 of file Module.php.

getJsonLocalizer()

MediaWiki\Rest\Module\Module::getJsonLocalizer

(

)

Since

1.47

Definition at line 76 of file Module.php.

getModuleDescription()

MediaWiki\Rest\Module\Module::getModuleDescription

(

)

Returns fields to be included when describing this module in the discovery document.

Supported keys are described in /docs/discovery-1.1.json#/definitions/Module

See also

/docs/discovery-1.1.json

/docs/mwapi-1.2.json

DiscoveryHandler

Definition at line 617 of file Module.php.

getOpenApiExternalDocs()

MediaWiki\Rest\Module\Module::getOpenApiExternalDocs

(

)

Return an array with data to be included as the root-level OpenAPI "externalDocs" object describing this module's external documentation.

See also

https://spec.openapis.org/oas/v3.0.0#external-documentation-object

Since

1.47

Returns

array

Reimplemented in MediaWiki\Rest\Module\ExtraRoutesModule, and MediaWiki\Rest\Module\SpecBasedModule.

Definition at line 577 of file Module.php.

getOpenApiInfo()

MediaWiki\Rest\Module\Module::getOpenApiInfo

(

)

Return an array with data to be included in an OpenAPI "info" object describing this module.

See also

https://spec.openapis.org/oas/v3.0.0#info-object

Returns

array

Reimplemented in MediaWiki\Rest\Module\ExtraRoutesModule, and MediaWiki\Rest\Module\SpecBasedModule.

Definition at line 565 of file Module.php.

getOpenApiTags()

MediaWiki\Rest\Module\Module::getOpenApiTags

(

)

Return an array with data to be included in an OpenAPI "tags" object describing this module's tags.

Each tag should be an associative array with 'name' and 'description' keys. Example: [ [ 'name' => 'pages', 'description' => 'Page operations' ] ]

See also

https://spec.openapis.org/oas/v3.0.0#tag-object

Since

1.47

Returns

array[]

Reimplemented in MediaWiki\Rest\Module\SpecBasedModule.

Definition at line 593 of file Module.php.

getPathPrefix()

MediaWiki\Rest\Module\Module::getPathPrefix

(

)

Definition at line 80 of file Module.php.

getRouter()

MediaWiki\Rest\Module\Module::getRouter

(

)

Definition at line 212 of file Module.php.

initForExecute()

MediaWiki\Rest\Module\Module::initForExecute

(

ResponseFactory

$responseFactory

)

Initialize this module for handling requests via execute().

Access: internal

Definition at line 119 of file Module.php.

initFromCacheData()

MediaWiki\Rest\Module\Module::initFromCacheData ( array $cacheData )

abstract

Initialize from the given cache data if possible.

This allows fast initialization based on data that was cached during a previous invocation of the module.

Implementations are responsible for verifying that the cache data matches the information provided to the constructor, to protect against a situation where configuration was updated in a way that affects the operation of the module.

Parameters

array

$cacheData

Data generated by getCacheData(), implementations are free to choose the format.

Returns

bool true if the cache data could be used, false if it was discarded.

See also

getCacheData()

Reimplemented in MediaWiki\Rest\Module\MatcherBasedModule.

instantiateHandlerObject()

MediaWiki\Rest\Module\Module::instantiateHandlerObject ( array $spec )

protected

Creates a handler from the given spec, but does not initialize it.

Definition at line 452 of file Module.php.

setCors()

MediaWiki\Rest\Module\Module::setCors

(

CorsUtils

$cors

)

Definition at line 539 of file Module.php.

setStats()

MediaWiki\Rest\Module\Module::setStats

(

StatsFactory

$stats

)

Access: internal

for use by Router

Parameters

StatsFactory

$stats

Returns

self

Definition at line 552 of file Module.php.

throwNoMatch()

MediaWiki\Rest\Module\Module::throwNoMatch ( string $path, string $method, array $allowed )

protected

Implementations of getHandlerForPath() should call this method when they cannot handle the requested path.

Parameters

string	$path	The requested path
string	$method	The HTTP method of the current request
string[]	$allowed	The allowed HTTP methods allowed by the path

Returns

never

Exceptions

HttpException

Definition at line 255 of file Module.php.

Member Data Documentation

CACHE_CONFIG_HASH_KEY

const MediaWiki\Rest\Module\Module::CACHE_CONFIG_HASH_KEY = 'CONFIG-HASH'

Access: internal

for use in cached module data

Definition at line 48 of file Module.php.

---

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

• includes/Rest/Module/Module.php