URL & Route Information

This document explains how to access and manipulate URL components, retrieve route parameters and metadata, and work with path segments in the Request class. These capabilities enable controllers and middleware to inspect the incoming request's URL structure and matched route information.

For information about routing and dispatching mechanisms, see Core Middleware & Request Lifecycle. For URL generation and signed URL creation, see Session, Authentication & Validation.

---

URL Components and Construction

The Request class provides methods to access individual URL components and construct URLs with various formats.

Accessing URL Parts

The URL is decomposed into standard HTTP components that can be accessed individually:

Method	Return Type	Description	Example Value
getScheme()	string	URL scheme	"https"
getHost()	string	Hostname without port	"api.example.com"
getPort()	int|string	Port number	443 or 8080
getHttpHost()	string	Host with port	"api.example.com:443"
isSecure()	bool	Whether HTTPS	true

The getHost() method src/Request.php214-219 reads from the HOST header, stripping the port if present. The getPort() method src/Request.php239-256 intelligently determines the port from the HOST header or falls back to server parameters and scheme defaults (443 for HTTPS, 80 for HTTP).

Sources: src/Request.php214-273

URL Construction Methods

URL Construction Methods:

• root() src/Request.php617-620: Returns the base URL without path or query string
• url() (inherited): Returns the full path without query string
• fullUrl() src/Request.php625-633: Returns the complete URL including query parameters
• fullUrlWithQuery(array $query) src/Request.php638-645: Merges additional query parameters into the URL
• fullUrlWithoutQuery(array|string $keys) src/Request.php650-659: Removes specified query parameters
• uri() src/Request.php748-751: Returns a Uri instance for fluent manipulation

Helper Methods:

• getSchemeAndHttpHost() / schemeAndHttpHost() src/Request.php430-441: Returns scheme + host + port (e.g., "https://api.example.com:443")

Sources: src/Request.php430-441 src/Request.php617-659 src/Request.php748-751

---

Route Parameters and Information

Once a route is matched, the Request provides access to the dispatched route metadata and extracted parameters.

DispatchedRoute Access Flow

Sources: src/Request.php664-702 src/DispatchedRoute.php48-83

Core Route Methods

The Request class provides the route() method as the primary interface for accessing route information:

route(?string $param = null, mixed $default = null) src/Request.php694-702

• When called without arguments: returns the full DispatchedRoute object
• When called with a parameter name: returns that route parameter's value
• Supports default values if parameter doesn't exist

getDispatchedRoute() src/Request.php664-667

• Returns the DispatchedRoute instance directly
• Used internally by route() method

Sources: src/Request.php664-702

DispatchedRoute Methods

The DispatchedRoute class src/DispatchedRoute.php1-108 extends Hyperf's Dispatched class and provides these methods:

Method	Return Type	Description
parameters()	array	All route parameters as key-value pairs
parameter(string $key, mixed $default)	mixed	Single parameter value with optional default
hasParameters()	bool	Whether any parameters exist
hasParameter(string $name)	bool	Whether specific parameter exists
getName()	?string	Named route identifier
getHandler()	?RouteHandler	Route handler object
getControllerClass()	?string	Controller class name
getMiddleware()	array	Route-specific middleware

Example Usage:

Sources: src/DispatchedRoute.php48-108

Route Name Matching

routeIs(mixed ...$patterns) src/Request.php707-720

Checks if the current route name matches any of the given patterns. Supports wildcard matching via Str::is():

Returns false if the route has no name.

Sources: src/Request.php707-720

---

Path Segments

Path segments are the individual parts of a URL path separated by slashes.

Segment Extraction Diagram

Sources: src/Request.php670-687

Segment Methods

segments() src/Request.php680-687

• Returns an array of all non-empty path segments
• Segments are extracted from decodedPath() by splitting on /
• Empty segments are filtered out
• Array is re-indexed to start at 0

segment(int $index, ?string $default = null) src/Request.php672-675

• Retrieves a single segment by 1-based index
• Returns the default value if the segment doesn't exist
• Internally calls segments() and accesses by $index - 1

Example Usage:

Sources: src/Request.php672-687

---

URL Pattern Matching

Beyond route name matching, the Request class provides methods to match URL patterns against the full URL.

Full URL Pattern Matching

fullUrlIs(mixed ...$patterns) src/Request.php725-735

Checks if the complete request URL (including query string) matches any of the given patterns:

Uses Str::is() for pattern matching, supporting wildcards (*) and other Laravel-style patterns.

Sources: src/Request.php725-735

---

Request Method and Headers

While primarily about URLs, the Request class also provides convenient access to request method and headers:

method() src/Request.php740-743

• Returns the HTTP method (GET, POST, PUT, etc.)
• Alias for getMethod()

headers() src/Request.php756-759

• Returns all request headers as an array
• Alias for getHeaders()

Sources: src/Request.php740-759

---

Integration with Route Parameter Resolution

The URL and route information system integrates with the dependency injection system through RouteDependency.

When RouteDependency resolves method parameters src/RouteDependency.php108-114 it considers:

1. Route parameters from the matched route
2. Values from the DI container
3. Default parameter values

Route parameters are passed as the $arguments array to getMethodParameters() and getClosureParameters() methods, where they are matched by name or position src/RouteDependency.php156-174

Sources: src/RouteDependency.php108-174 src/DispatchedRoute.php48-75

---

Common Use Cases

Building API Links

Route-Based Logic

Path Analysis

Security Checks

Sources: src/Request.php214-751