README

Быстрый, безопасный и строго типизированный HTTP-роутер для PHP 8.1+ без единой runtime-зависимости.

⚠️ Статус: активная разработка (ветка 0.x). Реализовано текучее ядро маршрутизации (раздел «Возможности»). Остальные пункты из Roadmap находятся в работе и в документации явно помечены как «планируется». Мы принципиально не описываем и не рекламируем то, чего ещё нет в коде — см. сравнение с аналогами, где честно показаны и сильные, и слабые стороны.

Возможности (реализовано)

• Ноль runtime-зависимостей — только сам PHP. Интеграция с PSR-7/PSR-15 будет опциональной.
• Текучее (fluent) определение маршрутов — ->name(), ->where() в цепочке вызовов.
• Все HTTP-глаголы и кастомные методы — get/post/put/patch/delete/head/options, match([...]) для нескольких методов, any(), custom('PURGE', …) для нестандартных методов.
• Параметры и ограничения — /{id} (по умолчанию [^/]+), встроенные /{id:\d+} и ->where('id', '\d+') (приоритет у where()).
• Безопасное сопоставление — статические сегменты экранируются, . и другие мета-символы трактуются буквально, параметр не «перепрыгивает» через /.
• Различение 404 и 405 — «путь не найден» отделён от «метод не разрешён»; для 405 доступен список допустимых методов (для заголовка Allow).
• Именованные маршруты — поиск по имени (getByName()).
• Строгая типизация — declare(strict_types=1), нативные типы, PHPStan max + Psalm level 1.

Требования

• PHP 8.1 или новее.
• Никаких других runtime-зависимостей.

Установка

composer require cloudcastle/http-router

Быстрый старт

use CloudCastle\Http\Router\Router;
use CloudCastle\Http\Router\Exception\MethodNotAllowedException;
use CloudCastle\Http\Router\Exception\RouteNotFoundException;

$router = new Router();

$router->get('/', 'home');
$router->get('/users/{id}', 'users.show')->name('users.show')->where('id', '\d+');
$router->post('/users', 'users.store');
$router->match(['PUT', 'PATCH'], '/users/{id}', 'users.update');
$router->custom('PURGE', '/cache/{key}', 'cache.purge'); // произвольный HTTP-метод

try {
    $match = $router->dispatch($_SERVER['REQUEST_METHOD'], $_SERVER['REQUEST_URI']);

    $action = $match->getRoute()->getAction(); // 'users.show'
    $id     = $match->getParameter('id');      // '42' для /users/42
} catch (MethodNotAllowedException $e) {
    header('Allow: ' . implode(', ', $e->getAllowedMethods()), true, 405);
} catch (RouteNotFoundException $e) {
    http_response_code(404);
}

Действие (action) — любое значение (строка, callable, пара [Controller::class, 'method']): роутер хранит и возвращает его как есть. Исполнение действий появится вместе с ActionResolver.

Сравнение с аналогами (кратко)

Полные таблицы (возможности, качество кода, зависимости) — в docs/ru/comparison.md. Кратко и честно, на текущий момент:

✅ есть · ⚠️ частично / вне ядра · ❌ нет · 🚧 у нас в разработке (см. Roadmap).

Честный вывод: сегодня по широте возможностей мы уступаем зрелым роутерам — многое ещё в разработке. Наши текущие преимущества — ноль зависимостей, строгая типизация и качество кода (ниже). Цель проекта — довести функциональность до уровня «всё, что умеют конкуренты вместе», не потеряв в качестве и безопасности.

Качество

Каждое изменение проходит composer ci: PHP-CS-Fixer + phpcs (PSR-12), PHPStan (max, без baseline), Psalm (level 1), PHPMD, Deptrac, Rector, затем 5 наборов тестов с пофайловым порогом покрытия и мутационным тестированием Infection. Актуальные метрики и методика — в docs/ru/testing.md.

Документация

• Оглавление документации
• Быстрый старт · Базовая маршрутизация · Параметры и ограничения · HTTP-методы
• Именованные маршруты · Обработка ошибок
• Архитектура · Сравнение · Тестирование · Roadmap · FAQ

Лицензия

MIT.