Luminova Framework

PHP Luminova: URI Pattern Type Placeholders

Last updated: 2026-08-30 22:29:19

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.

PlaceholderMatchesOptional 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/42

The (:?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 = null
  • https://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.functions is enabled in .env to allow /app/Utils/Global.php to 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.25

Key Difference Between double and float:

  • (:float) requires a decimal point.
  • (:double) allows both integers and decimals.
  • Both use a numeric string pattern; double does 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.50

The 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-doe

Use 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.100

Use 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.gz

Use 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.pdf

Use 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.