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

Inherited by MediaWiki\Rest\Module\MatcherBasedModule.

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

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

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

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

	getPathPrefix ()

	getRouter ()

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

	setCors (CorsUtils $cors)

	setStats (StatsFactory $stats)

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 36 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,
		HookContainer	$hookContainer )

Parameters

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

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

◆ executeHandler()

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

protected

Execute a fully-constructed handler.

Exceptions

HttpException

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

◆ 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 142 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.0.json#/definitions/Module

See also: /docs/discovery-1.0.json; /docs/mwapi-1.1.json; DiscoveryHandler

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

◆ getPathPrefix()

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

Definition at line 87 of file Module.php.

◆ getRouter()

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

Definition at line 198 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 437 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 521 of file Module.php.

◆ setCors()

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

Definition at line 488 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 501 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 241 of file Module.php.

Member Data Documentation

◆ $pathPrefix

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

protected

Definition at line 44 of file Module.php.

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

◆ $responseFactory

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

protected

Definition at line 45 of file Module.php.

Referenced by MediaWiki\Rest\Module\ExtraRoutesModule\__construct(), MediaWiki\Rest\Module\Module\__construct(), and MediaWiki\Rest\Module\SpecBasedModule\__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 41 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()

◆ getModuleDescription()

◆ getOpenApiInfo()

◆ getPathPrefix()

◆ getRouter()

◆ initFromCacheData()

◆ instantiateHandlerObject()

◆ loadJsonFile()

◆ setCors()

◆ setStats()

◆ throwNoMatch()

Member Data Documentation

◆ $pathPrefix

◆ $responseFactory

◆ CACHE_CONFIG_HASH_KEY