Documentation

Http extends AbstractMatch
in package

Pop router HTTP match class

Tags
category

Pop

author

Nick Sagona, III nick@popphp.org

copyright

Copyright (c) 2009-2026 Nick Sagona, III

license

https://www.popphp.org/license New BSD License

version
5.0.0

Table of Contents

Properties

$allowedMethods  : array<string|int, mixed>
Methods accepted by at least one path-matching route, populated by match() for use in a 405 response's Allow header
$basePath  : string|null
Base path
$customMethods  : array<string|int, mixed>
Whitelisted custom HTTP methods, for use with __call()
$defaultRoute  : array<string|int, mixed>|null
Default route
$dispatchableCache  : mixed
Cached dispatchable resolution for the current match cycle
$dispatchableParams  : array<string|int, mixed>
Dispatchable parameters
$dispatchableResolved  : bool
Whether the dispatchable has been resolved for the current match cycle
$dynamicRoute  : mixed
Dynamic route
$dynamicRouteActionIndex  : int|null
Position of the ':action'/'<action>' token within the dynamic route declaration
$dynamicRouteControllerIndex  : int|null
Position of the ':controller'/'<controller>' token within the dynamic route declaration
$dynamicRouteLiterals  : array<string|int, mixed>
Literal segments of the dynamic route declaration, keyed by their position within that declaration
$dynamicRoutePrefix  : mixed
Dynamic route prefix
$isDynamicRoute  : bool
Flag for dynamic route
$methodMismatch  : bool
Flag set by match(): true when the request path matched at least one route whose method constraint rejected the request, and nothing else (no wildcard/dynamic fallback) ended up handling it
$methodRoutes  : array<string|int, mixed>
Map of synthetic method-scoped route keys (see addRoute()) back to their real route string, used only internally by flattenRoutes() to recover the real path for regex generation
$preparedRoutes  : array<string|int, mixed>
Prepared routes
$preparedRoutesByLiteral  : array<string|int, mixed>
Prepared route keys grouped by their literal route path, so a direct (literal, non-regex) match only has to scan that path's method variants instead of every prepared route.
$route  : string|null
Matched route
$routeNames  : array<string|int, mixed>
Route names
$routeParams  : array<string|int, mixed>
Route parameters
$routes  : array<string|int, mixed>
Routes
$routeSpecificity  : array<string|int, mixed>
Specificity score per prepared route, keyed the same as preparedRoutes.
$routeString  : string|null
Route string
$segments  : array<string|int, mixed>
Segments of route string

Methods

