Routing

The Route facade provides a Laravel-style API for defining HTTP routes in Hypervel applications. It wraps Hyperf's routing infrastructure with methods for registering routes via HTTP verb helpers, organizing routes into groups, binding route parameters to models, and managing named routes.

Related Pages:

• For handling incoming HTTP requests, see page 4.1 (Request and Response)
• For URL generation from named routes, see page 4.4 (URL Generation)
• For the facade architecture pattern, see page 3.2 (Facade System)

Facade Architecture

The Route facade delegates to Hypervel\Router\Router, which wraps Hyperf's routing system. The delegation chain flows from static facade methods through the router to Hyperf's underlying route collector.

Diagram: Route Facade Delegation and Storage

Component	Class	Purpose
Facade	Hypervel\Support\Facades\Route	Static interface to routing
Router	Hypervel\Router\Router	Laravel-compatible routing API
Route Collector	Hyperf\HttpServer\Router\RouteCollector	Hyperf's route registration
Route Parser	FastRoute\RouteParser	FastRoute pattern parsing

The facade's getFacadeAccessor() method returns Router::class, which the container resolves to the Hypervel\Router\Router instance.

Sources: src/Facades/Route.php1-47

Route Registration

HTTP Verb Methods

Routes are registered using HTTP verb methods that correspond to standard HTTP methods. Each method accepts a route path, handler (callable, string, or array), and optional configuration array.

Diagram: HTTP Verb Method Delegation

Method	HTTP Verb(s)	Signature
get()	GET	get(string $route, callable|string|array|null $handler, array $options = [])
post()	POST	post(string $route, callable|string|array|null $handler, array $options = [])
put()	PUT	put(string $route, callable|string|array|null $handler, array $options = [])
delete()	DELETE	delete(string $route, callable|string|array|null $handler, array $options = [])
patch()	PATCH	patch(string $route, callable|string|array|null $handler, array $options = [])
head()	HEAD	head(string $route, callable|string|array|null $handler, array $options = [])
options()	OPTIONS	options(string $route, string|array $handler, array $options = [])
match()	Array of verbs	match(array $methods, string $route, string|array $handler, array $options = [])
any()	All verbs	any(string $route, string|array $handler, array $options = [])

All methods internally call addRoute(string|string[] $httpMethod, string $route, array|string $handler, array $options = []), which delegates to Hyperf's RouteCollector.

Sources: src/Facades/Route.php22-33

Route Parameters

Routes support dynamic parameters using curly brace syntax (e.g., /users/{id}, /posts/{post}/comments/{comment}). Parameters are extracted during request matching by FastRoute and can be resolved through:

1. Route model binding - Automatically resolve parameters to model instances
2. Explicit binding - Use custom Closure logic for parameter resolution
3. Direct access - Retrieve raw parameter values via Route::input()

The input(string $key, string|null $default = null) method retrieves a specific route parameter value, returning the default if the parameter is not present.

Sources: src/Facades/Route.php21

Route Options

The $options array parameter configures route behavior. Options are passed to the underlying Hyperf router and may include:

• name - Assigns a name to the route for URL generation
• middleware - Attaches middleware to the route
• Additional Hyperf-specific configuration

Sources: src/Facades/Route.php22-33

Route Groups

Route groups organize multiple routes under a common prefix and shared configuration. Both group() and addGroup() methods provide this functionality as aliases.

Diagram: Route Group Structure and Nesting

Method Signatures

Route::group(string $prefix, callable|string $source, array $options = [])
Route::addGroup(string $prefix, callable|string $source, array $options = [])

Parameters

Parameter	Type	Description
$prefix	string	URI prefix prepended to all routes in the group (e.g., /admin, /api/v1)
$source	callable|string	Either a Closure containing route definitions or a file path to load
$options	array	Configuration array (middleware, name prefix, etc.)

Nested Groups

Groups can be nested by calling group() or addGroup() within another group's callback. Prefixes concatenate and options merge through nested groups.

Sources: src/Facades/Route.php11-12

Parameter Binding

Parameter binding automatically resolves route parameters to objects during request handling. The router supports two binding types: implicit model binding and explicit custom binding.

Diagram: Parameter Binding Registration and Resolution

Model Binding

