Index

APIRoute

MMO\core\attributes ยท 1 symbol ยท generated 30 Sep 2026

class

APIRoute

APIRoute.php:78

Class to use to match a route in the router.

#[Attribute(6)] class MMO\core\attributes\APIRoute implements JsonSerializable, Stringable use MMO\core\classes\tWithOptions
Namespace
MMO\core\attributes
Implements
JsonSerializable, Stringable
Uses traits
tWithOptions
## Usage You can use this as an attribute for a controller's route : ```php class MyController { #[APIRoute('POST|update', body: ['id' => 'string', 'parent' => Entity::class])] public function routeX(\MMO\core\server\Route $route): ?iResponse {...} ... } \MMO\connect(MyController::class);//register the route in the app ``` Or use it directly and add it manually to the Application ```php //register route in a custom group 'mygroup' \MMO\app()->addRoute('mygroup', new APIRoute('POST|update', body: ['id' => 'string', 'parent' => Entity::class]) ->setOperation(function(\MMO\core\server\Route $route): ?iResponse {...}) ); ``` ## Url URL are relative and use this format: {method}|{path}?{query}#{fragment} - {method}: *|GET|POST|PUT|DELETE|PATCH|HEAD - {path}: a relative path. can contain moustache expressions. NOTE: `*` is replaced by one path item. It can be placed anywhere in the url's path. NOTE: `**` is replaced by multiple path item. It MUST be the last element on the path's url. - {query}: an encoded url query. can contain moustache expressions. - {fragment}: an url fragment. can contain moustache expressions. To declare a placeholder use the moustache format. - `{id:identifier}`: match is stored at key `id` and use the schema `identifier` to coerce and validate the value. NOTE: you need to register this custom schema by calling `Path::SetTypeSchema('identifier', ['type' => ...])` - `{?page:integer}`: match is NOT REQUIRED and is stored in key `page`. schema `integer` is used to validate and coerce the value. NOTE: for body|cookie|header you can pass a string that will be parsed as an url's query, or an array of key => value where the value can either be a string (with placeholder) or a schema ## Options You can add options to the route that will be transmitted in the matches when the route matches. These matches are then added as attributes of the request - hidden: {bool} if true, the route id hidden from the list of available routes - anonymous: {bool} if true, allow the route to be available without a user (used by oauth)
'index' match 'index/test' ($match = ['test']) and 'index' ($match = []) but not 'index/test/1''index /1' match 'index/test/1' ($match = ['test']) but not 'index''index*' match 'index/test' ($match = ['**' => 'test']) and 'index/test/1' ($match = ['**' => 'test/1']) and 'index' ($match = [])GET|mypath/{page:string}/{id:identifier}?page={?page:integer} - `{page:string}`: match is stored at key `page` and the value is coerced by the schema `string`.

Index

body
cookie
fragment
header
info
method
opts
order
path
query
addAPIParameter($parameters, $info)
addAPIParameters($params, $in)
addInfo($info, $default)Add information to the route
addOptions($opts, $appendList)Merge $opts into the existing options (through merge), rather than replacing them wholesale like setOptions.
api()Build this route's OpenAPI operation object (path parameters, query/header/cookie parameters, request body, merged with any extra addInfo info).
clearOptions()Empty the options bag.
createRequest($data, $method)Build a real Request matching this route, useful to synthesize/test a call without going through HTTP.
debugName()
getBody($data)
getCookie($data)
getFragment()
getHeader($data)
getInfo($key, $default)
getMethod()
getOperation()
getOption($key, $default)
getOptions()
getOrder()
getParameters($in, $data)
getPath()
getQuery($data)
getUrl($data, $absolute)Get path url. If no data are passed, it return a relative url with placeholders
hasInfo($key)
isHidden()
jsonSerialize()
match($request, $matches)Check if a request match this path.
setBasepath($path)
setBody($value)
setCookie($value)
setFragment($fragment)
setHeader($value)
setMethod($method)
setOperation($id)
setOption($key, $value)Set (or, with a null $value, remove) a single option.
setOptions($opts)Replace the whole options bag.
setOrder($value)
setParameters($in, $value)Set parameters capture information
setPath($path)Same as From, except wildcard are converted to placeholders
setQuery($value)
setUrl($url)Parse a full {method}|{path}?{query}#{fragment} route URL (see this class's own docblock for the format) and set every corresponding property (method, path, query, fragment) from it.
toLink($data, $rels)
uid()
__construct($url, $info, $body, $mediaTypes, $order, $options)
__toString()

