Basic Routes

Routing in SigmaPHP is designed to be simple, explicit, and easy to scale. Routes are defined using plain PHP arrays, making them easy to read, maintain, and organize across multiple files as your application grows. Whether you are building a small website or a large API, the router keeps everything predictable and structured.

Basic Setup

Routes can be stored in separate files and loaded into your application. Splitting routes into multiple files is recommended, allowing you to organize web routes, API endpoints, or admin routes independently.

web.php

<?php

return [
    [
        'name' => 'users.profile',
        'path' => '/users/profile',
        'method' => 'get',
        'controller' => UserController::class,
        'action' => 'profile',
    ],
];
    

api.php

<?php

return [
    [
        'name' => 'api.users.profile',
        'path' => '/api/v1/users/profile',
        'method' => 'get',
        'controller' => UserApiController::class,
        'action' => 'profileJson',
    ],
];
    

To define a route, simply append a new route array. At minimum, a route requires a path and an action.

$routes = [
    [
        'name' => 'users.profile',
        'path' => '/users/profile',
        'method' => 'get',
        'controller' => UserController::class,
        'action' => 'profile',
    ],
    [
        'path' => '/users/bio',
        'controller' => UserApiController::class,
        'action' => 'userBio',
    ],
];
    

Naming routes is optional but highly recommended. Named routes make URL generation easier and help avoid hard-coding paths across the application.

The global helper baseUrl() returns the full application base URL including protocol, domain, and configured base path.

print baseUrl();

# http://localhost/
    

HTTP Methods

SigmaPHP Router supports all common HTTP methods such as GET, POST, PUT, PATCH, and DELETE. A route may accept one or multiple methods.

$routes = [
    [
        'name' => 'users.profile',
        'path' => '/users/profile',
        'method' => 'get,post',
        'controller' => UserController::class,
        'action' => 'profile',
    ],
];
    

You may also use the special any method to accept all HTTP methods. If no method is specified, the router automatically defaults to GET.

'method' => 'any'
    

TRACE and CONNECT methods are intentionally unsupported for security reasons. HEAD requests behave like GET without a response body, and OPTIONS requests automatically return allowed methods.

Parameters

Route parameters use curly bracket syntax and are automatically passed to the controller action in the same order.

'path' => '/admin/users/{user_id}/addresses/{address_id}',

// will connect to the action:

public function getUserAddressDetails($userId, $addressId) {
    ...
}
    

Optional parameters can be defined using ? and must appear only at the end of the route path.

'path' => '/products/{id?}',
    

Optional parameters should include default values in the controller action.

public function list($id = null) {
    ...
}
    

Query parameters are automatically available through the global $_GET variable.

curl http://localhost/products?page=2&per_page=10
    

Validation

Routes may include validation rules using regular expressions. If validation fails, the router will automatically return a 404 response.

$routes = [
    [
        'name' => 'orders.show',
        'path' => '/orders/details/{order_id}',
        'method' => 'get',
        'controller' => OrderController::class,
        'action' => 'show',
        'validation' => [
            'order_id' => '[0-9]+'
        ]
    ],
];
    

In the example above, the router will match only an order_id that contains digits. Therefore, a URL such as /orders/details/abcd will not be matched, and the router will return a 404 – Page Not Found response.

Actions

Actions define what happens when a route is successfully matched. In most cases, an action points to a controller class and a specific method that will handle the incoming request, execute the required business logic, and return a response.

The router resolves the controller from the container, then calls the specified method. This keeps route definitions clean while allowing controllers to remain focused on a single responsibility.

'controller' => OrderController::class,
'action' => 'show',
    

In the example above, once the route is matched, the router will instantiate OrderController and execute the show() method. Route parameters, request objects, or dependencies may be automatically injected depending on the framework configuration.

Route Groups

Route groups allow applying prefixes, controllers, or middlewares to multiple routes at once, reducing duplication and improving organization.

[
    'group' => 'api',
    'prefix' => '/api/v1/',
    'controller' => UserApiController::class,
    'middlewares' => [
        [AuthMiddleware::class, 'handler'],
        [UserAccountIsActiveMiddleware::class, 'handler'],
    ],
    'routes' => [
        [
            'name' => 'users.profile',
            'path' => '/users/profile',
            'method' => 'get',
            'action' => 'show'
        ],
        [
            'name' => 'users.profile',
            'path' => '/users/profile',
            'method' => 'put',
            'action' => 'update'
        ],
        // rest of the routes....
    ]
]
    

The only required elements for a route group are the group name and the routes array. The group name is automatically prefixed to all contained routes. For example, the final route name becomes api.users.profile and the full route path becomes /api/v1/users/profile.

The prefix, controller, and middlewares options are completely optional. A route group may define any combination of these settings, or none at all, depending on the application needs.

Route definitions inside a group behave exactly like regular routes, with all features remaining available. If necessary, the group’s default controller can be overridden by explicitly defining a different controller at the route level.

URL Generation

SigmaPHP provides the url() helper to generate URLs using route names and parameters, avoiding hard-coded links.

$routes = [
    [
        'name' => 'order.items.details',
        'path' => '/order/{order_id}/items/{item_id?}',
        'method' => 'get',
        'controller' => OrderController::class,
        'action' => 'getOrderItems',
    ],
];

...

$url = url('order.items.details', [
    'order_id' => 5,
    'item_id' => 10,
]);

# http://localhost/order/5/items/10
    

The router automatically builds the full URL including protocol, domain, and base path configuration.

HTTP Method Override

Since HTML forms support only GET and POST, SigmaPHP implements HTTP Method Override using a hidden _method field. This allows forms to simulate PUT, PATCH, or DELETE requests.

<form action="/products" method="POST">
    <input type="hidden" name="_method" value="PUT" />
    <button type="submit">Save</button>
</form>
    

This feature is enabled by default and can be controlled using the allow_http_method_override option inside the app.php configuration file.

/**
* HTTP method override.
*/
'allow_http_method_override' => true,