__call()  : static
Magic method to register a route for a whitelisted custom HTTP method
__construct()  : mixed
Constructor
acceptsHtml()  : bool
Determine if the inbound request has a real preference for an HTML response
addCustomMethod()  : static
Add a custom HTTP method to the whitelist
addCustomMethods()  : static
Add multiple custom HTTP methods to the whitelist
addDispatchableParams()  : AbstractMatch
Add dispatchable params to be passed into a new dispatchable instance
addRoute()  : AbstractMatch
Add a route
addRoutes()  : AbstractMatch
Add multiple controller routes
appendDispatchableParams()  : AbstractMatch
Append dispatchable params to be passed into a new dispatchable instance
connect()  : static
Add a CONNECT route
delete()  : static
Add a DELETE route
get()  : static
Add a GET route
getAction()  : mixed
Get the action
getAllowedMethods()  : array<string|int, mixed>
Get the methods accepted by at least one path-matching route from the last match() call, for use in a 405 response's Allow header
getBasePath()  : string
Get the base path
getDefaultRoute()  : array<string|int, mixed>
Get the default route
getDispatchable()  : mixed
Get the dispatchable
getDispatchableParams()  : mixed
Get the params assigned to the dispatchable
getDynamicRoute()  : mixed
Get the dynamic route
getDynamicRoutePrefix()  : mixed
Get the dynamic route prefix
getFlattenedRoutes()  : array<string|int, mixed>
Get flattened routes
getOriginalRoute()  : string|null
Get original route string
getPreparedRoutes()  : array<string|int, mixed>
Get prepared routes
getRoute()  : string
Get route regex
getRouteConfig()  : mixed
Get route config
getRouteParams()  : array<string|int, mixed>
Get the params discovered from the route
getRoutes()  : array<string|int, mixed>
Get routes
getRouteString()  : string
Get the route string
getSegment()  : string|null
Get a route string segment
getSegments()  : array<string|int, mixed>
Get the route string segments
getUrl()  : string
Get URL for the named route
hasAction()  : bool
Determine if there is an action
hasCustomMethod()  : bool
Determine if a custom HTTP method has been whitelisted
hasDefaultRoute()  : bool
Determine if there is a default route
hasDispatchable()  : bool
Determine if there is a dispatchable
hasDispatchableParams()  : bool
Determine if the dispatchable has params
hasDynamicRoute()  : bool
Determine if there is a dynamic route
hasMethodMismatch()  : bool
Determine if match() found a route whose path matched but whose method constraint rejected the request, with nothing else available to handle it
hasName()  : bool
Has a route name
hasRoute()  : bool
Determine if the route has been matched
hasRouteConfig()  : bool
Has route config
hasRouteParams()  : bool
Determine if the route has params
head()  : static
Add a HEAD route
isDynamicRoute()  : bool
Determine if it is a dynamic route
match()  : bool
Match the route
methodNotAllowed()  : void
Method to process if a route matched the path but not the HTTP method
name()  : AbstractMatch
Add a route name
noRouteFound()  : void
Method to process if a route was not found
options()  : static
Add an OPTIONS route
patch()  : static
Add a PATCH route
post()  : static
Add a POST route
prepare()  : static
Prepare the routes
put()  : static
Add a PUT route
removeDispatchableParams()  : AbstractMatch
Remove dispatchable params
trace()  : static
Add a TRACE route
addVerbRoute()  : static
Register a route constrained to a single HTTP method
applyMethodToNestedRoutes()  : mixed
Recursively apply a method-group's method list to every leaf config in a (possibly further-nested) route sub-tree, without disturbing the sub-tree's own nested route keys
flattenRoutes()  : void
Flatten the nested routes
getDynamicRouteParamOffset()  : int
Get the segment offset at which the dynamic route's params start, i.e. the segment right after the action token
getRouteRegex()  : array<string|int, mixed>
Get the REGEX pattern for the route string
isDynamicRouteDeclaration()  : bool
Determine if a route declaration is the dynamic-route (":controller"/"<controller") pattern
isDynamicRouteLiteral()  : bool
Determine if a dynamic route declaration token is a literal segment, i.e. neither a param token nor an option
isMethodGroupKey()  : bool
Determine if a route key is a Popcorn-style method-group key, e.g.
matchesDynamicRoute()  : bool
Determine if the current request matches the dynamic route declaration: every literal segment of the declaration has to line up with the request's segment in that same position, and the request has to carry a segment where the declaration puts its controller token
normalizeController()  : mixed
Normalize a raw dispatchable value (closure, native callable, or a pop-utils pseudo-callable string such as 'Class->method', 'Class::method', 'Class', or 'new Class') into a ['controller' => $controller] config array. Already-formed config arrays (and nested-route sub-arrays) are returned unchanged.
normalizeMethods()  : array<string|int, mixed>|null
Normalize a 'method' config value (a method string, a comma-separated string, or an array of method strings) into a sorted, deduplicated, lowercase array. Returns null for an empty/absent value ("any method").
parseDynamicRoute()  : void
Parse a dynamic route declaration, recording where its ':controller'/':action' (HTTP) or '<controller>'/'<action>' (CLI) tokens sit within the declaration, along with any literal segments the request has to match for the route to apply
parseRouteParams()  : void
Parse route dispatch parameters
registerDynamicRoute()  : void
Register a dynamic route
registerRegularRoute()  : mixed
Register a regular (literal or param-bearing) route, recursing for nested route configs
registerWildcardRoute()  : mixed
Register a wildcard/default route
resolveNamedParamValue()  : mixed
Resolve a named param's raw value from either an object or an array of params
seed()  : void
Seed the parsing inputs (segments and route string) from either pre-split path segments or a raw path string

