MediaWiki master
MediaWiki\Rest\Module\Module Class Reference

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)
 
 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 33 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 60 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 257 of file Module.php.

◆ executeHandler()

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

Execute a fully-constructed handler.

Exceptions
HttpException

Definition at line 349 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$relPathA 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$requestThe request to handle. If $forExecution is true, this will be updated with the path parameters and parsed body data as appropriate.
bool$initForExecuteWhether 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
HttpExceptionIf no handler was found

Definition at line 135 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 184 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$cacheDataData 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 335 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 420 of file Module.php.

◆ setCors()

MediaWiki\Rest\Module\Module::setCors ( CorsUtils $cors)
Parameters
CorsUtils$cors
Returns
self

Definition at line 387 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 400 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$pathThe requested path
string$methodThe HTTP method of the current request
string[]$allowedThe allowed HTTP methods allowed by the path
Returns
never
Exceptions
HttpException

Definition at line 227 of file Module.php.

Member Data Documentation

◆ $pathPrefix

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

◆ $responseFactory

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

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


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