Contracts and Interfaces

This page provides comprehensive reference documentation for all contracts and interfaces defined by the hypervel/router package. These contracts define the public API boundaries and enable interface-based programming patterns throughout the routing system.

The package defines two primary contracts: UrlGenerator for URL generation operations, and UrlRoutable for model binding in route parameters. For implementation details of these contracts, see UrlGenerator Class and Model Binding and UrlRoutable. For information about how these contracts are registered with the dependency injection container, see Configuration and Framework Integration.

---

Contract Architecture

The following diagram illustrates the relationship between contracts, their implementations, and consumers within the routing system:

Sources: src/Contracts/UrlGenerator.php src/Contracts/UrlRoutable.php

---

UrlGenerator Contract

The UrlGenerator contract defines the complete interface for URL generation throughout the application. It is the highest-importance contract in the package (importance: 11.16) and is implemented by the UrlGenerator class (importance: 33.19).

Location: src/Contracts/UrlGenerator.php14-151

Namespace: Hypervel\Router\Contracts

Method Categories

The contract organizes 25 methods into six functional categories:

Sources: src/Contracts/UrlGenerator.php14-151

Named Route URL Methods

These methods generate URLs for named routes registered with the routing system.

Method	Signature	Purpose
route()	route(string $name, array $parameters = [], bool $absolute = true, string $server = 'http'): string	Generate URL to a named route
signedRoute()	signedRoute(BackedEnum|string $name, array $parameters = [], DateInterval|DateTimeInterface|int|null $expiration = null, bool $absolute = true, string $server = 'http'): string	Generate cryptographically signed URL for a named route
temporarySignedRoute()	temporarySignedRoute(BackedEnum|string $name, DateInterval|DateTimeInterface|int|null $expiration, array $parameters = [], bool $absolute = true, string $server = 'http'): string	Generate temporary signed URL with required expiration

Throws: InvalidArgumentException when route name does not exist

Sources: src/Contracts/UrlGenerator.php16-68

Path-Based URL Methods

These methods generate URLs from raw paths without requiring named routes.

Method	Signature	Purpose
to()	to(string $path, array $extra = [], ?bool $secure = null): string	Generate URL for application path
query()	query(string $path, array $query = [], array $extra = [], ?bool $secure = null): string	Generate absolute URL with query parameters
secure()	secure(string $path, array $extra = []): string	Generate secure (HTTPS) URL to path

Sources: src/Contracts/UrlGenerator.php24-36

Asset URL Methods

These methods generate URLs for static assets such as CSS, JavaScript, images, and fonts.

Method	Signature	Purpose
asset()	asset(string $path, ?bool $secure = null): string	Generate URL to application asset
secureAsset()	secureAsset(string $path): string	Generate secure URL to asset
assetFrom()	assetFrom(string $root, string $path, ?bool $secure = null): string	Generate URL to asset from custom root (e.g., CDN)

Sources: src/Contracts/UrlGenerator.php38-51

Signature Validation Methods

These methods validate cryptographic signatures on URLs to prevent tampering.

Method	Signature	Purpose
hasValidSignature()	hasValidSignature(RequestInterface $request, bool $absolute = true, array $ignoreQuery = []): bool	Check if request has valid signature and not expired
hasValidRelativeSignature()	hasValidRelativeSignature(RequestInterface $request, array $ignoreQuery = []): bool	Check if request has valid relative signature
hasCorrectSignature()	hasCorrectSignature(RequestInterface $request, bool $absolute = true, array $ignoreQuery = []): bool	Check if signature matches URL (ignores expiration)
signatureHasNotExpired()	signatureHasNotExpired(RequestInterface $request): bool	Check if signature expiration timestamp is valid

Sources: src/Contracts/UrlGenerator.php70-88

Request Information Methods

These methods retrieve URL information from the current HTTP request.

Method	Signature	Purpose
full()	full(): string	Get full URL for current request (with query string)
current()	current(): string	Get current URL without query string
previous()	previous(bool|string $fallback = false): string	Get URL for previous request (requires session)
previousPath()	previousPath($fallback = false): string	Get path info for previous request

Sources: src/Contracts/UrlGenerator.php90-110

Utility and Configuration Methods

These methods control URL formatting and scheme enforcement.

