URL Helper Functions

Overview

The hypervel/router package provides four global helper functions defined in the Hypervel\Router namespace for URL generation. These functions resolve the UrlGeneratorContract from ApplicationContext and delegate to the corresponding UrlGenerator methods. They provide a procedural interface for URL generation without requiring manual dependency injection.

For underlying URL generation implementation details, see page 3.1. For signed URL functionality, see page 3.2.

Function Signatures and Delegation

Each helper function in src/Functions.php1-49 follows the same pattern: resolve UrlGeneratorContract from the container via ApplicationContext::getContainer(), then call the corresponding method on the resolved instance.

Helper Function	Signature	Delegates To
route()	route(string $name, array $parameters = [], bool $absolute = true, string $server = 'http'): string	UrlGeneratorContract::route()
url()	url(?string $path = null, array $extra = [], ?bool $secure = null): string|UrlGeneratorContract	UrlGeneratorContract::to() or returns contract instance
secure_url()	secure_url(string $path, array $extra = []): string	UrlGeneratorContract::secure()
asset()	asset(string $path, ?bool $secure = null): string	UrlGeneratorContract::asset()

Sources: src/Functions.php16-48

Function Delegation Architecture

Sources: src/Functions.php7-48

Function Reference

route()

Generates URLs for named routes registered in the application's route collection.

Signature: src/Functions.php16

Parameters:

• $name - Named route identifier as registered via Router::get()->name() or similar
• $parameters - Associative array of route parameters and query string values
• $absolute - Generate absolute URL when true, relative when false (default: true)
• $server - Server name used for route matching when generating absolute URLs (default: 'http')

Returns: URL string for the named route

Throws: InvalidArgumentException if the named route is not registered

Implementation: Calls ApplicationContext::getContainer()->get(UrlGeneratorContract::class)->route($name, $parameters, $absolute, $server) at src/Functions.php18

Sources: src/Functions.php11-19

url()

Generates application URLs or returns the UrlGeneratorContract instance for method chaining.

Signature: src/Functions.php24

Parameters:

• $path - Path to generate URL for; when null, returns the UrlGeneratorContract instance
• $extra - Query string parameters to append
• $secure - Force HTTPS (true), HTTP (false), or use configured default (null)

Returns: URL string when $path is provided; UrlGeneratorContract instance when $path is null

Implementation: src/Functions.php26-31

• Resolves UrlGeneratorContract from container
• Returns the contract instance directly if $path is null
• Otherwise delegates to UrlGeneratorContract::to($path, $extra, $secure)

Sources: src/Functions.php21-32

secure_url()

Generates HTTPS URLs by forcing the secure protocol.

Signature: src/Functions.php37

Parameters:

• $path - Path to generate secure URL for
• $extra - Query string parameters to append

Returns: HTTPS URL string

Implementation: Calls ApplicationContext::getContainer()->get(UrlGeneratorContract::class)->secure($path, $extra) at src/Functions.php39

Sources: src/Functions.php34-40

asset()

Generates URLs for static assets such as CSS, JavaScript, images, and other resources.

Signature: src/Functions.php45

Parameters:

• $path - Asset path relative to the configured asset base URL
• $secure - Force HTTPS (true), HTTP (false), or use configured default (null)

Returns: Complete asset URL string

Implementation: Calls ApplicationContext::getContainer()->get(UrlGeneratorContract::class)->asset($path, $secure) at src/Functions.php47

Asset URLs respect the UrlGenerator configuration for asset base URLs and may include CDN integration or versioning strategies configured in the UrlGenerator instance.

Sources: src/Functions.php42-48

Container Resolution and Delegation Sequence

This diagram shows the complete execution flow when a helper function is called, including container resolution and method delegation.

Sources: src/Functions.php16-19

Common Usage Patterns

Named Route URL Generation

The route() function generates URLs for routes registered with a name:

Sources: src/Functions.php16-19

Path-Based URL Generation

The url() function generates URLs for arbitrary paths:

Sources: src/Functions.php24-32

UrlGenerator Instance Access

When url() is called without arguments, it returns the UrlGeneratorContract instance for accessing advanced methods:

This pattern provides access to methods not directly exposed through helper functions, such as signed URL generation (see page 3.2) and current/previous URL retrieval.

Sources: src/Functions.php26-29

Secure URL Generation

The secure_url() function forces HTTPS protocol:

Sources: src/Functions.php37-40

Asset URL Generation

The asset() function generates URLs for static assets:

Asset URLs respect the UrlGenerator configuration for asset base URLs, which may point to CDN endpoints or versioned asset directories.

Sources: src/Functions.php45-48

Container Integration

All helper functions rely on ApplicationContext::getContainer() to resolve the UrlGeneratorContract service. This ensures that:

1. The same UrlGenerator configuration is used across all helper functions
2. Any custom UrlGenerator implementations are automatically used
3. Container-managed dependencies (request context, configuration) are properly injected
4. Performance is maintained through container-level service caching

The helper functions provide a procedural interface while maintaining the benefits of dependency injection and service configuration.

Sources: src/Functions.php7-47