class UrlGenerator implements UrlGenerator

Traits

Constants

protected CACHED_SCHEME_CONTEXT_KEY

Context key for the URL scheme and the request it was computed from.

protected CACHED_ROOT_CONTEXT_KEY

Context key for the root URL and the request it was computed from.

protected FORCED_ROOT_CONTEXT_KEY

Context key for the forced root URL override.

protected FORCED_ASSET_ROOT_CONTEXT_KEY

Context key for the forced asset root URL override.

protected DEFAULT_PARAMETERS_CONTEXT_KEY

Context key for request-scoped default route parameters.

Properties

static protected array $macros

The registered string macros.

from  Macroable
protected RouteCollectionInterface $routes

The route collection.

protected Request $request

The request instance.

protected string|null $assetRoot

The asset root URL.

protected string|null $forceScheme

The forced scheme for URLs.

protected string|null $rootNamespace

The root namespace being applied to controller actions.

protected null|callable $sessionResolver

The session resolver callable.

protected null|callable $keyResolver

The encryption key resolver callable.

protected null|callable $missingNamedRouteResolver

The missing named route resolver callable.

protected Closure|null $originResolver

The callback used to resolve the URL origin.

protected Closure|null $defaultsResolver

The callback used to resolve default route parameters.

protected Closure|null $formatHostUsing

The callback to use to format hosts.

protected Closure|null $formatPathUsing

The callback to use to format paths.

protected RouteUrlGenerator|null $routeGenerator

The route URL generator instance.

Methods

int
secondsUntil(DateInterval|DateTimeInterface|int $delay)

Get the number of seconds until the given DateTime.

int
availableAt(DateInterval|DateTimeInterface|int|null $delay = 0)

Get the "available at" UNIX timestamp.

parseDateInterval(DateInterval|DateTimeInterface|int|null $delay)

If the given value is an interval, convert it to a DateTime instance.

int
currentTime()

Get the current system time as a UNIX timestamp.

string
runTimeForHumans(float $startTime, float|null $endTime = null)

Given a start time, format the total run time for human readability.

static void
macro(string $name, callable|object $macro)

Register a custom macro.

static void
mixin(object $mixin, bool $replace = true)

Mix another object into the class.

static bool
hasMacro(string $name)

Check if macro is registered.

static void
flushMacros()

Flush the existing macros.

static mixed
__callStatic(string $method, array $parameters)

Dynamically handle calls to the class.

mixed
__call(string $method, array $parameters)

Dynamically handle calls to the class.

__construct(RouteCollectionInterface $routes, Request $request, string|null $assetRoot = null)

Create a new URL generator instance.

string
full()

Get the full URL for the current request.

string
current()

Get the current URL for the request.

string
previous(bool|string $fallback = false)

Get the URL for the previous request.

string
previousPath(bool|string $fallback = false)

Get the previous path info for the request.

string|null
getPreviousUrlFromSession()

Get the previous URL from the session if possible.

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

Generate an absolute URL to the given path.

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

Generate an absolute URL with the given query parameters.

string
secure(string $path, mixed $parameters = [])

Generate a secure, absolute URL to the given path.

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

Generate the URL to an application asset.

string
secureAsset(string $path)

Generate the URL to a secure asset.

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

Generate the URL to an asset from a custom root domain such as CDN, etc.

string
removeIndex(string $root)

Remove the index.php file from a path.

string
formatScheme(bool|null $secure = null)

Get the default scheme for a raw URL.

string
signedRoute(BackedEnum|string $name, mixed $parameters = [], DateInterval|DateTimeInterface|int|null $expiration = null, bool $absolute = true)

Create a signed route URL for a named route.

void
ensureSignedRouteParametersAreNotReserved(array $parameters)

Ensure the given signed route parameters are not reserved.

string
temporarySignedRoute(BackedEnum|string $name, DateInterval|DateTimeInterface|int $expiration, mixed $parameters = [], bool $absolute = true)

Create a temporary signed route URL for a named route.

bool
hasValidSignature(Request $request, bool $absolute = true, Closure|array $ignoreQuery = [])

Determine if the given request has a valid signature.

bool
hasValidRelativeSignature(Request $request, Closure|array $ignoreQuery = [])

Determine if the given request has a valid signature for a relative URL.

bool
hasCorrectSignature(Request $request, bool $absolute = true, Closure|array $ignoreQuery = [])

