Luminova Framework

PHP Luminova: Dynamic URI Segment Capturing

Last updated: 2026-08-30 21:24:32

Define routes with raw regular expressions for precise and flexible URL matching when predefined placeholders cannot meet your routing requirements.

URI segment capturing allows you to extract values from a request URI or CLI command and pass them as arguments to controller methods or closure handlers.

The Routing System resolves captured values and injects them into the handler, similar to Dependency Injection. Captured values support union types and strict type validation.

There are three ways to define capture patterns:

  • Predefined Pattern Placeholders (Recommended)

    /foo/(:string)/(:int)

    Uses built-in placeholders with automatic type validation.

  • Regular Expressions (Advanced)

    /foo/([a-zA-Z0-9]+)/([0-9]+)

    Provides full control over matching but requires more complex patterns.

  • Named Placeholders (Basic)

    /foo/{title}/{id}

    Provides a simple and readable way to capture segments with less control over validation.

While regular expressions provide the most flexibility, predefined placeholders offer the best balance of readability, validation, and convenience. Named placeholders are useful when simple segment capturing is sufficient.


Using Predefined Placeholders

Predefined placeholders let you create dynamic routes without writing regular expressions.

They make routes readable, maintainable, and type-aware by matching each segment against a predefined pattern.

Each placeholder captures one URL segment and validates its value before the controller method is called.

See Predefined Pattern Placeholders for the available placeholders.


Attribute-Based Routing

Attribute-based routing keeps route definitions close to the controller methods they belong to, making it easy to see which URLs a method handles.

// /app/Controllers/Http/WebController.php

namespace App\Controllers\Http;

use Luminova\Attributes\Route;
use Luminova\Base\Controller;

class WebController extends Controller
{
    #[Route('/user/(:int)/(:username)', methods: ['GET'])]
    public function user(int $id, string $username): int
    {
        // Matches: GET /user/42/john-doe
        // (:int)      → $id        (integer)
        // (:username) → $username  (valid username)
    }

    #[Route('/file/(:numeric)', methods: ['GET'])]
    public function file(string $version): int
    {
        // Matches: GET /file/1.5
        // (:numeric) → $version (integer or decimal)
    }
}

Method-Based Routing

Method-based routing defines routes in a centralized route file.

This approach is simple and familiar, making it a good choice for smaller projects or teams that prefer keeping route definitions together.

// /routes/web.php

Router::get('/user/(:int)/(:username)', 'WebController::user');

Router::get('/file/(:numeric)', 'WebController::file');

Using Named Placeholders

Named placeholders let you define dynamic route segments using readable names instead of patterns.

They make routes easy to understand at a glance, but do not perform type validation. A named placeholder matches any non-empty segment regardless of its value.

In simple terms:

If the URL matches the route structure, the route matches, even if the captured value is invalid for your application.

Use named placeholders when readability and simplicity are more important than strict route-level validation.


Named Attribute-Based Routing

This style keeps the route definition close to the controller method, making it easy to see which URLs are handled by each method.

// /app/Controllers/Http/WebController.php

namespace App\Controllers\Http;

use Luminova\Attributes\Route;
use Luminova\Base\Controller;

class WebController extends Controller
{
    #[Route('/user/{id}/{username}', methods: ['GET'])]
    public function user(int $id, string $username): int
    {
        // Matches: GET /user/42/john-doe
        // Also matches: GET /user/abc/anything
        // No type validation is performed by the route.
    }

    #[Route('/file/{version}', methods: ['GET'])]
    public function file(string $version): int
    {
        // Matches: GET /file/1.5
        // Also matches: GET /file/anything-here
    }
}

Important

  • {id} and {username} match any non-empty text.
  • PHP type hints do not affect whether the route matches.
  • Validate captured values inside the method when application-level validation is required.

Named Method-Based Routing

This approach defines routes in a central route file.

It is straightforward and familiar, especially for developers who prefer centralized routing.

// /routes/web.php

Router::get('/user/{id}/{username}', 'WebController::user');

Router::get('/file/{version}', 'WebController::file');

How It Behaves

Named placeholders:

  • Match any non-empty value for the corresponding segment.
  • Perform no type validation at the routing level.
  • Require manual validation when specific input types or formats are needed.

Note

For strict route-level matching, use predefined placeholders such as (:int) or (:number) instead.


Using Raw Regular Expressions

Raw regular expressions give you full control over how a route matches a URL.

Unlike predefined placeholders, you write and maintain the matching patterns yourself. This makes regex routes powerful and flexible, but also harder to read, debug, and maintain.

Use raw regular expressions only when predefined placeholders cannot express the matching rules you need.


Regex Attribute-Based Routing

Routes can be defined directly on controller methods using regular expressions.

// /app/Controllers/Http/WebController.php

namespace App\Controllers\Http;

use Luminova\Attributes\Route;
use Luminova\Base\Controller;

class WebController extends Controller
{
    #[Route('/user/(\d+)/([a-zA-Z0-9._-]+)', methods: ['GET'])]
    public function user(int $id, string $username): int
    {
        // Matches: GET /user/42/john-doe
        // (\d+)                → numeric user ID
        // ([a-zA-Z0-9._-]+)    → username
    }

    #[Route('/file/([+-]?\d+(?:\.\d+)?)', methods: ['GET'])]
    public function file(string $version): int
    {
        // Matches: GET /file/1.5
        // Accepts integers or decimal numbers
    }
}

Regex Method-Based Routing

Routes can also be defined in a central routing file using regular expressions.

// /routes/web.php

Router::get('/user/(\d+)/([a-zA-Z0-9._-]+)', 'WebController::user');

Router::get('/file/([+-]?\d+(?:\.\d+)?)', 'WebController::file');

Recommendation

Prefer predefined placeholders whenever possible. They provide a clearer and more maintainable way to define common matching rules while reducing the chance of routing errors.