Overview

This document provides an introduction to the Hypervel Router package, explaining its purpose, key features, and integration with the Hyperf framework. The Hypervel Router is a routing component that extends Hyperf's native routing capabilities with advanced features like signed URLs, model binding, and rate limiting middleware.

For detailed information about specific components:

• Core routing mechanics are covered in Core Routing Components
• URL generation features are documented in URL Generation System
• Middleware functionality is explained in Middleware System
• Framework integration details are in Configuration and Framework Integration

Purpose and Scope

The Hypervel Router package (hypervel/router) is a routing library designed for Hyperf applications that provides enhanced routing capabilities beyond the standard Hyperf HTTP server. It integrates with the Hyperf framework's dependency injection container and HTTP server while leveraging the FastRoute library for efficient URL pattern matching.

Sources: composer.json1-54

Key Features

The package provides several core capabilities:

Feature	Description	Components
Route Registration	Define HTTP routes with patterns, methods, and handlers	Router, RouteCollector
Named Routes	Reference routes by name for URL generation	RouteCollector, UrlGenerator
Model Binding	Automatically resolve route parameters to model instances	SubstituteBindings, UrlRoutable interface
Signed URLs	Generate cryptographically signed URLs with expiration	UrlGenerator, ValidateSignature
Rate Limiting	Throttle requests based on configurable rules	ThrottleRequests middleware
URL Generation	Generate absolute, relative, and asset URLs	UrlGenerator, helper functions
Parameter Binding	Explicit bindings and type-based resolution	Router::bind(), Router::model()

Sources: composer.json31-42

Package Architecture

The Hypervel Router consists of three primary subsystems that work together to handle routing and URL generation:

High-Level Component Structure

Sources: composer.json23-29 diagrams provided in context

Core Subsystems

1. Routing System

The routing system manages route registration and request dispatching through three primary classes:

• Hypervel\Router\Router - Main entry point for route registration, stores model and explicit bindings
• Hypervel\Router\RouteCollector - Collects route definitions with patterns, methods, and middleware
• Hypervel\Router\DispatcherFactory - Initializes FastRoute dispatcher and loads route files

Sources: composer.json24-26

2. URL Generation System

The URL generation system constructs URLs from named routes and validates signed URLs:

• Hypervel\Router\UrlGenerator - Implements URL generation and signature creation/validation
• Hypervel\Router\Contracts\UrlGenerator - Contract interface for URL generation
• src/Functions.php - Global helper functions (route(), url(), secure_url(), asset())

Sources: composer.json27-29

3. Middleware Pipeline

The middleware components process requests and resolve parameters:

• Hypervel\Router\Middleware\SubstituteBindings - Resolves route parameters to objects
• Hypervel\Router\Middleware\ThrottleRequests - Implements rate limiting
• Hypervel\Router\Middleware\ValidateSignature - Validates signed URL signatures

Sources: composer.json37-41

Framework Integration

Dependency Integration

The package integrates with the Hyperf framework through a ConfigProvider that registers component implementations with the dependency injection container:

Sources: composer.json31-36 composer.json46-49

Package Dependencies

The package requires these dependencies:

Dependency	Version	Purpose
php	^8.2	Minimum PHP version
hyperf/context	~3.1.0	Request context management
hyperf/http-server	~3.1.0	HTTP server integration
nikic/fast-route	^1.3.0	URL pattern matching and dispatching

Optional dependencies (suggested):

• hypervel/cache - Required for ThrottleRequests middleware
• hypervel/core - Required for ThrottleRequests middleware
• hypervel/session - Required for session-based previous() function
• hypervel/http - Required for ValidateSignature middleware

Sources: composer.json31-42

Request Lifecycle

The following diagram illustrates how a request flows through the Hypervel Router components:

Request Processing Flow

Sources: All files, based on architecture diagrams provided in context

Component Interactions

Code Entity Mapping

The following table maps high-level concepts to concrete code entities:

Concept	Primary Class/File	Key Methods
Route registration	Hypervel\Router\Router	get(), post(), addRoute(), group()
Route collection	Hypervel\Router\RouteCollector	addRoute(), addGroup()
Request matching	Hypervel\Router\DispatcherFactory	getRouter(), initRoutes()
URL generation	Hypervel\Router\UrlGenerator	route(), to(), signedRoute()
Parameter binding	Hypervel\Router\Router	bind(), model(), getBindingCallback()
Rate limiting	Hypervel\Router\Middleware\ThrottleRequests	handle()
Signed URL validation	Hypervel\Router\Middleware\ValidateSignature	handle()
Parameter resolution	Hypervel\Router\Middleware\SubstituteBindings	handle()

Sources: composer.json24-29

Getting Started

To use the Hypervel Router in a Hyperf application:

1. Installation - The package is installed via Composer and auto-discovered by Hyperf through the ConfigProvider registered in composer.json46-49

2. Route Definition - Routes are registered using the Router class methods (documented in Router Class)

3. URL Generation - URLs are generated using the UrlGenerator or helper functions (documented in URL Generation System)

4. Middleware Configuration - Middleware is applied to routes or route groups (documented in Middleware System)

The remaining sections of this documentation provide detailed explanations of each component and subsystem.

Sources: composer.json1-54