Neuron-PHP

Router extends Memory
in package
implements IRunnable

Core HTTP routing engine for the Neuron framework.

This singleton router manages HTTP request routing, URL pattern matching, parameter extraction, and filter execution. It provides a centralized system for mapping HTTP requests to controller actions with support for:

  • RESTful HTTP methods (GET, POST, PUT, DELETE)
  • Dynamic route parameters (e.g., /user/:id)
  • Route filters for pre/post processing
  • Flexible parameter extraction and validation
  • URI normalization and processing

The router follows a singleton pattern ensuring consistent routing state across the entire application lifecycle.

Tags
example 
$router = Router::instance();

// Register routes
$router->get('/users', 'UserController@index');
$router->post('/users', 'UserController@create');
$router->get('/users/:id', 'UserController@show');

// Register filters
$router->registerFilter('auth', new AuthFilter());

// Execute routing
$router->run();

Table of Contents

Interfaces

IRunnable
Interface to add runnable behavior to an object.

Properties

$_instance  : mixed
$_delete  : array<string|int, mixed>
$_filter  : array<string|int, mixed>
$_filterRegistry  : array<string|int, mixed>
$_get  : array<string|int, mixed>
$_ipResolver  : IIpResolver|null
$_post  : array<string|int, mixed>
$_put  : array<string|int, mixed>
$_registeredNames  : array<string|int, mixed>
$_registeredRoutes  : array<string|int, mixed>
$_strictMode  : bool
$_urlRewrites  : array<string|int, mixed>

Methods

addFilter()  : void
clearRoutes()  : void
Clear all registered routes and filters.
delete()  : RouteMap
dispatch()  : mixed
generateUrl()  : string|null
Generate a URL for a named route with optional parameters.
get()  : RouteMap
getAllNamedRoutes()  : array<string|int, mixed>
Get all routes with their names for debugging/inspection.
getFilter()  : Filter
getInstance()  : ISingleton|null
getRoute()  : RouteMap|null
getRouteByName()  : RouteMap|null
Find a route by name across all HTTP methods.
instance()  : mixed
Gets the global object instance.
invalidate()  : void
Clears the current global object.
post()  : RouteMap
put()  : RouteMap
registerFilter()  : void
registerRouteName()  : void
Register a route name and check for duplicates (called by RouteMap::setName).
run()  : mixed
Generic run method.
serialize()  : void
Writes the object data to the storage medium.
setIpResolver()  : void
Set the IP resolver for all requests handled by this router.
setStrictMode()  : void
Enable or disable strict mode for duplicate route detection.
setUrlRewrites()  : void
Set URL rewrite rules.
unregisterRouteName()  : void
Unregister a route name (called by RouteMap::setName when renaming).
addRoute()  : RouteMap
checkDuplicateRoute()  : void
Check if a route is a duplicate and throw exception if found (in strict mode).
executePostFilters()  : void
executePreFilters()  : mixed
extractControllerInfo()  : string
Extract controller information from a route for error messages.
extractRouteParams()  : array<string|int, mixed>
Populates a param array with the data from the uri.
getRouteArray()  : array<string|int, mixed>
Returns a list of routes mapped to the current request method.
hasWildcard()  : bool
Check if route contains a wildcard parameter
isRouteWithParams()  : bool
processRoute()  : array<string|int, mixed>|null
processRouteWithParameters()  : array<string|int, mixed>
rewriteUrl()  : string
Rewrite a URL according to configured rewrite rules.
sanitizeUrlForLogging()  : string
Sanitize a URL for logging by removing query strings and fragments.
validateExistingRoutes()  : void
Validate all existing routes for duplicates.

Properties

$_instance

public static mixed $_instance = []

$_delete

private array<string|int, mixed> $_delete = []

$_filter

private array<string|int, mixed> $_filter = []

$_filterRegistry

private array<string|int, mixed> $_filterRegistry = []

$_get

private array<string|int, mixed> $_get = []

$_post

private array<string|int, mixed> $_post = []

$_put

private array<string|int, mixed> $_put = []

$_registeredNames

private array<string|int, mixed> $_registeredNames = []

Track registered route names: ['name' => 'method:path']

$_registeredRoutes

private array<string|int, mixed> $_registeredRoutes = []

Track registered routes to detect duplicates: ['method:path' => 'controller@action']

$_strictMode

private bool $_strictMode = true

Enable strict duplicate checking (throws exceptions)