Method	Signature	Purpose
format()	format(string $root, string $path): string	Format URL segments into single URL
formatScheme()	formatScheme(?bool $secure = null): string	Get default scheme for raw URL (http/https)
isValidUrl()	isValidUrl(string $path): bool	Determine if path is valid URL
forceScheme()	forceScheme(?string $scheme): void	Force scheme for all generated URLs
forceHttps()	forceHttps(bool $force = true): void	Force HTTPS scheme for all URLs
useOrigin()	useOrigin(?string $root): void	Set URL origin for all generated URLs
formatHostUsing()	formatHostUsing(Closure $callback): static	Set callback for custom host formatting
formatPathUsing()	formatPathUsing(Closure $callback): static	Set callback for custom path formatting
setSignedKey()	setSignedKey(?string $signedKey = null): static	Set signing key for URL signatures

Sources: src/Contracts/UrlGenerator.php112-151

---

UrlRoutable Contract

The UrlRoutable contract defines the interface for models that can be automatically resolved from route parameters. This contract is central to the model binding system used by the SubstituteBindings middleware.

Location: src/Contracts/UrlRoutable.php9-32

Namespace: Hypervel\Router\Contracts

Importance: 6.38

Interface Definition

Sources: src/Contracts/UrlRoutable.php9-32

Method Reference

Method	Signature	Purpose	Typical Implementation
getRouteKey()	public function getRouteKey()	Return the value that identifies this model in URLs	Returns $this->id or custom key value
getRouteKeyName()	public function getRouteKeyName()	Return the column name used as route key	Returns 'id' or custom column name
resolveRouteBinding()	public function resolveRouteBinding($value)	Resolve a model instance from a route parameter value	Queries database: return static::where($this->getRouteKeyName(), $value)->first();

Sources: src/Contracts/UrlRoutable.php11-31

Usage in Model Binding

The following diagram shows how UrlRoutable integrates with the parameter resolution system:

Sources: src/Contracts/UrlRoutable.php src/Middleware/SubstituteBindings.php

Implementation Requirements

Classes implementing UrlRoutable must:

1. Return consistent route keys - The getRouteKey() method must return a value that uniquely identifies the model instance
2. Define route key name - The getRouteKeyName() method must return the column or property name used for binding
3. Handle resolution failures - The resolveRouteBinding() method must return null when no matching model exists
4. Type compatibility - The return type of resolveRouteBinding() is ?Model, expecting a Hyperf database model or null

Sources: src/Contracts/UrlRoutable.php9-32

---

Contract Registration and Dependency Injection

The following table shows how contracts are registered with the Hyperf DI container:

Contract	Implementation	Registration Location	Binding Type
Hypervel\Router\Contracts\UrlGenerator	Hypervel\Router\UrlGenerator	src/ConfigProvider.php	Singleton binding via dependencies array
Hypervel\Router\Contracts\UrlRoutable	Not directly bound	N/A	Interface implemented by user models

Sources: src/ConfigProvider.php

Dependency Injection Example

The contracts enable interface-based dependency injection throughout the application:

Sources: src/ConfigProvider.php src/Contracts/UrlGenerator.php

---

Contract Extension Patterns

Custom UrlGenerator Implementation

While the package provides a complete UrlGenerator implementation, applications can provide custom implementations:

1. Create class implementing Hypervel\Router\Contracts\UrlGenerator
2. Override binding in config/autoload/dependencies.php
3. Implement all 25 interface methods

Sources: src/Contracts/UrlGenerator.php14-151

UrlRoutable in Domain Models

Models should implement UrlRoutable when they are used as route parameters:

Default behavior (Hyperf Model):

• getRouteKey(): Returns primary key value
• getRouteKeyName(): Returns 'id'
• resolveRouteBinding(): Queries by primary key

Custom behavior (override in model):

• Use different column (e.g., slug instead of id)
• Add query constraints (soft deletes, tenant filtering)
• Implement custom resolution logic

Sources: src/Contracts/UrlRoutable.php9-32 src/Middleware/SubstituteBindings.php

---

Summary

The hypervel/router package provides two primary contracts:

Contract	Methods	Primary Use Case	Importance
UrlGenerator	25	URL generation, signing, validation	11.16
UrlRoutable	3	Model binding in route parameters	6.38

These contracts establish clear API boundaries, enable dependency injection, and allow for custom implementations when needed. The UrlGenerator contract is bound to its implementation via the DI container, while UrlRoutable is implemented directly by domain models.

Sources: src/Contracts/UrlGenerator.php src/Contracts/UrlRoutable.php