Properties10

body

protected ?array $body = null
Type
null | array

fragment

protected ?string $fragment = null
Type
null | string

header

protected ?array $header = null
Type
null | array

info

protected array $info = []
Type
array

opts

protected array $opts = []
Type
array

order

protected int $order = 0
Type
int

path

protected MMO\core\helpers\Path $path
Type
Path

query

protected ?array $query = null
Type
null | array

Methods44

addAPIParameter($parameters, $info)

APIRoute.php:239
protected function addAPIParameter(array &$parameters, array $info): void
$parametersarray
$infoarray
returnsvoid

addInfo($info, $default)

APIRoute.php:153

Add information to the route

function addInfo(array $info, bool $default = false): void
$infoarray
$default = falseboolif true, current information are not overwritten
returnsvoid

addOptions($opts, $appendList)

tWithOptions.php:65

Merge $opts into the existing options (through merge), rather than replacing them wholesale like setOptions.

function addOptions(array $opts, bool $appendList = false): void
$optsarraythe options to merge in
$appendList = falseboolif true, a list-valued option is appended to (rather than replaced by) the corresponding list in $opts -- see \MMO\core\arrays\merge for the exact semantics
returnsvoid
$t->setOptions(['a' => 1, 'tags' => ['x']]); $t->addOptions(['b' => 2, 'tags' => ['y']]); $t->getOptions(); // ['a' => 1, 'tags' => ['y'], 'b' => 2] -- 'tags' is replaced, not appended ($appendList=false)

api()

APIRoute.php:282

Build this route's OpenAPI operation object (path parameters, query/header/cookie parameters, request body, merged with any extra addInfo info).

function api(): array
returnsarray[] if isHidden; otherwise ['/path' => ['method' => [...openapi operation...]]]

clearOptions()

tWithOptions.php:39

Empty the options bag.

function clearOptions(): void
returnsvoid
$t->clearOptions(); // getOptions() === []

createRequest($data, $method)

APIRoute.php:171

Build a real Request matching this route, useful to synthesize/test a call without going through HTTP.

function createRequest(array $data = [], ?string $method = null): MMO\core\server\Request
$data = []arrayplaceholder values for the URL/body/header/cookie templates
$method = nullnull | stringoverrides this route's own method (needed if the route accepts any method)
returnsRequest

getBody($data)

APIRoute.php:507
function getBody(?array $data = null): ?array
$data = nullnull | arrayif given, render each body template against it instead of returning the raw definitions
returnsnull | array

getCookie($data)

APIRoute.php:527
function getCookie(?array $data = null): ?array
$data = nullnull | arrayif given, render each cookie template against it instead of returning the raw definitions
returnsnull | array

getHeader($data)

APIRoute.php:517
function getHeader(?array $data = null): ?array
$data = nullnull | arrayif given, render each header template against it instead of returning the raw definitions
returnsnull | array

getMethod()

APIRoute.php:223
function getMethod(): ?string
returnsnull | stringthe HTTP method (or 'SHELL'), or null if this route matches any method

getOption($key, $default)

tWithOptions.php:49
function getOption(string $key, mixed $default = null): mixed
$keystring
$default = nullmixedreturned if $key is not set
returnsmixed
$t->getOption('a', 'fallback'); // the current value of 'a', or 'fallback' if not set

getOptions()

tWithOptions.php:20
function getOptions(): array
returnsarrayevery option currently set
$t->getOptions(); // ['a' => 1, 'tags' => ['x']]

