URL Generation

This document covers URL generation functionality provided by the URL facade. The URL facade provides methods for generating application URLs, named route URLs, asset URLs, and signed URLs with expiration. It also includes utilities for URL validation, signature verification, and URL introspection.

For route definition and registration, see Routing. For making HTTP requests to external URLs, see HTTP Client.

Architecture Overview

The URL generation system is built on the facade pattern, providing a static API over the underlying UrlGenerator implementation from the Hypervel Router component.

URL Facade Architecture

Sources: src/Facades/URL.php1-48

URL Facade Methods

The URL facade exposes methods organized into several categories:

Category	Methods	Purpose
Basic URLs	to(), secure(), query()	Generate absolute URLs to paths
Named Routes	route()	Generate URLs from named routes
Assets	asset(), secureAsset(), assetFrom()	Generate URLs to static assets
Signed URLs	signedRoute(), temporarySignedRoute()	Generate tamper-proof URLs with signatures
Validation	hasValidSignature(), hasCorrectSignature(), signatureHasNotExpired()	Verify URL signatures
Introspection	full(), current(), previous(), previousPath()	Get information about current/previous URLs
Configuration	forceScheme(), forceHttps(), useOrigin(), formatHostUsing(), formatPathUsing()	Configure URL generation behavior

Sources: src/Facades/URL.php10-38

Basic URL Generation

The URL facade provides methods for generating absolute URLs to application paths.

Generating URLs to Paths

to(string $path, array $extra = [], bool|null $secure = null): string

Generates an absolute URL to the specified path. The $extra array can contain additional path segments, and $secure controls HTTP vs HTTPS.

secure(string $path, array $extra = []): string

Convenience method to generate HTTPS URLs. Equivalent to URL::to($path, $extra, true).

query(string $path, array $query = [], array $extra = [], bool|null $secure = null): string

Generates a URL with query string parameters.

Sources: src/Facades/URL.php11-13

Named Route URLs

The route() method generates URLs from named route definitions.

route(string $name, array $parameters = [], bool $absolute = true, string $server = 'http'): string

Generates a URL for a named route. Route parameters are filled using the $parameters array, which supports both positional and named parameters.

The method resolves route parameters by:

1. Replacing named placeholders (e.g., {id}) with corresponding array values
2. Appending any remaining parameters as query strings

For details on route definition and naming, see Routing.

Sources: src/Facades/URL.php10

Asset URLs

Asset URL methods generate URLs to static files like CSS, JavaScript, images, and fonts.

asset(string $path, bool|null $secure = null): string

Generates a URL to an asset in the public directory.

secureAsset(string $path): string

Convenience method to generate HTTPS asset URLs. Equivalent to URL::asset($path, true).

assetFrom(string $root, string $path, bool|null $secure = null): string

Generates an asset URL from a custom root domain, useful for CDN integration.

Sources: src/Facades/URL.php14-16

Signed URLs

Signed URLs contain a cryptographic signature that prevents tampering and can include expiration times. These are commonly used for email verification links, temporary file access, and secure API endpoints.

Signed URL Flow

Sources: src/Facades/URL.php18-23

Generating Signed URLs

signedRoute(BackedEnum|string $name, array $parameters = [], DateInterval|DateTimeInterface|int|null $expiration = null, bool $absolute = true, string $server = 'http'): string

Generates a signed URL for a named route. The signature is appended as a signature query parameter.

temporarySignedRoute(BackedEnum|string $name, DateInterval|DateTimeInterface|int|null $expiration, array $parameters = [], bool $absolute = true, string $server = 'http'): string

Convenience method for generating signed URLs with required expiration. The parameter order differs from signedRoute() to emphasize that expiration is mandatory.

Signature Query Parameters

Signed URLs include the following query parameters:

• signature: HMAC hash of the URL
• expires: Unix timestamp of expiration (for temporary URLs)

Sources: src/Facades/URL.php18-19

Signature Validation