The model(string $param, string $modelClass) method registers implicit model binding. When a route parameter name matches $param, the router automatically resolves it to an instance of $modelClass by the parameter value (typically by primary key).

Route::model('user', \App\Models\User::class);
Route::get('/users/{user}', [UserController::class, 'show']);
// {user} parameter automatically resolves to User instance

The getModelBinding(string $param) method retrieves the registered model class name for a parameter, returning null if no binding exists.

Sources: src/Facades/Route.php14-16

Explicit Binding

The bind(string $param, \Closure $callback) method registers custom resolution logic. The Closure receives the parameter value and returns the resolved instance.

Route::bind('post', function ($value) {
 return Post::where('slug', $value)->firstOrFail();
});
Route::get('/posts/{post}', [PostController::class, 'show']);
// {post} parameter resolved via custom Closure

The getExplicitBinding(string $param) method retrieves the registered Closure for a parameter, returning null if no binding exists.

Sources: src/Facades/Route.php15-17

Named Routes

Named routes enable URL generation without hardcoding paths. Routes receive names via the name option in the $options array.

Diagram: Named Route Registration and Usage

Checking Route Existence

Route::has(array|string $name): bool

The has() method checks whether route name(s) exist. It accepts a string or array of route names and returns true only if all specified routes are registered.

if (Route::has('users.show')) {
 // Route exists
}

if (Route::has(['users.index', 'users.show'])) {
 // All routes exist
}

Sources: src/Facades/Route.php35

Retrieving All Named Routes

Route::getNamedRoutes(): array

The getNamedRoutes() method returns an associative array mapping route names to their route data. This enables inspection and debugging of the application's named routes.

Sources: src/Facades/Route.php34

Route Introspection

The router provides methods for accessing information about the currently matched route during request handling.

Diagram: Current Route Introspection

Current Route Object

Route::current(): \Hypervel\Http\DispatchedRoute|null
Route::getCurrentRoute(): \Hypervel\Http\DispatchedRoute|null

Both methods return the current Hypervel\Http\DispatchedRoute instance or null if no route is matched. These are aliases providing identical functionality.

The DispatchedRoute object contains the matched route's name, parameters, handler, middleware, and other metadata.

Sources: src/Facades/Route.php18-19

Current Route Name

Route::currentRouteName(): string|null

Returns the name of the currently matched route or null if the route is unnamed or no route is matched.

if (Route::currentRouteName() === 'users.show') {
 // Currently on users.show route
}

Sources: src/Facades/Route.php20

Route Parameter Access

Route::input(string $key, string|null $default = null): mixed

Retrieves a route parameter value by key. Returns the $default value if the parameter doesn't exist. This provides direct parameter access without retrieving the full DispatchedRoute object.

$userId = Route::input('id');
$slug = Route::input('slug', 'default-slug');

Sources: src/Facades/Route.php21

Multi-Server Configuration

For applications running multiple HTTP servers (e.g., separate public API and admin servers), the router supports server-specific route registration.

Route::addServer(string $serverName, callable $callback): void

The addServer() method registers routes for a specific named server. The $callback receives routing methods scoped to that server.

// Register routes for 'api' server
Route::addServer('api', function () {
 Route::get('/users', [UserController::class, 'index']);
 Route::get('/posts', [PostController::class, 'index']);
});

// Register routes for 'admin' server
Route::addServer('admin', function () {
 Route::get('/dashboard', [DashboardController::class, 'index']);
});

This enables server-specific route definitions when Hyperf is configured with multiple HTTP servers via config/server.php.

Sources: src/Facades/Route.php10

Integration with Hyperf

The Route facade wraps Hyperf's routing infrastructure while providing a Laravel-compatible API. The underlying Router class delegates to Hyperf components for route matching and dispatching.

Component	Purpose	Access Method
RouteCollector	Hyperf's route collector	getRouter()
RouteParser	FastRoute parser	getRouteParser()
Route data	Collected routes	getData()

The getRouter() method returns the underlying Hyperf\HttpServer\Router\RouteCollector instance for direct access to Hyperf routing features. The getRouteParser() method returns the FastRoute\RouteParser instance used for parsing route patterns. The getData() method returns the raw route data array collected by the router.

Sources: src/Facades/Route.php13-30