Determine if the signature from the given request matches the URL.

bool
signatureHasNotExpired(Request $request)

Determine if the expires timestamp from the given request is not from the past.

string
route(BackedEnum|string $name, mixed $parameters = [], bool $absolute = true)

Get the URL to a named route.

string
toRoute(Route $route, mixed $parameters, bool $absolute)

Get the URL for a given route instance.

string
action(array|string $action, mixed $parameters = [], bool $absolute = true)

Get the URL to a controller action.

string
formatAction(array|string $action)

Format the given controller action.

array
formatParameters(mixed $parameters)

Format the array of URL parameters.

array
extractQueryString(string $path)

Extract the query string from the given path.

string
formatRoot(string $scheme, string|null $root = null)

Get the base URL for the request.

string
resolveRoot(bool $useOriginResolver = true)

Resolve the root URL for the current coroutine.

string
format(string $root, string $path, Route|null $route = null)

Format the given URL segments into a single URL.

bool
isValidUrl(string $path)

Determine if the given path is a valid URL.

routeUrl()

Get the route URL generator instance.

void
resolveDefaultsUsing(Closure|null $resolver)

Register the default route parameter resolver.

void
defaults(array $defaults)

Set the default named parameters used by the URL generator.

array
getDefaultParameters()

Get the effective default named parameters used by the URL generator.

void
useDefaults(array|null $defaults)

Replace the default route parameters for the current coroutine.

array
getDefaultParameterOverrides()

Get the default route parameter overrides for the current coroutine.

void
forceScheme(string|null $scheme)

Force the scheme for URLs.

string|null
getForcedScheme()

Get the forced scheme for URLs.

void
forceHttps(bool $force = true)

Force the use of the HTTPS scheme for all generated URLs.

void
resolveOriginUsing(Closure|null $resolver)

Register the URL origin resolver.

void
useOrigin(string|null $root)

Set the URL origin for the current coroutine.

string|null
getForcedOrigin()

Get the URL origin override for the current coroutine.

void
useAssetOrigin(string|null $root)

Set the asset URL origin for the current coroutine.

string|null
getForcedAssetOrigin()

Get the asset URL origin override for the current coroutine.

formatHostUsing(Closure $callback)

Set a callback to be used to format the host of generated URLs.

formatPathUsing(Closure $callback)

Set a callback to be used to format the path of generated URLs.

pathFormatter()

Get the path formatter being used by the URL generator.

getRequest()

Get the request instance.

void
setRequest(Request $request)

Set the current request instance.

setRoutes(RouteCollectionInterface $routes)

Set the route collection.

mixed
getSession()

Get the session implementation from the resolver.

setSessionResolver(callable $sessionResolver)

Set the session resolver for the generator.

setKeyResolver(callable $keyResolver)

Set the encryption key resolver.

withKeyResolver(callable $keyResolver)

Clone a new instance of the URL generator with a different encryption key resolver.

resolveMissingNamedRoutesUsing(callable $missingNamedRouteResolver)

Set the callback that should be used to attempt to resolve missing named routes.

string|null
getRootControllerNamespace()

Get the root controller namespace.

setRootControllerNamespace(string $rootNamespace)

Set the root controller namespace.

static void
flushState()

Flush all static state.

Details

in InteractsWithTime at line 17
protected int secondsUntil(DateInterval|DateTimeInterface|int $delay)

Get the number of seconds until the given DateTime.

Parameters

DateInterval|DateTimeInterface|int $delay

Return Value

int

in InteractsWithTime at line 29
protected int availableAt(DateInterval|DateTimeInterface|int|null $delay = 0)

Get the "available at" UNIX timestamp.

Parameters

DateInterval|DateTimeInterface|int|null $delay

Return Value

int

in InteractsWithTime at line 47
protected DateTimeInterface|int parseDateInterval(DateInterval|DateTimeInterface|int|null $delay)

If the given value is an interval, convert it to a DateTime instance.

Parameters

DateInterval|DateTimeInterface|int|null $delay

Return Value

DateTimeInterface|int

in InteractsWithTime at line 63
protected int currentTime()

Get the current system time as a UNIX timestamp.

Return Value

int

in InteractsWithTime at line 71
protected string runTimeForHumans(float $startTime, float|null $endTime = null)

