Contents

October\Rain\Router\Router

Overview

Router used in October CMS for managing page routes.

Matching uses compiled lookup structures (see RouteCompiler): a hash map for static routes, a combined regex for dynamic routes and sequential matching for wildcard routes. Compilation happens lazily on the first match and sorts the route map by specificity (see sortRules), the compiled result can be cached and restored via toArray/fromArray.


Public Properties

public static string $defaultValue

defaultValue to use when a required parameter is not specified

Protected Properties

protected array $routeMap

routeMap is a list of specified routes. Rules restored from cached data are stored as raw config arrays and hydrated to Rule objects on demand.

protected October\Rain\Router\Rule $matchedRouteRule

matchedRouteRule reference

protected array $parameters

parameters with names and values extracted from the URL pattern and URL string

protected bool $isCompiled

isCompiled indicates if routes have been compiled for optimized matching

protected array $staticRoutes

staticRoutes hash map for O(1) static route lookup

protected array $dynamicRegexes

dynamicRegexes combined regexes for dynamic routes, keyed by the first static URL segment

protected array $dynamicRouteMap

dynamicRouteMap maps a combined regex mark to route info

protected array $fallbackRules

fallbackRules are rules matched sequentially (wildcard rules), each with the position they hold in the sorted route map


Public Methods

public compileRules()

public compileRules(): $this 

compileRules sorts the route map and builds the compiled lookup structures used for optimized matching

public fromArray()

public fromArray($data): void

fromArray loads routes from an array, including compiled state when present. Supports the legacy format (a plain list of rules).

public getCompiledRoutes()

public getCompiledRoutes(): array 

getCompiledRoutes returns the compiled route data, compiling first if necessary

public getParameters()

public getParameters(): array 

getParameters returns a list of parameters specified in the requested page URL. For example, if the URL pattern was /blog/post/:id and the actual URL was /blog/post/10, the $parameters['id'] element would be 10.

public getRoute()

public getRoute(string $name): Rule|null 

getRoute returns a route rule by name

public getRouteMap()

public getRouteMap(): array 

getRouteMap returns the active list of router rule objects

public hasRoute()

public hasRoute(string $name): bool 

hasRoute checks if a named route exists

public isCompiled()

public isCompiled(): bool 

isCompiled returns whether routes have been compiled

public static loadCompiledRoutes()

public static loadCompiledRoutes(string $path): static|null 

loadCompiledRoutes loads compiled routes from a PHP file

public match()

public match(string $url): bool 

match given URL string

public matchedRoute()

public matchedRoute(): October\Rain\Router\Rule 

matchedRoute returns the matched route rule name.

public reset()

public reset(): $this 

reset clears all existing routes

public route()

public route($name, $route): void

route registers a new route rule

public saveCompiledRoutes()

public saveCompiledRoutes(string $path): bool 

saveCompiledRoutes saves the routes with their compiled state to a PHP file, similar to Laravel's route:cache. Load it later with loadCompiledRoutes for instant route matching.

public setCompiledRoutes()

public setCompiledRoutes(array $compiled): $this 

setCompiledRoutes restores compiled route data, positions in the data must correspond to the current route map order. Data with a version mismatch is ignored and routes are recompiled on the next match.

public sortRules()

public sortRules(): void 

sortRules sorts all the routing rules by static segments (long to short), then dynamic segments (short to long), then wild segments (at end).

public toArray()

public toArray(): array 

toArray converts the rules to an array, including the compiled state for cache storage.

public url()

public url(string $name, array $parameters = []): string 

url builds a URL together by matching route name and supplied parameters

public urlFromPattern()

public urlFromPattern(string $pattern, array $parameters = []): string 

urlFromPattern builds a URL together by matching route pattern and supplied parameters

Protected Methods

protected acceptRuleMatch()

protected acceptRuleMatch(
    Rule $routeRule,
    array $parameters,
    string $url
): bool 

acceptRuleMatch runs the rule condition, stores the matched rule and processed parameters. Returns false when the condition rejects the match.

protected extractDynamicCandidate()

protected extractDynamicCandidate(array $matches): array|null 

extractDynamicCandidate builds the matched route candidate from a combined regex match, validating custom segment expressions with the same logic as Rule::resolveUrlSegments

protected hydrateRules()

protected hydrateRules(): void 

hydrateRules converts any raw rule configs to Rule objects

protected invalidateCompiled()

protected invalidateCompiled(): void 

invalidateCompiled clears compiled state when routes change

protected matchFromPosition()

protected matchFromPosition(
    array $segments,
    string $url,
    int $position
): bool 

matchFromPosition matches sequentially starting from a position in the sorted route map, used when compiled matching rejects a candidate

protected ruleObject()

protected ruleObject(string $name): Rule|null 

ruleObject returns a rule by name, hydrating it from raw config if needed