Properties

$allowedMethods

Methods accepted by at least one path-matching route, populated by match() for use in a 405 response's Allow header

protected array<string|int, mixed> $allowedMethods = []

$basePath

Base path

protected string|null $basePath = null

$customMethods

Whitelisted custom HTTP methods, for use with __call()

protected array<string|int, mixed> $customMethods = []

$defaultRoute

Default route

protected array<string|int, mixed>|null $defaultRoute = null

$dispatchableCache

Cached dispatchable resolution for the current match cycle

protected mixed $dispatchableCache = null

$dispatchableParams

Dispatchable parameters

protected array<string|int, mixed> $dispatchableParams = []

$dispatchableResolved

Whether the dispatchable has been resolved for the current match cycle

protected bool $dispatchableResolved = false

$dynamicRoute

Dynamic route

protected mixed $dynamicRoute = null

$dynamicRouteActionIndex

Position of the ':action'/'<action>' token within the dynamic route declaration

protected int|null $dynamicRouteActionIndex = null

$dynamicRouteControllerIndex

Position of the ':controller'/'<controller>' token within the dynamic route declaration

protected int|null $dynamicRouteControllerIndex = null

$dynamicRouteLiterals

Literal segments of the dynamic route declaration, keyed by their position within that declaration

protected array<string|int, mixed> $dynamicRouteLiterals = []

$dynamicRoutePrefix

Dynamic route prefix

protected mixed $dynamicRoutePrefix = null

$isDynamicRoute

Flag for dynamic route

protected bool $isDynamicRoute = false

$methodMismatch

Flag set by match(): true when the request path matched at least one route whose method constraint rejected the request, and nothing else (no wildcard/dynamic fallback) ended up handling it

protected bool $methodMismatch = false

$methodRoutes

Map of synthetic method-scoped route keys (see addRoute()) back to their real route string, used only internally by flattenRoutes() to recover the real path for regex generation

protected array<string|int, mixed> $methodRoutes = []

$preparedRoutes

Prepared routes

protected array<string|int, mixed> $preparedRoutes = []

$preparedRoutesByLiteral

Prepared route keys grouped by their literal route path, so a direct (literal, non-regex) match only has to scan that path's method variants instead of every prepared route.

protected array<string|int, mixed> $preparedRoutesByLiteral = []

$routeNames

Route names

protected array<string|int, mixed> $routeNames = []

$routeParams

Route parameters

protected array<string|int, mixed> $routeParams = []

$routes

Routes

protected array<string|int, mixed> $routes = []

$routeSpecificity

Specificity score per prepared route, keyed the same as preparedRoutes.

protected array<string|int, mixed> $routeSpecificity = []

Kept out of the preparedRoutes entries themselves so it doesn't leak into getRouteConfig()/getPreparedRoutes() public output.

$routeString

Route string

protected string|null $routeString = null

$segments

Segments of route string

protected array<string|int, mixed> $segments = []

Methods

__call()

Magic method to register a route for a whitelisted custom HTTP method

public __call(string $name, array<string|int, mixed> $arguments) : static
Parameters
$name : string
$arguments : array<string|int, mixed>
Tags
throws
Exception
Return values
static

__construct()

Constructor

public __construct() : mixed

Instantiate the HTTP match object

acceptsHtml()

Determine if the inbound request has a real preference for an HTML response

public acceptsHtml() : bool