$_urlRewrites

private array<string|int, mixed> $_urlRewrites = []

URL rewrites: ['/from' => '/to']

Methods

addFilter()

public addFilter(string $filter) : void
Parameters
$filter : string

clearRoutes()

Clear all registered routes and filters.

public clearRoutes() : void

This method resets the router to its initial state, removing all registered routes, route names, filters, and URL rewrites. Useful for testing or when you need to reconfigure routing from scratch.

delete()

public delete(string $route, mixed $function[, string|array<string|int, mixed>|null $filters = null ][, string|null $name = null ]) : RouteMap
Parameters
$route : string
$function : mixed
$filters : string|array<string|int, mixed>|null = null
$name : string|null = null
Tags
throws
Exception
Return values
RouteMap

generateUrl()

Generate a URL for a named route with optional parameters.

public generateUrl(string $name[, array<string|int, mixed> $parameters = [] ][, bool $absolute = false ]) : string|null
Parameters
$name : string

The route name

$parameters : array<string|int, mixed> = []

Parameters to substitute in the route path

$absolute : bool = false

Whether to return an absolute URL

Return values
string|null —

The generated URL or null if route not found

get()

public get(string $route, mixed $function[, string|array<string|int, mixed>|null $filters = null ][, string|null $name = null ]) : RouteMap
Parameters
$route : string
$function : mixed
$filters : string|array<string|int, mixed>|null = null
$name : string|null = null
Tags
throws
Exception
Return values
RouteMap

getAllNamedRoutes()

Get all routes with their names for debugging/inspection.

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

Array of route information

getFilter()

public getFilter(string $routeName) : Filter
Parameters
$routeName : string
Tags
throws
Exception
Return values
Filter

getRoute()

public getRoute(int $method, string $uri) : RouteMap|null
Parameters
$method : int
$uri : string
Tags
throws
Exception
Return values
RouteMap|null

getRouteByName()

Find a route by name across all HTTP methods.

public getRouteByName(string $name) : RouteMap|null
Parameters
$name : string

The route name to search for

Return values
RouteMap|null —

The route if found, null otherwise

instance()

Gets the global object instance.

public static instance() : mixed

invalidate()

Clears the current global object.

public static invalidate() : void

post()

public post(string $route, mixed $function[, string|array<string|int, mixed>|null $filters = null ][, string|null $name = null ]) : RouteMap
Parameters
$route : string
$function : mixed
$filters : string|array<string|int, mixed>|null = null
$name : string|null = null
Tags
throws
Exception
Return values
RouteMap

put()

public put(string $route, mixed $function[, string|array<string|int, mixed>|null $filters = null ][, string|null $name = null ]) : RouteMap
Parameters
$route : string
$function : mixed
$filters : string|array<string|int, mixed>|null = null
$name : string|null = null
Tags
throws
Exception
Return values
RouteMap

registerFilter()

public registerFilter(string $name, Filter $filter) : void
Parameters
$name : string
$filter : Filter

registerRouteName()

Register a route name and check for duplicates (called by RouteMap::setName).

public registerRouteName(string $name, string $method, string $path, RouteMap $route) : void

This method is called when a route name is set via the fluent API, allowing duplicate name detection to work properly even when names are set after route registration.

In strict mode, duplicate names throw an exception. In non-strict mode, the first registered name wins (subsequent attempts to register the same name are silently ignored).

Parameters
$name : string

The route name to register

$method : string

The HTTP method (GET, POST, PUT, DELETE)

$path : string

The route path

$route : RouteMap

The route being named

Tags
throws
DuplicateRouteException

If name is already in use and strict mode is enabled

run()

Generic run method.

public run([array<string|int, mixed> $argv = [] ]) : mixed
Parameters
$argv : array<string|int, mixed> = []
Tags
throws
Exception
Return values
mixed —

result of route lambda.

serialize()

Writes the object data to the storage medium.

public serialize() : void

setIpResolver()

Set the IP resolver for all requests handled by this router.

public setIpResolver(IIpResolver $resolver) : void
Parameters
$resolver : IIpResolver

The IP resolver to use

setStrictMode()

Enable or disable strict mode for duplicate route detection.

public setStrictMode(bool $strict) : void

When strict mode is enabled (default), duplicate routes will throw a DuplicateRouteException. When disabled, duplicates are silently allowed (first match wins behavior).

