Documentation

Router
in package

Simple Router for LWT Front Controller

Handles routing URLs to controller-based handlers

Tags
category

Lwt

author

HugoFara hugo.farajallah@protonmail.com

license

Unlicense http://unlicense.org/

link
https://hugofara.github.io/lwt/docs/php/
since
3.0.0

Table of Contents

Constants

PARAM_TYPES  = ['int' => '[0-9]+', 'alpha' => '[a-zA-Z]+', 'alphanum' => '[a-zA-Z0-9]+', 'slug' => '[a-zA-Z0-9_-]+', 'uuid' => '[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}']
Route parameter type constraints.

Properties

$basePath  : string
Base path for resolving file paths.
$container  : Container|null
The dependency injection container.
$middleware  : array<string, array<string, array<string|int, MiddlewareInterface|string>>>
Middleware stack for routes.
$prefixMiddleware  : array<string, array<string, array<string|int, MiddlewareInterface|string>>>
Middleware stack for prefix routes.
$prefixRoutes  : array<string, array<string, string>>
Prefix-based routes.
$routeParamTypes  : array<string, array<string, string>>
Store parameter types for routes.
$routes  : array<string, array<string, string>>
Registered routes.

Methods

__construct()  : mixed
Create a new Router instance.
delete()  : void
Register a DELETE route.
execute()  : void
Execute the resolved handler
get()  : void
Register a GET route.
match()  : void
Register routes for multiple HTTP methods.
patch()  : void
Register a PATCH route.
post()  : void
Register a POST route.
put()  : void
Register a PUT route.
register()  : void
Register a route
registerPrefix()  : void
Register a prefix route (matches all paths starting with prefix)
registerPrefixWithMiddleware()  : void
Register a prefix route with middleware.
registerWithMiddleware()  : void
Register a route with middleware.
resolve()  : array<string, mixed>
Resolve the current request to a handler.
buildMethodArguments()  : array<int, mixed>
Build method arguments using reflection.
coerceParams()  : array<string, mixed>
Coerce route parameters to their declared types.
convertPatternToRegex()  : non-empty-string
Convert route pattern to regex.
executeController()  : void
Execute a controller method with parameter injection.
executeFile()  : void
Execute a legacy file
executeHandler()  : void
Execute a handler (file include or controller method)
executeMiddleware()  : bool
Execute the middleware chain.
getMimeType()  : string
Get MIME type for a file
handle404()  : never
Handle 404 Not Found
handle500()  : never
Handle 500 Internal Server Error
resolveController()  : object
Resolve a controller instance from the container or create directly.
resolveMiddleware()  : MiddlewareInterface
Resolve a middleware to an instance.
resolveStaticAsset()  : array{type: "static", file: string, mime: string}|null
Resolve static asset requests
serveStaticFile()  : void
Serve a static file with proper headers

Constants

PARAM_TYPES

Route parameter type constraints.

private array<string, string> PARAM_TYPES = ['int' => '[0-9]+', 'alpha' => '[a-zA-Z]+', 'alphanum' => '[a-zA-Z0-9]+', 'slug' => '[a-zA-Z0-9_-]+', 'uuid' => '[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}']

Maps type names to regex patterns.

Properties

$basePath

Base path for resolving file paths.

private string $basePath

$container

The dependency injection container.

private Container|null $container

$middleware

Middleware stack for routes.

private array<string, array<string, array<string|int, MiddlewareInterface|string>>> $middleware = []

Structure: ['path' => ['method' => [middleware1, middleware2, ...]]]

$prefixMiddleware

Middleware stack for prefix routes.

private array<string, array<string, array<string|int, MiddlewareInterface|string>>> $prefixMiddleware = []

$prefixRoutes

Prefix-based routes.

private array<string, array<string, string>> $prefixRoutes = []

Structure: ['prefix' => ['method' => 'ControllerClass::method']]

$routeParamTypes

Store parameter types for routes.

private array<string, array<string, string>> $routeParamTypes = []

Structure: ['pattern' => ['param_name' => 'type']]

$routes

Registered routes.

private array<string, array<string, string>> $routes = []

Structure: ['path' => ['method' => 'ControllerClass::method']]

Methods

__construct()

Create a new Router instance.

public __construct(string $basePath[, Container|null $container = null ]) : mixed
Parameters
$basePath : string

Base path for resolving file paths

$container : Container|null = null

Optional DI container for resolving controllers

delete()

Register a DELETE route.

public delete(string $path, string $handler[, array<string|int, MiddlewareInterface|string> $middleware = [] ]) : void
Parameters
$path : string