Given a start time, format the total run time for human readability.

Parameters

float $startTime
float|null $endTime

Return Value

string

in Macroable at line 30
static void macro(string $name, callable|object $macro)

Register a custom macro.

Macros persist in a static property for the worker lifetime and apply to every subsequent call on the macroable class.

Parameters

string $name
callable|object $macro

Return Value

void

in Macroable at line 44
static void mixin(object $mixin, bool $replace = true)

Mix another object into the class.

Delegates to macro() for each method; registered macros persist in a static property for the worker lifetime.

Parameters

object $mixin
bool $replace

Return Value

void

Exceptions

ReflectionException

in Macroable at line 61
static bool hasMacro(string $name)

Check if macro is registered.

Parameters

string $name

Return Value

bool

in Macroable at line 72
static void flushMacros()

Flush the existing macros.

Clears worker-wide macros; concurrent coroutines may resolve different methods depending on timing.

Return Value

void

in Macroable at line 83
static mixed __callStatic(string $method, array $parameters)

Dynamically handle calls to the class.

Parameters

string $method
array $parameters

Return Value

mixed

Exceptions

BadMethodCallException

in Macroable at line 108
mixed __call(string $method, array $parameters)

Dynamically handle calls to the class.

Parameters

string $method
array $parameters

Return Value

mixed

Exceptions

BadMethodCallException

at line 133
__construct(RouteCollectionInterface $routes, Request $request, string|null $assetRoot = null)

Create a new URL generator instance.

Parameters

RouteCollectionInterface $routes
Request $request
string|null $assetRoot

at line 144
string full()

Get the full URL for the current request.

Return Value

string

at line 152
string current()

Get the current URL for the request.

Return Value

string

at line 160
string previous(bool|string $fallback = false)

Get the URL for the previous request.

Parameters

bool|string $fallback

Return Value

string

at line 179
string previousPath(bool|string $fallback = false)

Get the previous path info for the request.

Parameters

bool|string $fallback

Return Value

string

at line 198
protected string|null getPreviousUrlFromSession()

Get the previous URL from the session if possible.

Return Value

string|null

at line 206
string to(string $path, mixed $extra = [], bool|null $secure = null)

Generate an absolute URL to the given path.

Parameters

string $path
mixed $extra
bool|null $secure

Return Value

string

at line 239
string query(string $path, array $query = [], mixed $extra = [], bool|null $secure = null)

Generate an absolute URL with the given query parameters.

Parameters

string $path
array $query
mixed $extra
bool|null $secure

Return Value

string

at line 253
string secure(string $path, mixed $parameters = [])

Generate a secure, absolute URL to the given path.

Parameters

string $path
mixed $parameters

Return Value

string

at line 261
string asset(string $path, bool|null $secure = null)

Generate the URL to an application asset.

Parameters

string $path
bool|null $secure

Return Value

string

at line 284
string secureAsset(string $path)

Generate the URL to a secure asset.

Parameters

string $path

Return Value

string

at line 292
string assetFrom(string $root, string $path, bool|null $secure = null)

Generate the URL to an asset from a custom root domain such as CDN, etc.

Parameters

string $root
string $path
bool|null $secure

Return Value

string

at line 305
protected string removeIndex(string $root)

Remove the index.php file from a path.

Parameters

string $root

Return Value

string

at line 315
string formatScheme(bool|null $secure = null)

Get the default scheme for a raw URL.

Parameters

bool|null $secure

Return Value

string

at line 341
string signedRoute(BackedEnum|string $name, mixed $parameters = [], DateInterval|DateTimeInterface|int|null $expiration = null, bool $absolute = true)

Create a signed route URL for a named route.

Parameters

BackedEnum|string $name
mixed $parameters
DateInterval|DateTimeInterface|int|null $expiration
bool $absolute

Return Value

string

Exceptions

InvalidArgumentException

at line 369
protected void ensureSignedRouteParametersAreNotReserved(array $parameters)

Ensure the given signed route parameters are not reserved.

Parameters

array $parameters

Return Value

void

Exceptions

InvalidArgumentException

at line 387
string temporarySignedRoute(BackedEnum|string $name, DateInterval|DateTimeInterface|int $expiration, mixed $parameters = [], bool $absolute = true)

Create a temporary signed route URL for a named route.

Parameters