getOrder()

APIRoute.php:537
function getOrder(): int
returnsintthis route's matching priority (lower runs first among routes that both match)

getPath()

APIRoute.php:331
function getPath(): MMO\core\helpers\Path
returnsPaththe route's path (without method/query/fragment)

getQuery($data)

APIRoute.php:497
function getQuery(?array $data = null): ?array
$data = nullnull | arrayif given, render each query template against it instead of returning the raw definitions
returnsnull | array

getUrl($data, $absolute)

APIRoute.php:364

Get path url. If no data are passed, it return a relative url with placeholders

function getUrl(?array $data = null, bool $absolute = false): string
$data = nullnull | arrayif null won't expand the data
$absolute = falseboolif true, resolve to an absolute URL via \MMO\url()
returnsstring
throwsif $data is given but is missing a required query/fragment placeholder
$route->getUrl(); // 'users/{id:integer}' -- placeholders left as-is$route->getUrl(['id' => 5]); // 'users/5'

isHidden()

APIRoute.php:122
function isHidden(): bool
returnsbooltrue if the 'hidden' option is set: excluded from api() output and route listings

match($request, $matches)

APIRoute.php:185

Check if a request match this path.

function match( Psr\Http\Message\ServerRequestInterface $request, ?array &$matches = null ): string|true
$requestServerRequestInterface
$matches = nullnull | array
returnsstring | trueif string tells which property did not match, else return true

setBasepath($path)

APIRoute.php:452
function setBasepath(string $path): void
$pathstringprefix prepended to this route's own path when building URLs
returnsvoid

setMethod($method)

APIRoute.php:232
function setMethod(?string $method): void
$methodnull | stringone of GET/POST/PUT/DELETE/PATCH/HEAD/SHELL, '*', or null (both mean "any method")
returnsvoid
throwsfor any other value

setOption($key, $value)

tWithOptions.php:77

Set (or, with a null $value, remove) a single option.

function setOption(string $key, mixed $value): void
$keystring
$valuemixedif null, the option is unset entirely rather than being set to null
returnsvoid
$t->setOption('a', 1);$t->setOption('a', null); // removes 'a' from getOptions()

setOptions($opts)

tWithOptions.php:30

Replace the whole options bag.

function setOptions(array $opts): void
$optsarray
returnsvoid
$t->setOptions(['a' => 1]);

setParameters($in, $value)

APIRoute.php:487

Set parameters capture information

protected function setParameters(string $in, array|string|null $value): void
$instringquery,body,header,cookie
$valuearray | string | nullif string, split as an url's query if an array and the value is an array, it is the definition of the schema to use
returnsvoid

setPath($path)

APIRoute.php:341

Same as From, except wildcard are converted to placeholders

function setPath(MMO\core\helpers\Path|array|string $path): void
$pathPath | array | string
returnsvoid

setQuery($value)

APIRoute.php:502
function setQuery(array|string|null $value): void
$valuearray | string | nulla raw query string, or key => (template string | Schema)
returnsvoid

setUrl($url)

APIRoute.php:423

Parse a full {method}|{path}?{query}#{fragment} route URL (see this class's own docblock for the format) and set every corresponding property (method, path, query, fragment) from it.

function setUrl(string $url): voidWARNING: this url MUST be relative (to the router's url)
$urlstring
returnsvoid
throwsif $url is absolute
$route->setUrl('GET|users/{id:integer}?active={?active:boolean}');

uid()

APIRoute.php:127
function uid(): string
returnsstringthe operation id, or a readable name derived from its callable if it isn't a string

__construct($url, $info, $body, $mediaTypes, $order, $options)

APIRoute.php:92
function __construct( string $url, array|string $info = [], ?array $body = null, array $mediaTypes = [], int $order = 0, array $options = [] )
$urlstring
$info = []array | string
$body = nullnull | array
$mediaTypes = []array
$order = 0int
$options = []array