When enabling strict mode, this method validates all existing routes and throws an exception if any duplicates are found.

Parameters
$strict : bool

Enable strict duplicate checking

Tags
throws
DuplicateRouteException

If duplicates exist when enabling strict mode

setUrlRewrites()

Set URL rewrite rules.

public setUrlRewrites(array<string|int, mixed> $rewrites) : void

URL rewrites are applied before route matching, transparently rewriting incoming URLs to different paths without HTTP redirects. This is useful for handling legacy URLs, providing clean URLs, or allowing packages to define default routes that can be overridden by applications.

Parameters
$rewrites : array<string|int, mixed>

Associative array of ['/from' => '/to'] mappings

Tags
example 
$router->setUrlRewrites([
    '/' => '/home/members',      // Root goes to members homepage
    '/index' => '/home/members', // Legacy URL also redirected
    '/blog' => '/posts'          // Clean URL mapping
]);

unregisterRouteName()

Unregister a route name (called by RouteMap::setName when renaming).

public unregisterRouteName(string $name) : void

This method is called when a route's name is being changed, allowing the old name to be removed from the registry before registering the new name.

Parameters
$name : string

The route name to unregister

addRoute()

protected addRoute(array<string|int, mixed> &$routes, string $method, string $routeName, mixed $function, mixed $filters[, string|null $name = null ]) : RouteMap
Parameters
$routes : array<string|int, mixed>
$method : string

HTTP method (GET, POST, PUT, DELETE)

$routeName : string
$function : mixed
$filters : mixed

string|array

$name : string|null = null

Optional route name (for duplicate detection)

Tags
throws
Exception
Return values
RouteMap

checkDuplicateRoute()

Check if a route is a duplicate and throw exception if found (in strict mode).

protected checkDuplicateRoute(RouteMap $route, string $method) : void

This method always registers the route signature for tracking. In strict mode, it throws an exception if a duplicate is found. In non-strict mode, the first registered route wins and subsequent duplicates are allowed (first match wins).

Parameters
$route : RouteMap

The route being added

$method : string

The HTTP method (GET, POST, PUT, DELETE)

Tags
throws
DuplicateRouteException

If duplicate found and strict mode is enabled

extractControllerInfo()

Extract controller information from a route for error messages.

protected extractControllerInfo(RouteMap $route) : string
Parameters
$route : RouteMap
Return values
string

extractRouteParams()

Populates a param array with the data from the uri.

protected extractRouteParams(string $uri, array<string|int, mixed> $details) : array<string|int, mixed>
Parameters
$uri : string
$details : array<string|int, mixed>
Return values
array<string|int, mixed>

getRouteArray()

Returns a list of routes mapped to the current request method.

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

hasWildcard()

Check if route contains a wildcard parameter

protected hasWildcard(RouteMap $route) : bool
Parameters
$route : RouteMap
Return values
bool

isRouteWithParams()

protected isRouteWithParams(RouteMap $route) : bool
Parameters
$route : RouteMap
Return values
bool

processRoute()

protected processRoute(RouteMap $route, mixed $uri) : array<string|int, mixed>|null
Parameters
$route : RouteMap
$uri : mixed
Tags
throws
Exception
Return values
array<string|int, mixed>|null

processRouteWithParameters()

protected processRouteWithParameters(RouteMap $route, string $uri) : array<string|int, mixed>
Parameters
$route : RouteMap
$uri : string
Tags
throws
Exception
Return values
array<string|int, mixed>

rewriteUrl()

Rewrite a URL according to configured rewrite rules.

protected rewriteUrl(string $url) : string

This applies URL rewrites transparently before route matching. Rewrites are exact matches only (no pattern matching). The rewritten URL is used for route matching, but the original URL remains visible to the client.

Parameters
$url : string

The incoming URL to potentially rewrite

Return values
string —

The rewritten URL, or original URL if no rewrite applies

sanitizeUrlForLogging()

Sanitize a URL for logging by removing query strings and fragments.

protected sanitizeUrlForLogging(string $url) : string

This prevents sensitive tokens, API keys, or other data from being logged inadvertently.

Parameters
$url : string

The URL to sanitize

Return values
string —

The sanitized URL (path only)

validateExistingRoutes()

Validate all existing routes for duplicates.

protected validateExistingRoutes() : void

This rebuilds the route and name registries from scratch and throws an exception if any duplicates are found.

Tags
throws
DuplicateRouteException

If duplicates are found


        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results