BackedEnum|string $name
DateInterval|DateTimeInterface|int $expiration
mixed $parameters
bool $absolute

Return Value

string

at line 395
bool hasValidSignature(Request $request, bool $absolute = true, Closure|array $ignoreQuery = [])

Determine if the given request has a valid signature.

Parameters

Request $request
bool $absolute
Closure|array $ignoreQuery

Return Value

bool

at line 404
bool hasValidRelativeSignature(Request $request, Closure|array $ignoreQuery = [])

Determine if the given request has a valid signature for a relative URL.

Parameters

Request $request
Closure|array $ignoreQuery

Return Value

bool

at line 412
bool hasCorrectSignature(Request $request, bool $absolute = true, Closure|array $ignoreQuery = [])

Determine if the signature from the given request matches the URL.

Parameters

Request $request
bool $absolute
Closure|array $ignoreQuery

Return Value

bool

at line 464
bool signatureHasNotExpired(Request $request)

Determine if the expires timestamp from the given request is not from the past.

Parameters

Request $request

Return Value

bool

at line 481
string route(BackedEnum|string $name, mixed $parameters = [], bool $absolute = true)

Get the URL to a named route.

Parameters

BackedEnum|string $name
mixed $parameters
bool $absolute

Return Value

string

Exceptions

RouteNotFoundException
InvalidArgumentException

at line 504
string toRoute(Route $route, mixed $parameters, bool $absolute)

Get the URL for a given route instance.

Parameters

Route $route
mixed $parameters
bool $absolute

Return Value

string

Exceptions

UrlGenerationException

at line 518
string action(array|string $action, mixed $parameters = [], bool $absolute = true)

Get the URL to a controller action.

Parameters

array|string $action
mixed $parameters
bool $absolute

Return Value

string

Exceptions

InvalidArgumentException

at line 530
protected string formatAction(array|string $action)

Format the given controller action.

Parameters

array|string $action

Return Value

string

at line 546
array formatParameters(mixed $parameters)

Format the array of URL parameters.

Parameters

mixed $parameters

Return Value

array

at line 565
protected array extractQueryString(string $path)

Extract the query string from the given path.

Parameters

string $path

Return Value

array

at line 580
string formatRoot(string $scheme, string|null $root = null)

Get the base URL for the request.

Parameters

string $scheme
string|null $root

Return Value

string

at line 594
protected string resolveRoot(bool $useOriginResolver = true)

Resolve the root URL for the current coroutine.

Parameters

bool $useOriginResolver

Return Value

string

at line 621
string format(string $root, string $path, Route|null $route = null)

Format the given URL segments into a single URL.

Parameters

string $root
string $path
Route|null $route

Return Value

string

at line 639
bool isValidUrl(string $path)

Determine if the given path is a valid URL.

Parameters

string $path

Return Value

bool

at line 655
protected RouteUrlGenerator routeUrl()

Get the route URL generator instance.

The RouteUrlGenerator is cached on the instance for its default parameters, but its request is always resolved fresh from the UrlGenerator to ensure coroutine safety in Swoole's long-lived workers.

Return Value

RouteUrlGenerator

at line 670
void resolveDefaultsUsing(Closure|null $resolver)

Register the default route parameter resolver.

The callback persists on the worker-shared URL generator and is evaluated for subsequent route generations across all coroutines.

Parameters

Closure|null $resolver

Return Value

void

at line 687
void defaults(array $defaults)

Set the default named parameters used by the URL generator.

Request-scoped when a request is present: the defaults are stored in coroutine Context and isolated to the current request. Outside a request (boot, queue jobs, scheduled tasks, console), they are stored on the worker-global route URL generator, shared across concurrent coroutines and persisting for the worker lifetime until changed or flushed.

Use useDefaults() for operation-local defaults outside an HTTP request.

Parameters

array $defaults

Return Value

void

at line 704
array getDefaultParameters()

Get the effective default named parameters used by the URL generator.

Return Value

array

at line 722
void useDefaults(array|null $defaults)

Replace the default route parameters for the current coroutine.

Parameters

array|null $defaults

Return Value

void

at line 736
array getDefaultParameterOverrides()

Get the default route parameter overrides for the current coroutine.

Return Value

array

at line 748
void forceScheme(string|null $scheme)

Force the scheme for URLs.

The scheme is stored on the worker-shared URL generator singleton and affects subsequent requests across coroutines; not safe to call per-request.

