A Module that is based on route definition files. More...

Collaboration diagram for MediaWiki\Rest\Module\RouteFileModule:

[legend]

Public Member Functions

__construct (array $routeFiles, array $extraRoutes, Router $router, string $pathPrefix, ResponseFactory $responseFactory, BasicAuthorizerInterface $basicAuth, ObjectFactory $objectFactory, Validator $restValidator, ErrorReporter $errorReporter)

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

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

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)

execute (string $path, RequestInterface $request)

Find the handler for a request and execute it.

getHandlerForPath (string $path, RequestInterface $request, bool $initForExecute=false)

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

getPathPrefix ()

getRouter ()

setCors (CorsUtils $cors)

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

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

ResponseFactory	$responseFactory

Detailed Description

A Module that is based on route definition files.

This module responds to requests by matching the requested path against a list of known routes to identify the appropriate handler. The routes are loaded for route definition files.

Two versions of route declaration files are currently supported, "flat" route files and "annotated" route files. Both use JSON syntax. Flat route files are supported for backwards compatibility, and should be avoided.

Flat files just contain a list (a JSON array) or route definitions (see below). Annotated route definition files contain a map (a JSON object) with the following fields:

"module": the module name (string). The router uses this name to find the correct module for handling a request by matching it against the prefix of the request path. The module name must be unique.
"routes": a list (JSON array) or route definitions (see below).

Each route definition maps a path pattern to a handler class. It is given as a map (JSON object) with the following fields:

"path": the path pattern (string) relative to the module prefix. Required. The path may contain placeholders for path parameters.
"method": the HTTP method(s) or "verbs" supported by the route. If not given, it is assumed that the route supports the "GET" method. The "OPTIONS" method for CORS is supported implicitly.
"class" or "factory": The handler class (string) or factory function (callable) of an "object spec" for use with ObjectFactory::createObject. See there for the usage of additional fields like "services". If a shorthand is used (see below), no object spec is needed.

The following fields are supported as a shorthand notation:

"redirect": the route represents a redirect and will be handled by the RedirectHandler class. The redirect is specified as a JSON object that specifies the target "path", and optional the redirect "code".

More shorthands may be added in the future.

Route definitions can contain additional fields to configure the handler. The handler can access the route definition by calling getConfig().

Access: internal

Since: 1.43

Definition at line 63 of file RouteFileModule.php.

Constructor & Destructor Documentation

◆ __construct()

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

Parameters

string[]	$routeFiles	List of names of JSON files containing routes See the documentation of this class for a description of the file format.
	array<int,array>	$extraRoutes Extension route array. The content of this array must be a list of route definitions. See the documentation of this class for a description of the expected structure.

Definition at line 96 of file RouteFileModule.php.

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

Member Function Documentation

◆ findHandlerMatch()

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

Definition at line 300 of file RouteFileModule.php.

References $path.

◆ getAllowedMethods()

MediaWiki\Rest\Module\RouteFileModule::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 346 of file RouteFileModule.php.

◆ getCacheData()

MediaWiki\Rest\Module\RouteFileModule::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 120 of file RouteFileModule.php.

◆ getDefinedPaths()

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

Access: internal: for testing and for generating OpenAPI specs

Returns: array[]

Reimplemented from MediaWiki\Rest\Module\Module.

Definition at line 245 of file RouteFileModule.php.

◆ initFromCacheData()

MediaWiki\Rest\Module\RouteFileModule::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 131 of file RouteFileModule.php.

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

includes/Rest/Module/RouteFileModule.php

Public Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ __construct()

Member Function Documentation

◆ findHandlerMatch()

◆ getAllowedMethods()

◆ getCacheData()

◆ getDefinedPaths()

◆ initFromCacheData()