PHP Luminova: URI Pattern Type Placeholders
Define dynamic URI and CLI route parameters using predefined type-aware placeholders with built-in pattern matching, validation, and optional segment support.
Dynamic URI pattern placeholders provide predefined patterns for capturing URL segments and CLI command parameters when routing to controller methods. They can be used with Route Attribute, Prefix Attribute, Command Attribute, and Method Based routing.
They let you define dynamic routes without writing raw regular expressions or using curly-brace named placeholders, making route definitions cleaner, more readable, and easier to maintain.
Each placeholder applies a predefined matching pattern, with many supporting type-aware validation and optional forms such as (:?int) or (:?string).
These placeholders provide a consistent way to define dynamic HTTP routes and CLI commands while keeping route patterns concise and predictable.
Placeholders
These placeholders provide readable, type-aware route patterns, helping keep dynamic routing definitions concise and consistent.
| Placeholder | Matches | Optional form |
|---|---|---|
(:base) | The base path with any following content. | No |
(:root) | The remaining root-level path, including multiple segments. | No |
(:group) | Any content, including /; may be empty. | No |
(:int) | One or more digits. | (:?int) |
(:integer) | One or more digits. | (:?integer) |
(:mixed) | A single URI segment; may be empty. | (:?mixed) |
(:string) | A non-empty URI segment that cannot contain /. | (:?string) |
(:optional) | An optional URI segment. | No |
(:alphabet) | Letters only (A-Z, a-z). | (:?alphabet) |
(:alphanumeric) | Letters and digits only. | (:?alphanumeric) |
(:username) | Letters, digits, ., _, and -, with an optional @ prefix. | (:?username) |
(:number) | Integers or decimals with an optional + or - sign. | (:?number) |
(:numeric) | Integers or decimals with an optional - sign. | (:?numeric) |
(:version) | Two or more dot-separated numeric components, such as 1.0 or 2.3.4. | (:?version) |
(:double) | Integers or decimals with an optional + or - sign. | (:?double) |
(:float) | Decimal numbers with an optional + or - sign; a decimal point is required. | (:?float) |
(:file) | A filename containing an extension. | (:?file) |
(:filepath) | A file path with zero or more directories and a filename containing an extension. | (:?filepath) |
(:path) | Two or more non-empty URI segments separated by /. | (:?path) |
(:uuid) | A UUID-shaped value in 8-4-4-4-12 hexadecimal format. | (:?uuid) |
(:ulid) | A 26-character ULID using Crockford Base32. | (:?ulid) |
Optional Typed Placeholders
Most typed placeholders support an optional form by prefixing the type with ?.
For example:
(:int) → (:?int)
(:username) → (:?username)
(:uuid) → (:?uuid)The optional form makes the entire URI segment optional, including its preceding /.
(:int) → /users/42
(:?int) → /users or /users/42The (:?type) form is not available for the structural placeholders (:base), (:root), (:group), or (:optional).
Usages
Dynamic User Route
Capture a user's ID and username directly from the URI:
https://example.com/user/42/john-doe→$id = 42,$username = 'john-doe'
#[Route('/user/(:int)/(:username)', methods: ['GET'])]
public function user(int $id, string $username): int
{
return $this->view('user', [
'id' => $id,
'username' => $username
]);
}Optional Segment
Handle both URI forms in a single controller method:
https://example.com/users→$id = nullhttps://example.com/users/12→$id = 12
#[Route('/users/(:?int)', methods: ['GET'])]
public function users(?int $id = null): int
{
if ($id === null) {
return $this->view('users');
}
return $this->view('user', [
'id' => $id,
'user' => User::find($id)
]);
}Defining Custom Placeholders
Luminova allows you to define your own custom pattern placeholders for dynamic routes. Custom placeholders are useful when:
- The same pattern is used across multiple routes.
- A pattern is long or complex.
- You need to extend or override a predefined placeholder.
Custom placeholders can be registered in the Application class using onCreate() or onPreCreate(), or globally in /app/Utils/Global.php. They must be registered before routing starts.
Note
When registering placeholders globally, make sure
feature.app.dev.functionsis enabled in.envto allow/app/Utils/Global.phpto be autoloaded.
// /app/Application.php
namespace App;
use Luminova\Routing\Router;
use Luminova\Foundation\Core\Application as CoreApplication;
class Application extends CoreApplication
{
protected function onPreCreate(): void
{
// Automatically capture the pattern.
Router::pattern('slug', '[a-z0-9-]+');
// Use the pattern without a capturing group.
Router::pattern('slug', '[a-z0-9-]+', 0);
// Wrap the pattern in a capturing group.
Router::pattern('slug', '[a-z0-9-]+', 1);
// Already grouped patterns remain unchanged.
Router::pattern('custom', '([a-z]+)-(\d+)', 1);
// Custom placeholders.
Router::pattern('my-int', '(\d+)');
Router::pattern('my-username', '([a-zA-Z0-9._-]+)');
Router::pattern('my-version', '([+-]?\d+(?:\.\d+)?)');
}
}Using Custom Placeholders with Attribute-Based Routing
Once registered, custom placeholders can be used in route attributes like predefined placeholders.
// /app/Controllers/Http/WebController.php
namespace App\Controllers\Http;
use Luminova\Base\Controller;
use Luminova\Attributes\Route;
use Luminova\Attributes\Prefix;
#[Prefix('/(:root)')]
class WebController extends Controller
{
#[Route('/user/(:my-int)/(:my-username)', methods: ['GET'])]
public function user(int $id, string $username): int
{
// Matches: GET /user/42/john-doe
}
#[Route('/(:my-version)', methods: ['GET'])]
public function file(string $version): int
{
// Matches: GET /user/files/1.5
}
}Using Custom Placeholders with Method-Based Routing
Custom placeholders can also be used with method-based routes.
// /routes/web.php
Router::get('/user/(:my-int)/(:my-username)', 'WebController::user');
Router::get('/file/(:my-version)', 'WebController::file');Once registered, custom placeholders are available to routes throughout the application, allowing you to reuse complex patterns and keep route definitions consistent and maintainable.
Default Placeholders Description
root
Matches the entire remaining path after the route's starting point, including multiple URI segments.
Unlike (:base), (:root) requires the remaining path to begin with a non-empty URI segment. It is intended for routes where the full remaining path needs to be captured as a single value.
Example:
- Pattern:
?(?:/[^/].*)? - Route:
/(:root) - URI:
/about/company - Matched Value:
about/company
Use Case:
Use (:root) when a route needs to capture the remaining URI path, such as controller-level routes, middleware, or grouped routes that handle multiple sub-paths.
(:root)does not support the optional(:?root)form.
base
Matches the base route with or without additional path segments.
Unlike (:root), (:base) is permissive and allows anything after the base path, including an empty or nested path. The additional path is matched but is not intended to be captured as a route parameter.
Example:
- Pattern:
?(?:/.*)? - Route:
/dashboard(:base) - URI:
/dashboard - Matched Value: (none)
- URI:
/dashboard/stats/2024 - Matched Value: (none; additional path is ignored)
Use Case:
Use (:base) when a route should match its base path and anything below it, such as controller-level prefixes with Luminova\Attributes\Prefix, entry points, or feature modules that handle their own internal routing.
(:base)does not support the optional(:?base)form.
group
Matches any characters, including /, and can also match an empty value.
Unlike (:string) and (:mixed), (:group) can span multiple URI segments because it is not restricted by /.
Example:
- Pattern:
(.*) - Route:
/content/(:group) - URI:
/content/articles/2024/intro - Matched Value:
articles/2024/intro
It can also match an empty value:
- URI:
/content/ - Matched Value: (empty string)
Use Case:
Use (:group) when you need to capture an unrestricted portion of the URI, including multiple nested segments.
(:group)does not support the(:?group)form.
mixed
Matches zero or more characters except /.
Unlike (:string), (:mixed) can match an empty value. It matches characters within a single URI segment and cannot cross /.
Example:
- Pattern:
([^/]*) - Route:
/user/(:mixed) - URI:
/user/ - Matched Value: (empty string)
- URI:
/user/1234 - Matched Value:
1234
Use Case:
Use (:mixed) when a URI segment may be empty but must not contain /.
(:?mixed)is also supported when the entire URI segment is optional.
string
Matches one or more characters except /.
Unlike (:mixed), (:string) requires at least one character. It can contain letters, numbers, and other characters as long as the value does not contain /.
Example:
- Pattern:
([^/]+) - Route:
/profile/(:string) - URI:
/profile/user_123 - Matched Value:
user_123
Use Case:
Use (:string) for a required URI segment when the value can contain arbitrary characters but must remain within a single segment.
(:?string)is also supported when the segment is optional.
integer
Matches one or more digits (0–9).
The (:int) and (:integer) placeholders use the same pattern and are interchangeable.
Alias:
(:int) and (:integer)
Example:
- Pattern:
(\d+) - Route:
/user/(:int) - URI:
/user/42 - Matched Value:
42
Use Case:
Use (:int) or (:integer) when a route parameter must contain digits only.
Both
(:?int)and(:?integer)are supported for optional integer segments.
float
Matches a decimal number with a required decimal point and an optional + or - sign.
It requires at least one digit before and after the decimal point.
Example:
- Pattern:
([+-]?\d+\.\d+) - Route:
/discount/(:float) - URI:
/discount/-25.50 - Matched Value:
-25.50
Use Case:
Use (:float) when a route must contain a decimal number and integers should not be accepted.
Examples of matching values include:
10.5
-25.50
+3.14
(:?float)is also supported when the decimal segment is optional.
double
Matches integers or decimal numbers with an optional + or - sign.
A decimal point is optional, but when present it must be followed by one or more digits. A trailing decimal point is not allowed.
Example:
- Pattern:
([+-]?\d+(?:\.\d+)?) - Route:
/temperature/(:double) - URI:
/temperature/98.6 - Matched Value:
98.6
Examples of matching values:
98
98.6
-25.50
+10.25Key Difference Between double and float:
(:float)requires a decimal point.(:double)allows both integers and decimals.- Both use a numeric string pattern;
doubledoes not enforce PHP double-precision behavior at the routing level.
Use Case:
Use (:double) when a route parameter can contain either an integer or decimal numeric value.
(:?double)is also supported for optional numeric segments.
numeric
The (:numeric) and (:number) placeholders matches integers or decimal numbers with an optional - sign.
A decimal point is optional, but when present it must be followed by one or more digits. A leading + sign is not allowed.
Example:
- Pattern:
([-]?\d+(?:\.\d+)?) - Route:
/price/(:numeric) - URI:
/price/49.99 - Matched Value:
49.99
Examples of matching values:
49
49.99
-10
-25.50The following values do not match:
+10
+25.50
10.Use Case:
Use (:numeric) for general numeric route parameters where integers and decimals are allowed, with an optional negative sign.
(:?numeric)is also supported for optional numeric segments.
Unlike
(:number)and(:double),(:numeric)does not allow a leading+sign.
uuid
Matches a UUID-formatted value containing 32 hexadecimal characters separated by four hyphens.
The pattern checks the UUID structure but does not validate a specific UUID version or variant.
Example:
- Pattern:
([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}) - Route:
/resource/(:uuid) - URI:
/resource/550e8400-e29b-41d4-a716-446655440000 - Matched Value:
550e8400-e29b-41d4-a716-446655440000
Use Case:
Use (:uuid) for routes that use UUID-formatted identifiers, such as resource IDs.
(:?uuid)is also supported for optional UUID segments.
ulid
Matches a 26-character ULID using the standard Crockford Base32 character set, excluding ambiguous characters such as I, L, O, and U.
The pattern is case-insensitive and restricts the first character to 0–7, which is required for a valid 26-character ULID.
Example:
- Pattern:
([0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}) - Route:
/resource/(:ulid) - URI:
/resource/01ARZ3NDEKTSV4RRFFQ69G5FAV - Matched Value:
01ARZ3NDEKTSV4RRFFQ69G5FAV
Use Case:
Use (:ulid) for routes that use ULIDs as resource identifiers, such as database records, API resources, or public URLs.
(:?ulid)is also supported for optional ULID segments.
username
Matches usernames containing letters, numbers, dots (.), underscores (_), and hyphens (-), with an optional @ at the beginning.
The pattern does not restrict the position or combination of these characters beyond the allowed character set.
Example:
- Pattern:
(@?[a-zA-Z0-9._-]+) - Route:
/profile/(:username) - URI:
/profile/user_123 - Matched Value:
user_123
It also matches values such as:
john-doe
user_123
john.doe
@john-doeUse Case:
Use (:username) for usernames, handles, slugs, or other identifiers that require a restricted character set.
(:?username)is also supported for optional username segments.
version
Matches numeric version strings containing two or more numeric components separated by dots.
Each component must contain at least one digit.
Example:
- Pattern:
(\d+(?:\.\d+)+) - Route:
/package/(:version) - URI:
/package/3.6.6 - Matched Value:
3.6.6
Examples of matching values include:
1.0
2.1
3.6.6
10.25.100Use Case:
Use (:version) for numeric version strings such as API versions, package versions, and software release versions.
(:?version)is also supported for optional version segments.
optional
Matches an optional URI segment. The segment may be omitted or provided as a value, and it cannot cross / boundaries.
Unlike (:?type) placeholders, (:optional) is a general-purpose placeholder that does not apply a specific data type or validation pattern.
Example:
- Pattern:
?(?:/([^/]*))? - Route:
/product/(:optional) - URI:
/product - Matched Value: (no segment)
- URI:
/product/123 - Matched Value:
123
Use Case:
Use (:optional) when a route needs a general optional segment without restricting its value to a specific predefined type.
For type-specific optional segments, use the
(:?type)form instead.
alphanumeric
Matches letters and numbers only (A–Z, a–z, and 0–9).
Spaces, symbols, and other characters are not allowed.
Example:
- Pattern:
([a-zA-Z0-9]+) - Route:
/category/(:alphanumeric) - URI:
/category/electronics123 - Matched Value:
electronics123
Use Case:
Use (:alphanumeric) for identifiers that should contain only letters and numbers.
(:?alphanumeric)is also supported for optional alphanumeric segments.
alphabet
Matches letters only (A–Z and a–z).
Numbers, spaces, and symbols are not allowed.
Example:
- Pattern:
([a-zA-Z]+) - Route:
/name/(:alphabet) - URI:
/name/Peter - Matched Value:
Peter
Use Case:
Use (:alphabet) when a URI segment must contain alphabetic characters only.
(:?alphabet)is also supported for optional alphabetic segments.
path
Matches two or more non-empty URI segments separated by /.
Unlike (:string), (:path) can cross / boundaries and captures the complete multi-segment path as a single value.
Example:
- Pattern:
([^/]+(?:/[^/]+)+) - Route:
/files/(:path) - URI:
/files/images/2024/summer/beach.png - Matched Value:
images/2024/summer/beach.png
Use Case:
Use (:path) when you need to capture a nested path containing multiple URI segments, such as directory paths or hierarchical resources.
(:?path)is also supported for optional multi-segment paths.
file
Matches a filename with an extension within a single URI segment.
The filename must contain at least one character before the dot and at least one character after it. It cannot contain /.
Example:
- Pattern:
([^/]+\.[^/]+) - Route:
/download/(:file) - URI:
/download/report.pdf - Matched Value:
report.pdf
Examples of matching values include:
index.php
report.pdf
photo.jpg
archive.tar.gzUse Case:
Use (:file) when a route should capture a single filename, such as documents, images, scripts, or other resources.
(:?file)is also supported for optional file segments.
filepath
Matches a file path containing one or more directories and a filename with an extension.
Each path segment must be non-empty, and the final segment must contain a file extension. The captured value does not include a leading /.
Example:
- Pattern:
((?:[^/]+/)*[^/]+\.[^/]+) - Route:
/download/(:filepath) - URI:
/download/documents/2024/reports/annual.pdf - Matched Value:
documents/2024/reports/annual.pdf
The filename can also be in the current directory:
report.pdf
documents/report.pdf
documents/2024/report.pdfUse Case:
Use (:filepath) when a route needs to capture a file together with its directory path, such as downloadable resources, assets, or nested files.
(:?filepath)is also supported for optional file paths.