Parameters

string|null $scheme

Return Value

void

at line 757
string|null getForcedScheme()

Get the forced scheme for URLs.

Return Value

string|null

at line 769
void forceHttps(bool $force = true)

Force the use of the HTTPS scheme for all generated URLs.

The scheme is stored on the worker-shared URL generator singleton and affects subsequent requests across coroutines; not safe to call per-request.

Parameters

bool $force

Return Value

void

at line 781
void resolveOriginUsing(Closure|null $resolver)

Register the URL origin resolver.

The callback persists on the worker-shared URL generator and is evaluated for subsequent URL generations across all coroutines.

Parameters

Closure|null $resolver

Return Value

void

at line 793
void useOrigin(string|null $root)

Set the URL origin for the current coroutine.

Stored in coroutine Context so one request, job, or command cannot affect concurrent work.

Parameters

string|null $root

Return Value

void

at line 805
string|null getForcedOrigin()

Get the URL origin override for the current coroutine.

Return Value

string|null

at line 819
void useAssetOrigin(string|null $root)

Set the asset URL origin for the current coroutine.

Stored in coroutine Context so one request, job, or command cannot affect concurrent work.

Parameters

string|null $root

Return Value

void

at line 831
string|null getForcedAssetOrigin()

Get the asset URL origin override for the current coroutine.

Return Value

string|null

at line 844
UrlGenerator formatHostUsing(Closure $callback)

Set a callback to be used to format the host of generated URLs.

The callback persists on the singleton URL generator and affects every subsequent request.

Parameters

Closure $callback

Return Value

UrlGenerator

at line 860
UrlGenerator formatPathUsing(Closure $callback)

Set a callback to be used to format the path of generated URLs.

The callback persists on the singleton URL generator and affects every subsequent request.

Parameters

Closure $callback

Return Value

UrlGenerator

at line 871
Closure pathFormatter()

Get the path formatter being used by the URL generator.

Return Value

Closure

at line 885
Request getRequest()

Get the request instance.

In Swoole's long-lived workers, the UrlGenerator is a singleton. The request must be resolved from the coroutine-local RequestContext to avoid one coroutine's request leaking to another.

Return Value

Request

at line 898
void setRequest(Request $request)

Set the current request instance.

Per-request code should rely on RequestContext (read first by getRequest()); this setter writes the singleton UrlGenerator's fallback request used outside coroutine contexts, plus mutates the shared routeGenerator — runtime use races across coroutines.

Parameters

Request $request

Return Value

void

at line 923
UrlGenerator setRoutes(RouteCollectionInterface $routes)

Set the route collection.

Replacing the collection mutates the singleton URL generator for every subsequent request.

Parameters

RouteCollectionInterface $routes

Return Value

UrlGenerator

at line 934
protected mixed getSession()

Get the session implementation from the resolver.

Return Value

mixed

at line 951
UrlGenerator setSessionResolver(callable $sessionResolver)

Set the session resolver for the generator.

The resolver persists on the singleton URL generator and affects every subsequent request.

Parameters

callable $sessionResolver

Return Value

UrlGenerator

at line 967
UrlGenerator setKeyResolver(callable $keyResolver)

Set the encryption key resolver.

The resolver persists on the singleton URL generator and affects every subsequent request.

Parameters

callable $keyResolver

Return Value

UrlGenerator

at line 978
UrlGenerator withKeyResolver(callable $keyResolver)

Clone a new instance of the URL generator with a different encryption key resolver.

Parameters

callable $keyResolver

Return Value

UrlGenerator

at line 991
UrlGenerator resolveMissingNamedRoutesUsing(callable $missingNamedRouteResolver)

Set the callback that should be used to attempt to resolve missing named routes.

The callback persists on the singleton URL generator and affects every subsequent request.

Parameters

callable $missingNamedRouteResolver

Return Value

UrlGenerator

at line 1002
string|null getRootControllerNamespace()

Get the root controller namespace.

Return Value

string|null

at line 1015
UrlGenerator setRootControllerNamespace(string $rootNamespace)

Set the root controller namespace.

The namespace persists on the singleton URL generator and affects every subsequent request.

Parameters

string $rootNamespace

Return Value

UrlGenerator

at line 1026
static void flushState()

Flush all static state.

Return Value

void