App
in package
Central API application router and orchestrator.
The App class manages all API endpoints, coordinates request routing, and handles the startup sequence. It maintains a registry of endpoints organized by HTTP method, and dynamically routes incoming requests to matching handlers.
Key features:
- Method-based route grouping for efficient lookup
- Smart path pattern matching with parameter extraction
- Automatic route file loading during startup
- Clean separation of route definitions and execution
Startup flow:
- Parse request path into components
- Traverse directory structure looking for PHP files matching path segments
- Load a single matching PHP file to register routes
- Execute first matching route handler
- Return 404 if no route matches
Example: (requires server to route all requests to startup file,
with __p parameter containing the request path)
require_once('./sys/boot.php');
$app = new App('./root');
$app->get('/users', fn() => new UserList());
$app->post('/users', fn(CreateUserRequest $body) => new UserResponse());
$app->startup($_GET['__p']); // Start routing
Tags
Table of Contents
Properties
- $listeners : array<string, array<string|int, Api>>
- Route registry organized by HTTP method.
- $root : string
Methods
- __construct() : mixed
- Initialize the App with an optional root directory.
- add() : static
- Register a new endpoint for any HTTP method.
- delete() : static
- Register a DELETE endpoint.
- get() : static
- Register a GET endpoint.
- post() : static
- Register a POST endpoint.
- put() : static
- Register a PUT endpoint.
- report() : static
- Register a REPORT (CalDAV) endpoint.
- run() : never
- Route an incoming request to a matching handler.
- startup() : never
- Start the application and route the incoming request.
Properties
$listeners
Route registry organized by HTTP method.
protected
array<string, array<string|int, Api>>
$listeners
= []
Structure: ['GET' => [Api, Api, ...], 'POST' => [Api, ...], ...]
$root
protected
string
$root
= ''
Methods
__construct()
Initialize the App with an optional root directory.
public
__construct([string $root = '' ]) : mixed
Remember to call startup() to begin request processing in case of file-based routing, otherwise you can directly call run() after registering routes.
Parameters
- $root : string = ''
-
The root directory for file-based route loading. Routes can be split across multiple PHP files organized in a directory hierarchy matching URL paths.
add()
Register a new endpoint for any HTTP method.
public
add(HTTP $method, string $path, Closure $handler) : static
Low-level registration method. Prefer the convenience methods (get, post, etc.) unless you need dynamic method selection at runtime.
Parameters
- $method : HTTP
-
The HTTP method to respond to.
- $path : string
-
The URL path pattern. Use {name:i} for int, {name:s} for string.
- $handler : Closure
-
The request handler. Return value is automatically serialized.
Return values
static —Fluent interface for chaining.
delete()
Register a DELETE endpoint.
public
delete(string $path, Closure $handler) : static
Parameters
- $path : string
-
The URL path pattern.
- $handler : Closure
-
The request handler.
Return values
static —Fluent interface for chaining.
get()
Register a GET endpoint.
public
get(string $path, Closure $handler) : static
Parameters
- $path : string
-
The URL path pattern.
- $handler : Closure
-
The request handler.
Return values
static —Fluent interface for chaining.
post()
Register a POST endpoint.
public
post(string $path, Closure $handler) : static
Parameters
- $path : string
-
The URL path pattern.
- $handler : Closure
-
The request handler.
Return values
static —Fluent interface for chaining.
put()
Register a PUT endpoint.
public
put(string $path, Closure $handler) : static
Parameters
- $path : string
-
The URL path pattern.
- $handler : Closure
-
The request handler.
Return values
static —Fluent interface for chaining.
report()
Register a REPORT (CalDAV) endpoint.
public
report(string $path, Closure $handler) : static
Parameters
- $path : string
-
The URL path pattern.
- $handler : Closure
-
The request handler.
Return values
static —Fluent interface for chaining.
run()
Route an incoming request to a matching handler.
public
run(string $path) : never
Iterates through registered endpoints for the current HTTP method, testing each against the request path. The first match is executed.
The matching process:
- Get all listeners (endpoint handlers) for the current HTTP method
- Test each listener's path pattern against the incoming path
- Extract path parameters if the pattern includes them
- Execute the first matching handler
- If no handler matches, throw NotFoundException
Parameters
- $path : string
-
The request path (typically from URL parsing).
Tags
Return values
never —Always terminates execution via Api::run() or NotFoundException.
startup()
Start the application and route the incoming request.
public
startup(string $path) : never
This is the main entry point in case of file-based routing. It handles the complete startup sequence:
- Path Validation: Ensures the path is safe (no
..,.,\0) - Directory Traversal: Walks the directory structure following the URL path like a normal file server would
- File Loading: Automagically find and load a single PHP file along the path to register routes
- Route Matching: Passes remaining path components to route handlers
- Error Handling: Returns 404 if path is invalid or no file matches
Directory structure example:
root/
index.php → Loaded first, can register routes
user.php → Loaded for /user requests
user/
index.php → Loaded for /user/* requests
profile.php → Loaded for /user/profile requests
Security: Prevents directory traversal attacks by rejecting path components
containing .., ., or null bytes.
Parameters
- $path : string
-
The request path from URL parsing (typically
$_GET['__p']).
Tags
Return values
never —Always terminates execution via run() or NotFoundException.