Core Routing Components

Purpose and Scope

This document provides an overview of the three core routing components in hypervel/router that work together to handle route definition, collection, and dispatching. These components form the foundation of the routing system:

• Router - Primary API for defining routes and managing parameter bindings
• RouteCollector - Collects and organizes route definitions with middleware and naming
• DispatcherFactory - Initializes routes and compiles them into executable dispatchers

For detailed information about specific aspects of these components, see:

• Router class methods and bindings: Router Class
• Route grouping and middleware assignment: Route Collection and Registration
• Route initialization and FastRoute integration: Route Dispatching and Initialization

For URL generation capabilities, which consume the routes defined by these components, see URL Generation System.

---

Three-Component Architecture

The routing system is organized into three collaborating components, each with distinct responsibilities:

Sources: src/Router.php1-189 src/RouteCollector.php1-183 src/DispatcherFactory.php1-51

---

Component Responsibilities

Component	Primary Role	Key Data Structures	File Reference
Router	Route definition API and parameter binding registry	modelBindings array, explicitBindings array	src/Router.php
RouteCollector	Route collection, organization, and storage	namedRoutes array, FastRoute dataGenerator	src/RouteCollector.php
DispatcherFactory	Route initialization, compilation, and caching	routers array (per-server collectors), initialized flag	src/DispatcherFactory.php

Router Class

The Router class (src/Router.php20) serves as the primary entry point for route definition. It provides:

• Route Definition Methods: Via __call magic method (src/Router.php49-54), delegates to RouteCollector methods like get(), post(), put(), etc.
• Parameter Binding Registry: Stores model bindings (src/Router.php29) and explicit bindings (src/Router.php36) for route parameter resolution
• Static Access: Via __callStatic (src/Router.php183-188), enables Router::get() static calls
• Server Management: Supports multi-server routing via serverName property (src/Router.php22)
• Current Route Access: Methods like current() (src/Router.php144-149), currentRouteName() (src/Router.php162-169)

RouteCollector Class

The RouteCollector class (src/RouteCollector.php13) extends Hyperf's base collector and adds:

• Named Route Storage: Maintains namedRoutes array (src/RouteCollector.php18) for URL generation
• Additional HTTP Methods: Adds options() (src/RouteCollector.php26-29), match() (src/RouteCollector.php37-40), any() (src/RouteCollector.php48-51)
• Route Registration: Core addRoute() method (src/RouteCollector.php53-81) integrates with FastRoute parser and middleware managers
• Prefix Merging: Handles route prefixes and group options (src/RouteCollector.php104-113)

DispatcherFactory Class

The DispatcherFactory class (src/DispatcherFactory.php13) extends Hyperf's base factory and adds:

• Route Initialization: initRoutes() method (src/DispatcherFactory.php22-37) loads route files at startup
• Lazy Initialization: Uses initialized flag (src/DispatcherFactory.php15) to defer route loading
• RouteCollector Management: getRouter() method (src/DispatcherFactory.php39-50) creates and caches collectors per server
• Annotation Integration: Constructor (src/DispatcherFactory.php17-20) initializes annotation-based routes

Sources: src/Router.php20-189 src/RouteCollector.php13-183 src/DispatcherFactory.php13-51

---

Route Definition to Dispatch Flow

The following sequence illustrates how a route travels through all three components from definition to runtime dispatch:

Key Stages:

1. Definition: Application calls Router::get(), Router::post(), etc. via static magic method
2. Delegation: Router delegates to RouteCollector for the current server via __call
3. Parsing: RouteCollector uses FastRoute parser to transform route patterns into route data
4. Storage: Route data stored in FastRoute DataGenerator, named routes stored in array, middleware registered
5. Initialization: DispatcherFactory lazily loads all route files on first request
6. Compilation: Route data compiled into FastRoute dispatcher for efficient matching

