 |
VOOZH | about |
|
VOOZH | about |
The URL Generation System provides comprehensive URL construction capabilities for the Hypervel Router package. This system generates URLs for named routes, arbitrary paths, static assets, and signed URLs with cryptographic validation. It also provides access to current and previous request information.
This document provides an overview of the URL generation architecture, core capabilities, and component interactions. For detailed method documentation of the UrlGenerator class, see page 3.1. For signed URL creation and validation, see page 3.2. For global helper function usage (route(), url(), asset(), etc.), see page 3.3.
Sources: src/UrlGenerator.php1-519 src/Contracts/UrlGenerator.php1-151
The URL Generation System consists of three architectural layers: a contract interface (Hypervel\Router\Contracts\UrlGenerator), a concrete implementation (Hypervel\Router\UrlGenerator), and optional global helper functions that provide convenient access.
Architecture Overview: Applications access URL generation through the UrlGenerator contract interface, which is implemented by the UrlGenerator class. The implementation organizes methods into four functional groups: core URL generation, request information retrieval, signed URL operations, and configuration. The system depends on DispatcherFactory for named route resolution, ConfigInterface for application settings, RequestInterface for current request data, and SessionInterface for previous URL tracking.
Sources: src/UrlGenerator.php28-61 src/Contracts/UrlGenerator.php14-151
The URL Generation System consists of three architectural layers: a contract interface, a concrete implementation, and optional global helper functions that provide convenient access.
Architecture Overview: Applications access URL generation through the UrlGenerator contract interface, which is implemented by the UrlGenerator class. The implementation organizes methods into four functional groups: core URL generation, request information retrieval, signed URL operations, and configuration. The system depends on DispatcherFactory for named route resolution, ConfigInterface for application settings, RequestInterface for current request data, and SessionInterface for previous URL tracking.
Sources: src/UrlGenerator.php28-61 src/Contracts/UrlGenerator.php14-151
The UrlGenerator provides five primary categories of URL generation, each serving distinct use cases within the application.
| Capability | Primary Methods | Purpose | Typical Usage |
|---|---|---|---|
| Named Route URLs | route(), signedRoute(), temporarySignedRoute() | Generate URLs from route names with parameters | Navigation links, form actions, redirects |
| Path-Based URLs | to(), query(), secure() | Generate URLs from arbitrary paths | Dynamic URLs, external integrations |
| Asset URLs | asset(), secureAsset(), assetFrom() | Generate URLs for static resources | CSS, JavaScript, image references |
| Request Information | full(), current(), previous(), previousPath() | Retrieve current request URL data | Breadcrumbs, back buttons, referrer tracking |
| Signed URLs | signedRoute(), hasValidSignature(), hasCorrectSignature() | Create and validate cryptographically secure URLs | Email unsubscribe links, temporary access |
Sources: src/Contracts/UrlGenerator.php14-151 src/UrlGenerator.php63-353
Named route URL generation is the most complex capability, requiring integration with the routing system to resolve route names to URI patterns.
Route Resolution Process: The route() method first retrieves the named routes from DispatcherFactory for the specified server. It throws InvalidArgumentException if the route name doesn't exist. The method then iterates through route segments, replacing placeholders with parameter values. Unused parameters become query string parameters. Finally, it formats the complete URL using the configured root and scheme.
Sources: src/UrlGenerator.php63-100
Path-based and asset URL generation methods provide simpler URL creation for arbitrary paths and static resources.
Method Relationships: The to() method serves as the foundation for path-based URLs. It validates if the path is already a valid URL, formats parameters (extracting route keys from UrlRoutable objects), handles existing query strings, and combines the root URL with the formatted path. The query() method extends to() by merging additional query parameters. The secure() method is a wrapper that forces HTTPS. Asset methods follow a simpler pattern, primarily combining the root URL with the asset path without extensive parameter processing.
Sources: src/UrlGenerator.php104-174
The URL generator provides methods to access information about the current and previous requests, essential for navigation features and referrer tracking.
Data Source Strategy: Current request methods (full(), current()) retrieve data from RequestInterface when a request context exists, falling back to the configured app.url. The current() method strips the query string from the full URL using regex. Previous request methods (previous(), previousPath()) check three sources in order: the HTTP referer header from the current request, the session's stored previous URL, and finally a fallback parameter or root path. This multi-source approach ensures robust URL retrieval even when some data sources are unavailable.
Sources: src/UrlGenerator.php298-353 src/UrlGenerator.php511-518
The UrlGenerator provides extensive configuration options to control URL generation behavior across the application.
| Configuration Method | Purpose | Scope | Example Use Case |
|---|---|---|---|
forceScheme(?string $scheme) | Force all URLs to use specific scheme | Global | Force HTTPS in production |
forceHttps(bool $force = true) | Convenience wrapper for HTTPS | Global | Simplified HTTPS enforcement |
useOrigin(?string $root) | Override root URL for all generation | Per-request (Context) | Multi-tenant applications |
formatHostUsing(Closure $callback) | Custom host formatting logic | Global | Domain transformation |
formatPathUsing(Closure $callback) | Custom path formatting logic | Global | Path normalization |
setSignedKey(?string $signedKey) | Override signing key | Instance | Per-feature signing keys |
Configuration Architecture: Configuration is stored across three layers: instance properties (scheme, formatting callbacks, signing key), coroutine context (forced root URL for request isolation), and the application configuration (app.key). Instance properties affect all URLs generated by that instance, while context storage enables per-request overrides in the Hyperf coroutine environment. The formatScheme() method caches the computed scheme to avoid repeated calculation. The useOrigin() method stores the root URL in coroutine context and clears cached values, ensuring request isolation in concurrent environments.
Sources: src/UrlGenerator.php33-58 src/UrlGenerator.php177-509
The UrlGenerator integrates with multiple framework components to provide comprehensive URL generation capabilities.
Dependency Resolution Pattern: The UrlGenerator receives only ContainerInterface via constructor injection and lazily resolves other dependencies as needed. This pattern reduces coupling and avoids unnecessary service instantiation. The DispatcherFactory is accessed only when generating named route URLs. RequestInterface and SessionInterface are conditionally accessed based on context availability checks, allowing the generator to function even outside of HTTP request contexts (e.g., CLI commands). Configuration data is retrieved from ConfigInterface for application settings. Context storage provides request isolation in Hyperf's coroutine environment, with separate entries for forced root URLs and cached request roots.
Sources: src/UrlGenerator.php59-61 src/UrlGenerator.php477-518