Luminova Framework

PHP Luminova: Method URI Prefixing for Route Context Files

Last updated: 2025-08-21 18:33:14

The Method-Based URI prefix makes it easier to manage and optimize the routing system for request handling when using low-level method route definitions instead of attributes.

The Method-Based URI Prefix in Luminova helps you organize and speed up your routing system when defining routes directly in code instead of using attributes.

You typically set this up in /public/index.php using the router’s context method. It groups routes by URI prefix so that only the necessary routes are loaded for a given request, reducing overhead and improving performance.

This approach keeps your codebase cleaner by separating concerns. Each context clearly shows its URI prefix and error handler, making the routing setup easier to read and understand at a glance.


Why Use Prefix

Think of route prefixes like labels on storage boxes. Instead of throwing all your stuff in one big box and digging through it every time, you put “Web,” “API,” or “CLI” on the boxes and know exactly where things live.

Without prefixes, every route sits in the same pile. That works for small projects — until it doesn’t. As your app grows, you’ll have HTTP routes mixed with admin routes, API endpoints, maybe even CLI commands. Good luck finding what’s what when you come back six months later.

With prefixes:

  • You only write /api or /admin once, instead of repeating it on every single route.
  • Your routes are naturally grouped — “all the web pages here, all the API calls there.”
  • Changing a group later is way easier — update one prefix, done.

And it’s not just about staying organized — bad route structure can actually slow things down. Without prefixes, the routing system has to scan every single route to find a match. Even worse, a sloppy pattern can accidentally match the wrong route, leading to bugs that make you question reality (or at least your coffee intake).

So, do you have to use prefixes? No. But do they save you from future headaches? Absolutely.It’s like labeling those boxes now so you’re not unpacking your garage every time you need a screwdriver.


Prefix Usages

You can define routing prefixes in two ways: using the Prefix class or using an array configuration.Prefixes are registered in /public/index.php using the router’s context() method.

Notes:

  • The prefix name must match the file name in /routes/ for routing to work correctly.
  • Your error handler (e.g., onApiError) must exist in the specified class (ErrorController or any custom error controller).

Using the Prefix Class

With a Prefix object, all URLs starting with the given prefix are automatically routed to the matching file in /routes/.For example, requests beginning with /api will load /routes/api.php.

The Prefix class takes two parameters:

  • $prefix (string) – The URI prefix name.
  • $onError (\Closure|array\<int,string>|null) – A handler for 404 errors in this context.
// /public/index.php

use Luminova\Boot;
use Luminova\Routing\Prefix;
use App\Errors\Controllers\ErrorController;

Boot::http()->router->context(
   new Prefix(Prefix::WEB, [ErrorController::class, 'onApiError']),
   new Prefix(Prefix::API, [ErrorController::class, 'onApiError']),
   new Prefix(Prefix::CLI),
   // ...
)->run();

Using Array Configuration

You can also define prefixes as associative arrays.This approach avoids initializing Prefix objects at runtime, which can be more efficient when you have many route contexts.

Each prefix must define:

  • prefix (string) – The URI prefix name.
  • error (Closure|array|null) – Optional 404 error handler.
// /public/index.php

use Luminova\Boot;
use App\Errors\Controllers\ErrorController;

Boot::http()->router->context(
   [
      'prefix' => 'web',
      'error'  => [ErrorController::class, 'onWebError']
   ],
   [
      'prefix' => 'api',
      'error'  => [ErrorController::class, 'onApiError']
   ],
   [
      'prefix' => 'cli'
   ],
   // ...
)->run();

Tip:Use Prefix objects if you want clear type-safety and IDE support. Use arrays when optimizing for performance with many prefixes.


Prefix Context File

After adding a new route prefix in public/index.php, you need to create a matching handler file in the /routes/ directory. The file name must match the prefix name.

For example, if you register the prefix admin, create /routes/admin.php:

// /routes/admin.php

$router->get('/', 'AdminController::login');
$router->get('/dashboard', 'AdminController::dashboard');

Now, any URL starting with /admin (e.g.,https://example.com/admin,https://example.com/admin/foo, orhttps://localhost/example.com/public/admin)will automatically load routes from admin.php.


Class Definition

  • Class namespace: Luminova\Routing\Prefix
  • This class is marked as final and can't be subclassed

Constants

Predefined Prefixes

The framework reserves certain URI prefix names for common use cases. You can still define your own, but these built-ins cover the most frequent scenarios:

ConstantValueReservedDescription
WEBwebYesDefault prefix for standard HTTP request URIs.
CLIcliYesDefault prefix for all CLI commands.
APIapiNoSuggested custom prefix for API routes (/api).
PANELpanelNoSuggested custom prefix for control panel routes.
ADMINadminNoSuggested custom prefix for admin routes (/admin).
CONSOLEconsoleNoSuggested custom prefix for console routes.
WEBHOOKwebhookNoSuggested custom prefix for webhook endpoints.

WEB Prefix

The WEB prefix is reserved and cannot be renamed.It is automatically applied to all HTTP request URIs that don't explicitly use another prefix (for example, https://example.com/ or other public URLs). The associated route context file is always /routes/web.php, and this filename cannot be changed.


CLI Prefix

The CLI prefix is also reserved and cannot be renamed.It is used for handling all command-line routes, and the route context file is always /routes/cli.php.


Methods

constructor

Initialize constructor to register a router prefix.

public __construct(string $prefix, \Closure|array|null $onError = null): mixed

Parameters:

ParameterTypeDescription
$prefixstringThe route URL prefix name to handle (e.g, blog).
$onError\Closure|array<int,string>|nullOptional prefix context error handler.

Error handler supports any callable, or list array with two elements, the first element should be class name while the second is method name.