Sources: src/Router.php49-54 src/Router.php183-188 src/RouteCollector.php53-81 src/DispatcherFactory.php22-50

---

Integration with Framework Components

The three core components integrate with several Hyperf and external systems:

Dependency Injection Integration

All three components are registered with the Hyperf DI container via ConfigProvider:

Component	Binding Type	Container Key
DispatcherFactory	Singleton (replaces Hyperf's)	Hyperf\HttpServer\Router\DispatcherFactory::class
RouteCollector	Factory (per-server)	Created by DispatcherFactory::getRouter()
Router	Singleton	Hypervel\Router\Router::class

The Router constructor (src/Router.php38-40) receives DispatcherFactory via dependency injection, establishing the connection between components.

FastRoute Integration

The RouteCollector integrates with nikic/fast-route:

• Parser: Uses $this->routeParser (src/RouteCollector.php58) to parse route patterns
• DataGenerator: Uses $this->dataGenerator (src/RouteCollector.php68) to store route data
• RouteHandler: Wraps handlers in custom RouteHandler class (src/RouteCollector.php68) to preserve options

Middleware System Integration

Routes register middleware through two managers:

• MiddlewareManager: Stores middleware to apply (src/RouteCollector.php76)
• MiddlewareExclusionManager: Stores middleware to exclude (src/RouteCollector.php79)

See Middleware Configuration and Exclusions for details on how middleware is processed.

Server Name Routing

The system supports multiple HTTP servers via the serverName property:

The Router::addServer() method (src/Router.php42-47) temporarily changes the server name during route definition, allowing routes to be registered to different servers (e.g., HTTP vs WebSocket).

Sources: src/Router.php22 src/Router.php38-54 src/RouteCollector.php58-79 src/DispatcherFactory.php39-50

---

Parameter Binding System

The Router class maintains two types of parameter bindings used by the SubstituteBindings middleware:

Binding Storage

Binding Registration Methods

Method	Signature	Purpose	Line Reference
model()	model(string $param, string $modelClass): void	Register a model class for a parameter	src/Router.php104-115
bind()	bind(string $param, Closure $callback): void	Register a closure for custom resolution	src/Router.php120-123
getModelBinding()	getModelBinding(string $param): ?string	Retrieve model binding for parameter	src/Router.php128-131
getExplicitBinding()	getExplicitBinding(string $param): ?Closure	Retrieve explicit binding for parameter	src/Router.php136-139

The bindings are consulted by the SubstituteBindings middleware during request processing. See Route Parameter Binding and Model Binding and UrlRoutable for how these bindings are resolved.

Sources: src/Router.php29 src/Router.php36 src/Router.php104-139

---

Route File Loading

The DispatcherFactory supports loading routes from files via integration with RouteFileCollector:

The initialization process:

1. First Request: getRouter() (src/DispatcherFactory.php39) checks initialized flag
2. Load Files: initRoutes() (src/DispatcherFactory.php22) fetches files from RouteFileCollector
3. Require Files: Each file is required (src/DispatcherFactory.php33-36), executing route definitions
4. Mark Complete: initialized flag set to true (src/DispatcherFactory.php24)

The Router::group() method (src/Router.php59-68) can also accept a file path directly:

This delegates to registerRouteFile() (src/Router.php83-90), which returns a closure that requires the file.

Sources: src/DispatcherFactory.php22-37 src/Router.php59-90

---

Current Route Access

The Router provides methods to access information about the currently dispatched route:

Method	Return Type	Description	Line Reference
current()	?DispatchedRoute	Get current route instance	src/Router.php144-149
getCurrentRoute()	?DispatchedRoute	Alias for current()	src/Router.php154-157
currentRouteName()	?string	Get name of current route	src/Router.php162-169
input()	mixed	Get route parameter value	src/Router.php174-181

These methods retrieve the route from the current request context via ApplicationContext::getContainer()->get(Request::class)->route() (src/Router.php146-148).

Sources: src/Router.php144-181