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

Inherited by MediaWiki\Rest\Module\RouteFileModule.

Collaboration diagram for MediaWiki\Rest\Module\Module:

Public Member Functions
	__construct (Router $router, string $pathPrefix, ResponseFactory $responseFactory, BasicAuthorizerInterface $basicAuth, ObjectFactory $objectFactory, Validator $restValidator, ErrorReporter $errorReporter)

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

	getHandlerForPath (string $path, RequestInterface $request, bool $initForExecute=false)
	Create a Handler for the given path, taking into account the request method.

	getPathPrefix ()

	getRouter ()

	initFromCacheData (array $cacheData)
	Initialize from the given cache data if possible.

	setCors (CorsUtils $cors)

Static Public Member Functions
static	loadJsonFile (string $fileName)
	Loads a module specification from a file.

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.

Protected Attributes
string	$pathPrefix

ResponseFactory	$responseFactory

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 32 of file Module.php.

Constructor & Destructor Documentation

◆ __construct()

MediaWiki\Rest\Module\Module::__construct	(	Router	$router,
		string	$pathPrefix,
		ResponseFactory	$responseFactory,
		BasicAuthorizerInterface	$basicAuth,
		ObjectFactory	$objectFactory,
		Validator	$restValidator,
		ErrorReporter	$errorReporter )

Parameters

Router	$router
string	$pathPrefix
ResponseFactory	$responseFactory
BasicAuthorizerInterface	$basicAuth
ObjectFactory	$objectFactory
Validator	$restValidator
ErrorReporter	$errorReporter

Definition at line 58 of file Module.php.

References MediaWiki\Rest\Module\Module\$pathPrefix, and MediaWiki\Rest\Module\Module\$responseFactory.

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 253 of file Module.php.

References $path.

◆ executeHandler()

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

protected

Execute a fully-constructed handler.

Exceptions

HttpException

Definition at line 306 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 instantiateHandlerObject()
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 returned in the Allow header of a 405 response and included in CORS pre-flight.

Reimplemented in MediaWiki\Rest\Module\RouteFileModule.

◆ 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\RouteFileModule.

◆ 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\RouteFileModule.

◆ 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\RouteFileModule.

◆ 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 131 of file Module.php.

◆ getPathPrefix()

MediaWiki\Rest\Module\Module::getPathPrefix ( )

Definition at line 76 of file Module.php.

◆ getRouter()

MediaWiki\Rest\Module\Module::getRouter ( )

Definition at line 180 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\RouteFileModule.

◆ instantiateHandlerObject()

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

protected

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

Definition at line 292 of file Module.php.

◆ loadJsonFile()

static MediaWiki\Rest\Module\Module::loadJsonFile ( string $fileName )

static

Loads a module specification from a file.

This method does not know or care about the structure of the file other than that it must be JSON and contain a list or map (that is, a JSON array or object).

Parameters

string $fileName

Access: internal

Returns: array An associative or indexed array describing the module

Exceptions

ModuleConfigurationException

Definition at line 364 of file Module.php.

◆ setCors()

MediaWiki\Rest\Module\Module::setCors ( CorsUtils $cors )

Parameters

CorsUtils $cors

Returns: self

Definition at line 344 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 223 of file Module.php.

Member Data Documentation

◆ $pathPrefix

string MediaWiki\Rest\Module\Module::$pathPrefix

protected

Definition at line 39 of file Module.php.

Referenced by MediaWiki\Rest\Module\RouteFileModule\__construct(), and MediaWiki\Rest\Module\Module\__construct().

◆ $responseFactory

ResponseFactory MediaWiki\Rest\Module\Module::$responseFactory

protected

Definition at line 40 of file Module.php.

Referenced by MediaWiki\Rest\Module\RouteFileModule\__construct(), and MediaWiki\Rest\Module\Module\__construct().

◆ 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 37 of file Module.php.

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

includes/Rest/Module/Module.php

Public Member Functions

Static Public Member Functions

Public Attributes

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ __construct()

Member Function Documentation

◆ execute()

◆ executeHandler()

◆ findHandlerMatch()

◆ getAllowedMethods()

◆ getCacheData()

◆ getDefinedPaths()

◆ getHandlerForPath()

◆ getPathPrefix()

◆ getRouter()

◆ initFromCacheData()

◆ instantiateHandlerObject()

◆ loadJsonFile()

◆ setCors()

◆ throwNoMatch()

Member Data Documentation

◆ $pathPrefix

◆ $responseFactory

◆ CACHE_CONFIG_HASH_KEY