HTML only wins on a real preference (AcceptSpecificity::Loose - a bare '/' doesn't count); everything else falls back to JSON. That's the opposite of checking for an explicit JSON preference - a real browser always states 'text/html' explicitly in its Accept header, while non-browser HTTP clients (curl, most API callers) are wildly inconsistent about declaring 'application/json' and commonly send a bare '/' or no Accept header at all.

Return values
bool

addCustomMethod()

Add a custom HTTP method to the whitelist

public addCustomMethod(string $method) : static
Parameters
$method : string
Return values
static

addCustomMethods()

Add multiple custom HTTP methods to the whitelist

public addCustomMethods(array<string|int, mixed> $methods) : static
Parameters
$methods : array<string|int, mixed>
Return values
static

addDispatchableParams()

Add dispatchable params to be passed into a new dispatchable instance

public addDispatchableParams(string $dispatchable, mixed $params) : AbstractMatch
Parameters
$dispatchable : string
$params : mixed
Return values
AbstractMatch

addRoute()

Add a route

public addRoute(string $route, mixed $controller) : AbstractMatch

Overrides AbstractMatch::addRoute() only for a regular route (not wildcard, not dynamic) that carries a 'method' constraint - those are stored under a synthetic composite key (route + a null-byte-separated method signature) instead of the plain route string, so registering the same path for multiple methods with different controllers (GET and POST on the same URI) doesn't collide with AbstractMatch::addRoute()'s merge-on-duplicate-key behavior, which would otherwise silently overwrite the earlier registration. Every other case (no method key, wildcard routes, dynamic routes, nested route arrays) falls through to the parent implementation unchanged.

Parameters
$route : string
$controller : mixed
Return values
AbstractMatch

appendDispatchableParams()

Append dispatchable params to be passed into a new dispatchable instance

public appendDispatchableParams(string $dispatchable, mixed $params) : AbstractMatch
Parameters
$dispatchable : string
$params : mixed
Return values
AbstractMatch

connect()

Add a CONNECT route

public connect(string $route, mixed $controller) : static
Parameters
$route : string
$controller : mixed
Return values
static

delete()

Add a DELETE route

public delete(string $route, mixed $controller) : static
Parameters
$route : string
$controller : mixed
Return values
static

get()

Add a GET route

public get(string $route, mixed $controller) : static
Parameters
$route : string
$controller : mixed
Return values
static

getAllowedMethods()

Get the methods accepted by at least one path-matching route from the last match() call, for use in a 405 response's Allow header

public getAllowedMethods() : array<string|int, mixed>
Return values
array<string|int, mixed>

getBasePath()

Get the base path

public getBasePath() : string
Return values
string

getDefaultRoute()

Get the default route

public getDefaultRoute() : array<string|int, mixed>
Return values
array<string|int, mixed>

getDispatchable()

Get the dispatchable

public getDispatchable() : mixed

getDispatchableParams()

Get the params assigned to the dispatchable

public getDispatchableParams(string $dispatchable) : mixed
Parameters
$dispatchable : string

getDynamicRoute()

Get the dynamic route

public getDynamicRoute() : mixed

getDynamicRoutePrefix()

Get the dynamic route prefix

public getDynamicRoutePrefix() : mixed

getFlattenedRoutes()

Get flattened routes

public getFlattenedRoutes() : array<string|int, mixed>
Return values
array<string|int, mixed>

getOriginalRoute()

Get original route string

public getOriginalRoute() : string|null
Return values
string|null

getPreparedRoutes()

Get prepared routes

public getPreparedRoutes() : array<string|int, mixed>
Return values
array<string|int, mixed>

getRoute()

Get route regex

public getRoute() : string
Return values
string

getRouteConfig()

Get route config

public getRouteConfig([string|null $key = null ]) : mixed
Parameters
$key : string|null = null

getRouteParams()

Get the params discovered from the route

public getRouteParams() : array<string|int, mixed>
Return values
array<string|int, mixed>

getRoutes()

Get routes

public getRoutes() : array<string|int, mixed>
Return values
array<string|int, mixed>

getRouteString()

Get the route string

public getRouteString() : string
Return values
string

getSegment()

Get a route string segment

public getSegment(int $i) : string|null
Parameters
$i : int
Return values
string|null

getSegments()

Get the route string segments

public getSegments() : array<string|int, mixed>
Return values
array<string|int, mixed>

getUrl()

Get URL for the named route

public getUrl(string $routeName[, mixed $params = null ][, bool $fqdn = false ]) : string
Parameters
$routeName : string
$params : mixed = null
$fqdn : bool = false
Return values
string

hasAction()

Determine if there is an action

public hasAction() : bool
Return values
bool

hasCustomMethod()

Determine if a custom HTTP method has been whitelisted

public hasCustomMethod(string $method) : bool
Parameters
$method : string
Return values
bool

hasDefaultRoute()

Determine if there is a default route

public hasDefaultRoute() : bool
Return values
bool

hasDispatchable()

Determine if there is a dispatchable

public hasDispatchable() : bool
Return values
bool

hasDispatchableParams()

Determine if the dispatchable has params

public hasDispatchableParams(string $dispatchable) : bool
Parameters
$dispatchable : string
Return values
bool

hasDynamicRoute()

Determine if there is a dynamic route

public hasDynamicRoute() : bool
Return values
bool

hasMethodMismatch()

Determine if match() found a route whose path matched but whose method constraint rejected the request, with nothing else available to handle it

public hasMethodMismatch() : bool
Return values
bool

hasName()

Has a route name

public hasName(string $routeName) : bool
Parameters
$routeName : string
Return values
bool

hasRoute()

Determine if the route has been matched

public hasRoute() : bool
Return values
bool

hasRouteConfig()

Has route config

public hasRouteConfig([string|null $key = null ]) : bool
Parameters
$key : string|null = null
Return values
bool

hasRouteParams()

Determine if the route has params

public hasRouteParams() : bool
Return values
bool

head()

Add a HEAD route

public head(string $route, mixed $controller) : static
Parameters
$route : string
$controller : mixed
Return values
static

isDynamicRoute()

Determine if it is a dynamic route

public isDynamicRoute() : bool
Return values
bool

match()

Match the route

public match([string|array<string|int, mixed>|null $forceRoute = null ]) : bool
Parameters
$forceRoute : string|array<string|int, mixed>|null = null
Return values
bool

methodNotAllowed()

Method to process if a route matched the path but not the HTTP method

public methodNotAllowed(array<string|int, mixed> $allowedMethods[, bool $exit = true ]) : void
Parameters
$allowedMethods : array<string|int, mixed>
$exit : bool = true

noRouteFound()

Method to process if a route was not found

public noRouteFound([bool $exit = true ]) : void
Parameters
$exit : bool = true

options()

Add an OPTIONS route

public options(string $route, mixed $controller) : static
Parameters
$route : string
$controller : mixed
Return values
static

patch()

Add a PATCH route

public patch(string $route, mixed $controller) : static
Parameters
$route : string
$controller : mixed
Return values
static

post()

Add a POST route

public post(string $route, mixed $controller) : static
Parameters
$route : string
$controller : mixed
Return values
static

prepare()

Prepare the routes

public prepare() : static
Return values
static

put()

Add a PUT route

public put(string $route, mixed $controller) : static
Parameters
$route : string
$controller : mixed
Return values
static

trace()

Add a TRACE route

public trace(string $route, mixed $controller) : static
Parameters
$route : string
$controller : mixed
Return values
static

addVerbRoute()

Register a route constrained to a single HTTP method

protected addVerbRoute(string $method, string $route, mixed $controller) : static
Parameters
$method : string
$route : string
$controller : mixed
Return values
static

applyMethodToNestedRoutes()

Recursively apply a method-group's method list to every leaf config in a (possibly further-nested) route sub-tree, without disturbing the sub-tree's own nested route keys

protected applyMethodToNestedRoutes(mixed $controller, string $method) : mixed
Parameters
$controller : mixed
$method : string

flattenRoutes()

Flatten the nested routes

protected flattenRoutes(array<string|int, mixed>|string $route[, mixed $controller = null ]) : void
Parameters
$route : array<string|int, mixed>|string
$controller : mixed = null

getDynamicRouteParamOffset()

Get the segment offset at which the dynamic route's params start, i.e. the segment right after the action token

protected getDynamicRouteParamOffset() : int
Return values
int

getRouteRegex()

Get the REGEX pattern for the route string

protected getRouteRegex(string $route) : array<string|int, mixed>
Parameters
$route : string
Return values
array<string|int, mixed>

isDynamicRouteDeclaration()

Determine if a route declaration is the dynamic-route (":controller"/"<controller") pattern

protected isDynamicRouteDeclaration(string $route) : bool
Parameters
$route : string
Return values
bool

isDynamicRouteLiteral()

Determine if a dynamic route declaration token is a literal segment, i.e. neither a param token nor an option

protected isDynamicRouteLiteral(string $token) : bool
Parameters
$token : string
Return values
bool

isMethodGroupKey()

Determine if a route key is a Popcorn-style method-group key, e.g.

protected isMethodGroupKey(string $route) : bool

'get', 'options,get', 'options,post' - a bare, comma-separated list of recognized HTTP methods only, never a real route path (which always starts with '/', is '*', or contains ':controller').

Parameters
$route : string
Return values
bool

matchesDynamicRoute()

Determine if the current request matches the dynamic route declaration: every literal segment of the declaration has to line up with the request's segment in that same position, and the request has to carry a segment where the declaration puts its controller token

protected matchesDynamicRoute() : bool
Return values
bool

normalizeController()

Normalize a raw dispatchable value (closure, native callable, or a pop-utils pseudo-callable string such as 'Class->method', 'Class::method', 'Class', or 'new Class') into a ['controller' => $controller] config array. Already-formed config arrays (and nested-route sub-arrays) are returned unchanged.

protected normalizeController(mixed $controller) : mixed
Parameters
$controller : mixed

normalizeMethods()

Normalize a 'method' config value (a method string, a comma-separated string, or an array of method strings) into a sorted, deduplicated, lowercase array. Returns null for an empty/absent value ("any method").

protected normalizeMethods(mixed $method) : array<string|int, mixed>|null
Parameters
$method : mixed
Return values
array<string|int, mixed>|null

parseDynamicRoute()

Parse a dynamic route declaration, recording where its ':controller'/':action' (HTTP) or '<controller>'/'<action>' (CLI) tokens sit within the declaration, along with any literal segments the request has to match for the route to apply

protected parseDynamicRoute(string $route) : void
Parameters
$route : string

parseRouteParams()

Parse route dispatch parameters

protected parseRouteParams() : void

registerDynamicRoute()

Register a dynamic route

protected registerDynamicRoute(string $route, mixed $controller) : void
Parameters
$route : string
$controller : mixed

registerRegularRoute()

Register a regular (literal or param-bearing) route, recursing for nested route configs

protected registerRegularRoute(string $route, mixed $controller) : mixed
Parameters
$route : string
$controller : mixed
Return values
mixed

the normalized controller config

registerWildcardRoute()

Register a wildcard/default route

protected registerWildcardRoute(string $route, mixed $controller) : mixed
Parameters
$route : string
$controller : mixed
Return values
mixed

the normalized controller config

resolveNamedParamValue()

Resolve a named param's raw value from either an object or an array of params

protected resolveNamedParamValue(mixed $params, string $paramName) : mixed
Parameters
$params : mixed
$paramName : string

seed()

Seed the parsing inputs (segments and route string) from either pre-split path segments or a raw path string

protected seed(string|array<string|int, mixed> $input) : void
Parameters
$input : string|array<string|int, mixed>

        
On this page

Search results