The URL path (supports {param} placeholders)

$handler : string

The handler (controller@method)

$middleware : array<string|int, MiddlewareInterface|string> = []

Optional middleware

Tags
psalm-suppress

PossiblyUnusedMethod - Public API for route registration

execute()

Execute the resolved handler

public execute(array<string, mixed> $resolution) : void
Parameters
$resolution : array<string, mixed>

Result from resolve()

Tags
psalm-suppress

MixedAssignment,MixedArgument,MixedArrayAccess - Dynamic route resolution

psalm-suppress

PossiblyUnusedMethod - Called from Application::run()

get()

Register a GET route.

public get(string $path, string $handler[, array<string|int, MiddlewareInterface|string> $middleware = [] ]) : void

Convenience method for registering GET-only routes.

Parameters
$path : string

The URL path (supports {param} placeholders)

$handler : string

The handler (controller@method)

$middleware : array<string|int, MiddlewareInterface|string> = []

Optional middleware

match()

Register routes for multiple HTTP methods.

public match(array<string|int, string> $methods, string $path, string $handler[, array<string|int, MiddlewareInterface|string> $middleware = [] ]) : void
Parameters
$methods : array<string|int, string>

HTTP methods (GET, POST, etc.)

$path : string

The URL path

$handler : string

The handler

$middleware : array<string|int, MiddlewareInterface|string> = []

Optional middleware

Tags
psalm-suppress

PossiblyUnusedMethod - Public API for route registration

patch()

Register a PATCH route.

public patch(string $path, string $handler[, array<string|int, MiddlewareInterface|string> $middleware = [] ]) : void
Parameters
$path : string

The URL path (supports {param} placeholders)

$handler : string

The handler (controller@method)

$middleware : array<string|int, MiddlewareInterface|string> = []

Optional middleware

Tags
psalm-suppress

PossiblyUnusedMethod - Public API for route registration

post()

Register a POST route.

public post(string $path, string $handler[, array<string|int, MiddlewareInterface|string> $middleware = [] ]) : void
Parameters
$path : string

The URL path (supports {param} placeholders)

$handler : string

The handler (controller@method)

$middleware : array<string|int, MiddlewareInterface|string> = []

Optional middleware

Tags
psalm-suppress

PossiblyUnusedMethod - Public API for route registration

put()

Register a PUT route.

public put(string $path, string $handler[, array<string|int, MiddlewareInterface|string> $middleware = [] ]) : void
Parameters
$path : string

The URL path (supports {param} placeholders)

$handler : string

The handler (controller@method)

$middleware : array<string|int, MiddlewareInterface|string> = []

Optional middleware

register()

Register a route

public register(string $path, string $handler[, string $method = '*' ]) : void
Parameters
$path : string

The URL path

$handler : string

The handler (file path or controller@method)

$method : string = '*'

HTTP method (GET, POST, or *)

registerPrefix()

Register a prefix route (matches all paths starting with prefix)

public registerPrefix(string $prefix, string $handler[, string $method = '*' ]) : void
Parameters
$prefix : string

The URL prefix (e.g., '/api/v1')

$handler : string

The handler (file path or method)

$method : string = '*'

HTTP method (GET, POST, or *)

registerPrefixWithMiddleware()

Register a prefix route with middleware.

public registerPrefixWithMiddleware(string $prefix, string $handler, array<string|int, MiddlewareInterface|string> $middleware[, string $method = '*' ]) : void
Parameters
$prefix : string

The URL prefix (e.g., '/api/v1')

$handler : string

The handler (file path or method)

$middleware : array<string|int, MiddlewareInterface|string>

Array of middleware class names or instances

$method : string = '*'

HTTP method (GET, POST, or *)

Tags
psalm-suppress

PossiblyUnusedMethod - Public API for route registration

registerWithMiddleware()

Register a route with middleware.

public registerWithMiddleware(string $path, string $handler, array<string|int, MiddlewareInterface|string> $middleware[, string $method = '*' ]) : void
Parameters
$path : string

The URL path

$handler : string

The handler (file path or controller@method)

$middleware : array<string|int, MiddlewareInterface|string>

Array of middleware class names or instances

$method : string = '*'

HTTP method (GET, POST, or *)

resolve()

Resolve the current request to a handler.

public resolve() : array<string, mixed>
Tags
psalm-return

array{ type: 'handler'|'not_found'|'redirect'|'static', path?: string, url?: string, code?: 301, handler?: string, params?: array<array-key, mixed>, routeParams?: array<string, mixed>, file?: string, mime?: string, middleware?: array<MiddlewareInterface|string> }

Return values
array<string, mixed> —

