MediaWiki\Rest\Module\ExtraRoutesModule Class Reference

A Module that is based on flat route definitions in the form originally introduced in MW 1.35. More...

Inherits MediaWiki\Rest\Module\MatcherBasedModule.

Collaboration diagram for MediaWiki\Rest\Module\ExtraRoutesModule:

Public Member Functions
	__construct (private array $routeFiles, private readonly array $extraRoutes, Router $router, JsonLocalizer $jsonLocalizer, BasicAuthorizerInterface $basicAuth, ObjectFactory $objectFactory, Validator $restValidator, ErrorReporter $errorReporter, HookContainer $hookContainer, private readonly ServiceOptions $options,)
	getDefinedPaths ()
	getDeprecatedDate ()
	Return the timestamp at which this was or will be deprecated, or null if none. See also Handler::getDeprecatedDate() Since 1.47
	getOpenApiContact ()
	getOpenApiExternalDocs ()
	Return an array with data to be included as the root-level OpenAPI "externalDocs" object describing this module's external documentation. See also https://spec.openapis.org/oas/v3.0.0#external-documentation-object Since 1.47 Returns array
	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
Public Member Functions inherited from 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.
	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 (private readonly Router $router, protected readonly string $pathPrefix, protected readonly JsonLocalizer $jsonLocalizer, private readonly BasicAuthorizerInterface $basicAuth, private readonly ObjectFactory $objectFactory, private readonly Validator $restValidator, private readonly ErrorReporter $errorReporter, HookContainer $hookContainer,)
	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.
	getJsonLocalizer ()
	getModuleDescription ()
	Returns fields to be included when describing this module in the discovery document.
	getOpenApiTags ()
	Return an array with data to be included in an OpenAPI "tags" object describing this module's tags.
	getPathPrefix ()
	getRouter ()
	initForExecute (ResponseFactory $responseFactory)
	Initialize this module for handling requests via execute().
	setCors (CorsUtils $cors)
	setStats (StatsFactory $stats)

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

Protected Member Functions
	getConfigHash ()
	Get a config version hash for cache invalidation.
	initRoutes ()
	Initialize matchers by calling addRoute() for each known route.
Protected Member Functions inherited from MediaWiki\Rest\Module\MatcherBasedModule
	addRoute ( $method, string $path, array $info)
	getMatchers ()
	Get an array of PathMatcher objects indexed by HTTP method.
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.

Detailed Description

A Module that is based on flat route definitions in the form originally introduced in MW 1.35.

This module acts as a "catch all" since it doesn't use a module prefix. So it handles all routes that do not explicitly belong to a module.

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 from the route definition files or in extension.json files using the RestRoutes key.

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 optionally 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 65 of file ExtraRoutesModule.php.

Constructor & Destructor Documentation

__construct()

MediaWiki\Rest\Module\ExtraRoutesModule::__construct	(	private array	$routeFiles,
		private readonly array	$extraRoutes,
		Router	$router,
		JsonLocalizer	$jsonLocalizer,
		BasicAuthorizerInterface	$basicAuth,
		ObjectFactory	$objectFactory,
		Validator	$restValidator,
		ErrorReporter	$errorReporter,
		HookContainer	$hookContainer,
		private readonly ServiceOptions	$options )

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 93 of file ExtraRoutesModule.php.

Member Function Documentation

getConfigHash()

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

protected

Get a config version hash for cache invalidation.

Reimplemented from MediaWiki\Rest\Module\MatcherBasedModule.

Definition at line 121 of file ExtraRoutesModule.php.

getDefinedPaths()

MediaWiki\Rest\Module\ExtraRoutesModule::getDefinedPaths

(

)

Returns

array[]

Reimplemented from MediaWiki\Rest\Module\Module.

Definition at line 176 of file ExtraRoutesModule.php.

getDeprecatedDate()

MediaWiki\Rest\Module\ExtraRoutesModule::getDeprecatedDate

(

)

Return the timestamp at which this was or will be deprecated, or null if none.

See also

Handler::getDeprecatedDate()

Since

1.47

Reimplemented from MediaWiki\Rest\Module\Module.

Definition at line 298 of file ExtraRoutesModule.php.

getOpenApiContact()

MediaWiki\Rest\Module\ExtraRoutesModule::getOpenApiContact

(

)

Definition at line 272 of file ExtraRoutesModule.php.

getOpenApiExternalDocs()

MediaWiki\Rest\Module\ExtraRoutesModule::getOpenApiExternalDocs

(

)

Return an array with data to be included as the root-level OpenAPI "externalDocs" object describing this module's external documentation.

See also

https://spec.openapis.org/oas/v3.0.0#external-documentation-object

Since

1.47

Returns

array

Reimplemented from MediaWiki\Rest\Module\Module.

Definition at line 290 of file ExtraRoutesModule.php.

getOpenApiInfo()

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

Definition at line 252 of file ExtraRoutesModule.php.

initRoutes()

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

protected

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

Reimplemented from MediaWiki\Rest\Module\MatcherBasedModule.

Definition at line 199 of file ExtraRoutesModule.php.

References $path.

Member Data Documentation

CONSTRUCTOR_OPTIONS

const MediaWiki\Rest\Module\ExtraRoutesModule::CONSTRUCTOR_OPTIONS

Initial value:

= [
        MainConfigNames::Sitename,
        MainConfigNames::CanonicalServer,
        MainConfigNames::EmergencyContact,
        MainConfigNames::RestTermsOfServiceUrl,
    ]

Definition at line 67 of file ExtraRoutesModule.php.

---

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

• includes/Rest/Module/ExtraRoutesModule.php