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:

Category with name = 'electronics'
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.

model / router

Maintainers

Details