Resolution array with type and handler info

buildMethodArguments()

Build method arguments using reflection.

private buildMethodArguments(string $controllerClass, string $method, array<string, mixed> $params, array<string, mixed> $routeParams) : array<int, mixed>

Matches route parameters to method parameter names. Falls back to passing the full params array for legacy compatibility.

Parameters
$controllerClass : string

Controller class name

$method : string

Method name

$params : array<string, mixed>

All parameters

$routeParams : array<string, mixed>

Route parameters

Tags
psalm-suppress

MixedAssignment - Dynamic argument building via reflection

Return values
array<int, mixed> —

Ordered arguments for the method

coerceParams()

Coerce route parameters to their declared types.

private coerceParams(string $routePattern, array<string, mixed> $params) : array<string, mixed>
Parameters
$routePattern : string

The original route pattern

$params : array<string, mixed>

The extracted parameters

Tags
psalm-suppress

MixedAssignment - Dynamic type coercion by design

Return values
array<string, mixed> —

Parameters with types coerced

convertPatternToRegex()

Convert route pattern to regex.

private convertPatternToRegex(string $pattern) : non-empty-string

Supports:

  • Basic params: {id} - matches any non-slash characters
  • Typed params: {id:int} - matches only digits
  • Optional params: {id?} or {id:int?} - makes the param optional

Available types: int, alpha, alphanum, slug, uuid

Parameters
$pattern : string

Route pattern (e.g., '/text/{id}', '/user/{id:int}')

Return values
non-empty-string —

Regex pattern

executeController()

Execute a controller method with parameter injection.

private executeController(string $controllerClass, string $method, array<string, mixed> $params[, array<string, mixed> $routeParams = [] ]) : void

Route parameters are injected as method arguments by name. The method can also accept a $params array for all parameters.

Examples:

  • Route: /text/{id:int} -> Method: read(int $id)
  • Route: /user/{id}/post/{slug} -> Method: show(int $id, string $slug)
  • Legacy: Method: index(array $params) still works
Parameters
$controllerClass : string

Controller class name

$method : string

Method name

$params : array<string, mixed>

All parameters (query + route)

$routeParams : array<string, mixed> = []

Route parameters for injection

executeFile()

Execute a legacy file

private executeFile(string $filePath, array<string|int, mixed> $params) : void
Parameters
$filePath : string

Path to PHP file or static file

$params : array<string|int, mixed>

Parameters (available to file)

executeHandler()

Execute a handler (file include or controller method)

private executeHandler(string $handler, array<string, mixed> $params[, array<string, mixed> $routeParams = [] ]) : void
Parameters
$handler : string

Handler string

$params : array<string, mixed>

All request parameters (query + route)

$routeParams : array<string, mixed> = []

Route parameters only (for injection)

executeMiddleware()

Execute the middleware chain.

private executeMiddleware(array<string|int, MiddlewareInterface|string> $middlewareList) : bool
Parameters
$middlewareList : array<string|int, MiddlewareInterface|string>

List of middleware class names or instances

Return values
bool —

True if all middleware passed, false if halted

getMimeType()

Get MIME type for a file

private getMimeType(string $filePath) : string
Parameters
$filePath : string

Path to file

Return values
string —

MIME type

handle404()

Handle 404 Not Found

private handle404(string $path) : never
Parameters
$path : string

Requested path

Return values
never

handle500()

Handle 500 Internal Server Error

private handle500(string $message) : never
Parameters
$message : string

Error message

Return values
never

resolveController()

Resolve a controller instance from the container or create directly.

private resolveController(class-string $controllerClass) : object
Parameters
$controllerClass : class-string

The fully qualified controller class name

Tags
psalm-suppress

MixedInferredReturnType,MixedReturnStatement - Dynamic instantiation

Return values
object —

The controller instance

resolveStaticAsset()

Resolve static asset requests

private resolveStaticAsset(string $path) : array{type: "static", file: string, mime: string}|null

Maps legacy paths to new asset locations:

  • /css/* -> /assets/css/*
  • /img/* -> /assets/images/*
  • /js/* -> /assets/js/*
  • /assets/* -> /assets/* (direct access)
  • /docs/* -> /docs/* (documentation)
  • /favicon.ico -> /favicon.ico
Parameters
$path : string

Request path

Return values
array{type: "static", file: string, mime: string}|null —

Resolution array or null if not a static asset

serveStaticFile()

Serve a static file with proper headers

private serveStaticFile(string $filePath, string $mimeType) : void
Parameters
$filePath : string

Full path to the file

$mimeType : string

MIME type of the file


        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results