The URL facade provides methods to validate signed URLs and verify that they have not been tampered with or expired.

hasValidSignature(RequestInterface $request, bool $absolute = true, array $ignoreQuery = []): bool

Verifies that a request has a valid signature and has not expired (if an expiration was set). Returns true if the signature is correct and has not expired.

hasValidRelativeSignature(RequestInterface $request, array $ignoreQuery = []): bool

Validates signature using relative URLs (without domain). Useful when the domain might change between URL generation and validation.

hasCorrectSignature(RequestInterface $request, bool $absolute = true, array $ignoreQuery = []): bool

Checks if the signature is correct without checking expiration. Useful when you want to separate signature verification from expiration checks.

signatureHasNotExpired(RequestInterface $request): bool

Checks if a signed URL has not expired. Returns true if there is no expiration or if the expiration time has not passed.

Validation Decision Tree

Sources: src/Facades/URL.php20-23

URL Introspection

Methods for retrieving information about the current and previous requests.

full(): string

Returns the full URL for the current request including query string.

current(): string

Returns the current URL without query string parameters.

previous(string|bool $fallback = false): string

Returns the previous URL from the request's referer header. If no referer exists, returns the $fallback value.

previousPath(mixed $fallback = false): string

Returns the path portion of the previous URL without domain.

Sources: src/Facades/URL.php24-27

URL Configuration

The URL facade provides methods to configure global URL generation behavior.

forceScheme(string|null $scheme): void

Forces all generated URLs to use a specific scheme (e.g., http, https).

forceHttps(bool $force = true): void

Convenience method to force HTTPS for all generated URLs. Equivalent to forceScheme('https').

useOrigin(string|null $root): void

Sets a custom root URL for all generated URLs. Useful for CDN integration or when the application is behind a proxy.

formatHostUsing(Closure $callback): UrlGenerator

Registers a callback to customize host formatting for generated URLs.

formatPathUsing(Closure $callback): UrlGenerator

Registers a callback to customize path formatting for generated URLs.

setSignedKey(string|null $signedKey = null): UrlGenerator

Sets the secret key used for generating URL signatures. By default, uses the application's encryption key.

Sources: src/Facades/URL.php30-35

URL Validation and Formatting

isValidUrl(string $path): bool

Checks if a string is a valid URL format.

formatScheme(bool|null $secure = null): string

Returns the appropriate URL scheme based on the secure flag and configuration.

format(string $root, string $path): string

Formats a URL by combining root and path components.

Sources: src/Facades/URL.php17-29

Method Reference Summary

URL Generation Methods

Method	Return Type	Description
to()	string	Generate absolute URL to path
secure()	string	Generate HTTPS URL to path
query()	string	Generate URL with query parameters
route()	string	Generate URL from named route
asset()	string	Generate URL to asset
secureAsset()	string	Generate HTTPS URL to asset
assetFrom()	string	Generate asset URL from custom root

Signed URL Methods

Method	Return Type	Description
signedRoute()	string	Generate signed route URL
temporarySignedRoute()	string	Generate signed URL with required expiration
hasValidSignature()	bool	Check if request has valid, non-expired signature
hasValidRelativeSignature()	bool	Check relative URL signature validity
hasCorrectSignature()	bool	Check signature correctness (ignore expiration)
signatureHasNotExpired()	bool	Check if signature has not expired

Introspection Methods

Method	Return Type	Description
full()	string	Get full current URL with query
current()	string	Get current URL without query
previous()	string	Get previous URL from referer
previousPath()	string	Get previous path without domain

Configuration Methods

Method	Return Type	Description
forceScheme()	void	Force specific URL scheme
forceHttps()	void	Force HTTPS for all URLs
useOrigin()	void	Set custom root URL
formatHostUsing()	UrlGenerator	Customize host formatting
formatPathUsing()	UrlGenerator	Customize path formatting
setSignedKey()	UrlGenerator	Set signature secret key

Sources: src/Facades/URL.php10-38