MatcherBasedModules respond to requests by matching the requested path against a list of known routes to identify the appropriate handler. More...

Inherits MediaWiki\Rest\Module\Module.

Inherited by MediaWiki\Rest\Module\ExtraRoutesModule, and MediaWiki\Rest\Module\SpecBasedModule.

Collaboration diagram for MediaWiki\Rest\Module\MatcherBasedModule:

[legend]

Public Member Functions

findHandlerMatch (string $path, string $requestMethod)

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.

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.

initFromCacheData (array $cacheData)

Initialize from the given cache data if possible.

Public Member Functions inherited from MediaWiki\Rest\Module\Module

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

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

setCors (CorsUtils $cors)

setStats (StatsFactory $stats)

Protected Member Functions
	addRoute ( $method, string $path, array $info)

	getConfigHash ()
	Get a config version hash for cache invalidation.

	getMatchers ()
	Get an array of PathMatcher objects indexed by HTTP method.

	initRoutes ()
	Initialize matchers by calling addRoute() for each known route.

Protected Member Functions inherited from MediaWiki\Rest\Module\Module
	executeHandler (Handler $handler)
	Execute a fully-constructed handler.

	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.

Additional Inherited Members
Static Public Member Functions inherited from MediaWiki\Rest\Module\Module
static	loadJsonFile (string $fileName)
	Loads a module specification from a file.

Public Attributes inherited from MediaWiki\Rest\Module\Module
const	CACHE_CONFIG_HASH_KEY = 'CONFIG-HASH'

Protected Attributes inherited from MediaWiki\Rest\Module\Module
string	$pathPrefix

ResponseFactory	$responseFactory

Detailed Description

MatcherBasedModules respond to requests by matching the requested path against a list of known routes to identify the appropriate handler.

See also: Matcher

Since: 1.43

Definition at line 16 of file MatcherBasedModule.php.

Member Function Documentation

◆ addRoute()

MediaWiki\Rest\Module\MatcherBasedModule::addRoute	(		$method,
		string	$path,
		array	$info )

protected

Parameters

string \| string[]	$method	The method(s) the route should be registered for
string	$path	The path pattern for the route
array	$info	Information to be associated with the route. Supported keys: "spec": an object spec for use with ObjectFactory for constructing a Handler object. "config": an array of configuration valies to be passed to Handler::initContext.

Definition at line 83 of file MatcherBasedModule.php.

References $path, and MediaWiki\Rest\PathTemplateMatcher\PathMatcher\add().

◆ findHandlerMatch()

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

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 from MediaWiki\Rest\Module\Module.

Definition at line 107 of file MatcherBasedModule.php.

◆ getAllowedMethods()

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

Get the allowed methods for a path.

Useful to check for 405 wrong method.

Parameters

string $relPath A concrete request path.

Returns: string[]

Reimplemented from MediaWiki\Rest\Module\Module.

Definition at line 140 of file MatcherBasedModule.php.

◆ getCacheData()

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

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 from MediaWiki\Rest\Module\Module.

Definition at line 23 of file MatcherBasedModule.php.

◆ getConfigHash()

MediaWiki\Rest\Module\MatcherBasedModule::getConfigHash ( )

abstractprotected

Get a config version hash for cache invalidation.

Returns: string

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

◆ getMatchers()

MediaWiki\Rest\Module\MatcherBasedModule::getMatchers ( )

protected

Get an array of PathMatcher objects indexed by HTTP method.

Returns: PathMatcher[]

Definition at line 62 of file MatcherBasedModule.php.

◆ initFromCacheData()

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

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 from MediaWiki\Rest\Module\Module.

Definition at line 34 of file MatcherBasedModule.php.

◆ initRoutes()

MediaWiki\Rest\Module\MatcherBasedModule::initRoutes ( )

abstractprotected

Initialize matchers by calling addRoute() for each known route.

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

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

includes/Rest/Module/MatcherBasedModule.php

Public Member Functions

Protected Member Functions

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ addRoute()

◆ findHandlerMatch()

◆ getAllowedMethods()

◆ getCacheData()

◆ getConfigHash()

◆ getMatchers()

◆ initFromCacheData()

◆ initRoutes()