getphred/atlas

A high-performance, modular PHP routing engine with PSR-7 support.

dev-master 2026-02-15 19:19 UTC

Requires

• php: ^8.2
• psr/http-message: ^1.0 || ^2.0

Requires (Dev)

• phpstan/phpstan: ^1.10
• phpunit/phpunit: ^10.0
• squizlabs/php_codesniffer: ^3.7

MIT

• Phred

README

A high-performance, modular PHP routing engine designed for professional-grade applications. It prioritizes developer experience, architectural purity, and interoperability through PSR-7 support.

Features

• Fluent API: Expressive and chainable route definitions.
• Dynamic Matching: Support for {{parameters}} and {{optional?}} segments.
• Parameter Validation: Strict validation rules (numeric, alpha, regex, etc.).
• Route Groups: Recursive grouping with prefix and middleware inheritance.
• Modular Routing: Automatic route discovery from modules.
• Reverse Routing: Safe URL generation with parameter validation.
• PSR-7 Support: Built on standard HTTP message interfaces.
• Advanced Capabilities: Subdomain constraints, i18n support, and redirects.
• Developer Tooling: Programmatic Inspector API and CLI tools.
• Performance: Optimized matching engine with route caching support.

Installation

composer require getphred/atlas

Basic Usage

use Atlas\Router\Router;
use Atlas\Config\Config;
use GuzzleHttp\Psr7\ServerRequest;

// 1. Setup Configuration
$config = new Config([
    'modules_path' => __DIR__ . '/src/Modules',
]);

// 2. Initialize Router
$router = new Router($config);

// 3. Define Routes
$router->get('/users', function() {
    return 'User List';
})->name('users.index');

$router->get('/users/{{id}}', function($id) {
    return "User $id";
})->name('users.show')->valid('id', 'numeric');

// 4. Match Request
$request = ServerRequest::fromGlobals();
$route = $router->match($request);

if ($route) {
    $handler = $route->getHandler();
    // Execute handler...
} else {
    // 404 Not Found
}

Route Groups

$router->group(['prefix' => '/api', 'middleware' => ['auth']])->group(function($group) {
    $group->get('/profile', 'ProfileHandler');
    $group->get('/settings', 'SettingsHandler');
});

All group routes inherit whatever options you pass in (middleware, prefix, etc).

While the above syntax works and is completely viable, I find the double group method syntax a bit confusing.

So, here is another way you can do it (my personal preferred method) that is, in my opinion, cleaner, and more readable.

$api = $router->group(['prefix' => '/api']);

$api->get('/users', 'UserIndexHandler');
$api->post('/users', 'UserCreateHandler');

Performance & Caching

For production environments, you can cache the route collection:

if ($cache->has('routes')) {
    $routes = unserialize($cache->get('routes'));
    $router->setRoutes($routes);
} else {
    // Define your routes...
    $cache->set('routes', serialize($router->getRoutes()));
}

CLI Tools

Atlas comes with a CLI tool to help you debug your routes:

# List all routes
./atlas route:list

# Test a specific request
./atlas route:test GET /users/5

License

The MIT License (MIT). Please see License File for more information.