model/router

There is no license information available for the latest version (v0.2.33) of this package.

Routing module for ModEl Framework

v0.2.33 2026-02-10 14:33 UTC

Requires

• ext-mbstring: *
• model/cache: ^0.5.3
• model/config: ^0.7.0
• model/events: ^0.2.1
• model/providers-finder: ^0.3.7

Unknown License

• Domenico Giambra

README

A standalone, framework-agnostic PHP router with bidirectional routing support, multi-field URL segments, and relationship resolution.

Features

• Modern route syntax with :parameter notation
• Multi-field segments: /users/:name-:surname
• Relationship fields: /products/:category.name/:id-:name
• Bidirectional routing: Parse URLs and generate URLs
• Database integration via dependency injection
• Framework-agnostic: Works as a standalone package

Installation

The router is designed as a standalone package. You can use install it via Composer:

composer require model/router

Basic Usage

1. Create Router providers

use \Model\Router\AbstractRouterProvider;

class RouterProvider extends AbstractRouterProvider {
    public function getRoutes(): void {
        return [
            [
                'pattern' => '/pages/:name',
                'controller' => 'PageController',
                'options' => [
                    'entity' => [
                        'table' => 'pages',
                    ],
                ],
            ],
            [
                'pattern' => '/users/:name-:surname',
                'controller' => 'UserController',
                'options' => [
                    'entity' => [
                        'table' => 'users',
                    ],
                ],
            ],
        ];
    }
}

### 2. Create Router

```php
use Model\Router\Router;

// If your route do not use database lookups
$router = new Router();

// If they use database lookups, provide a Resolver instance
$resolver = new YourDatabaseResolver(); // Implement the Resolver interface
$router = new Router($resolver);

3. Match Incoming URLs

$url = '/pages/about-us';
$result = $router->match($url);

if ($result) {
	$controller = $result['controller']; // 'PageController'
	$params = $result['params']; // ['id' => 5] (from database lookup)
}

4. Generate URLs

// Generate URL with ID
$url = $router->generate('PageController', 5);
// Result: /pages/about-us

// Generate URL with explicit parameters
$url = $router->generate('UserController', [
	'name' => 'John',
	'surname' => 'Doe',
]);
// Result: /users/john-doe

Route Syntax

Simple Parameters

[
    'pattern' => '/pages/:name',
    'controller' => 'PageController',
    'options' => [
        'entity' => [
            'table' => 'pages',
        ],
    ],
]

URL: /pages/about-us → Looks up page with name = 'about-us'

Numeric IDs

[
    'pattern' => '/pages/:id',
    'controller' => 'PageController',
]

URL: /pages/123 → Directly matches ID 123

Multiple Fields in One Segment

[
    'pattern' => '/pages/:name-:surname',
    'controller' => 'UserController',
    'options' => [
        'entity' => [
            'table' => 'users',
        ],
    ],
]

URL: /users/john-doe-smith → Tries combinations:

• name='john' AND surname='doe-smith'
• name='john-doe' AND surname='smith'

Relationship Fields

[
    'pattern' => '/products/:category.name/:id-:name',
    'controller' => 'ProductController',
    'options' => [
        'entity' => [
            'table' => 'products',
        ],
    ],
]

URL: /products/electronics/123-laptop → Looks up:

1. Category with name = 'electronics'
2. Product with id = 123 AND name = 'laptop'

Route Options

Available Options

• table (string): Database table for lookups
• primary (string): Primary key field name (default: 'id')
• relationships (array): Relationship configuration
• case_sensitive (bool): Case-sensitive matching (default: false)
• tags (array): Additional metadata for route filtering
• lowercase (bool): Convert generated URLs to lowercase (default: true)

Example with All Options

[
    'pattern' => '/blog/:category.name/:id-:slug',
    'controller' => 'BlogController',
    'options' => [
        'entity' => [
            'table' => 'blog_posts',
        ],
        'case_sensitive' => false,
        'tags' => [
            'lang' => 'en',
            'type' => 'public',
        ],
        'lowercase' => true,
]

URL Generation with Tags

Generate URLs for specific route variants using tags:

// Generate for specific language
$url = $router->generate('PageController', 5, ['lang' => 'en']);
// Result: /pages/about-us

$url = $router->generate('PageController', 5, ['lang' => 'it']);
// Result: /pagine/chi-siamo

Advanced Features

Custom URL Encoding

The router automatically converts field values to URL-friendly format:

• Converts to lowercase
• Replaces spaces with dashes
• Removes special characters
• Supports Unicode characters (Cyrillic, Chinese, etc.)

Caching

The UrlGenerator caches database lookups during URL generation to minimize queries. Routes are also cached after first loading.

Combination Algorithm

For multi-field segments, the router generates all possible word distributions and tries each until finding a match.