Мини-роутер без фреймворка
Фреймворки классные, но мини-роутер полезно написать хотя бы раз - чтобы понимать, что происходит «под капотом». Если не знаком с методами и кодами - сначала кросс-урок про HTTP.
Идея
Мы хотим, чтобы:
GET /показывал «OK»GET /tasksвозвращал список задачPOST /tasksсоздавал задачуGET /tasks/42возвращал задачу по ID
Шаг 1: Простейший роутер на if/else
public/index.php:
<?php
declare(strict_types=1);
$method = $_SERVER['REQUEST_METHOD'] ?? 'GET';
$path = parse_url($_SERVER['REQUEST_URI'] ?? '/', PHP_URL_PATH) ?: '/';
header('Content-Type: application/json; charset=utf-8');
if ($method === 'GET' && $path === '/') {
echo json_encode(['ok' => true]);
exit;
}
if ($method === 'GET' && $path === '/tasks') {
echo json_encode(['tasks' => []]);
exit;
}
http_response_code(404);
echo json_encode(['error' => 'Not Found']);
ℹ️ Почему parse_url
$_SERVER['REQUEST_URI']содержит и путь, и query-строку (/tasks?page=2).parse_url(..., PHP_URL_PATH)отрезает?query=..., оставляя только путь.
Это работает, но быстро превращается в спагетти. Давай сделаем лучше.
Шаг 2: Роутер как массив
<?php
declare(strict_types=1);
$routes = [
'GET /' => fn() => ['ok' => true],
'GET /tasks' => fn() => ['tasks' => listTasks()],
'POST /tasks' => function () {
$body = json_decode(file_get_contents('php://input'), true, 512, JSON_THROW_ON_ERROR);
$title = $body['title'] ?? '';
if ($title === '') {
http_response_code(400);
return ['error' => 'title is required'];
}
return ['id' => createTask($title), 'ok' => true];
},
];
$method = $_SERVER['REQUEST_METHOD'] ?? 'GET';
$path = parse_url($_SERVER['REQUEST_URI'] ?? '/', PHP_URL_PATH) ?: '/';
$key = "$method $path";
header('Content-Type: application/json; charset=utf-8');
if (isset($routes[$key])) {
$result = $routes[$key]();
echo json_encode($result, JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR);
} else {
http_response_code(404);
echo json_encode(['error' => 'Not Found']);
}
Уже лучше - роуты отделены от логики диспетчеризации.
Шаг 3: Динамические сегменты
Как обработать /tasks/42? Нужны параметры в URL. Для этого понадобятся
регулярные выражения - шаблоны для поиска в строках.
ℹ️ Регулярные выражения: минимум для роутера
Регулярка в PHP записывается строкой с ограничителями:
'#^/tasks/(\d+)$#'- решётки по краям только отмечают начало и конец шаблона (можно и/.../, но в URL много слешей). Внутри:
^и$- начало и конец строки: совпасть должна вся строка, а не её кусок;\d+- одна или больше цифр,[^/]+- один или больше любых символов, кроме/;\w+- буквы, цифры и_;\{- буквальная фигурная скобка;(...)- группа: то, что совпало внутри, сохраняется отдельно;(?<id>...)- именованная группа: совпадение попадёт ещё и в$matches['id'].Две функции:
preg_match($regex, $string, $matches)возвращает1, если строка подходит, и0, если нет; в$matches[0]- всё совпадение, в$matches[1],[2]... - содержимое групп.preg_match('#^/tasks/(\d+)$#', '/tasks/42', $m)даст$m[1] === '42'.preg_replace($regex, $replacement, $string)заменяет все совпадения;$1в замене - содержимое первой группы.Подробнее - в документации: PCRE в PHP.
<?php
declare(strict_types=1);
$routes = [];
function route(string $method, string $pattern, callable $handler): void {
global $routes;
$routes[] = [
'method' => $method,
'pattern' => $pattern,
'handler' => $handler,
];
}
function matchRoute(string $method, string $path): ?array {
global $routes;
foreach ($routes as $route) {
if ($route['method'] !== $method) {
continue;
}
// Превращаем /tasks/{id} в регулярку /tasks/([^/]+)
$regex = preg_replace('#\{(\w+)\}#', '([^/]+)', $route['pattern']);
$regex = '#^' . $regex . '$#';
if (preg_match($regex, $path, $matches)) {
array_shift($matches); // убираем полное совпадение
return ['handler' => $route['handler'], 'params' => $matches];
}
}
return null;
}
Регистрация роутов:
<?php
route('GET', '/', fn() => ['ok' => true]);
route('GET', '/tasks', fn() => ['tasks' => listTasks()]);
route('GET', '/tasks/{id}', function (string $id) {
$task = findTask((int)$id);
if ($task === null) {
http_response_code(404);
return ['error' => 'Task not found'];
}
return $task;
});
route('POST', '/tasks', function () {
$body = json_decode(file_get_contents('php://input'), true, 512, JSON_THROW_ON_ERROR);
return ['id' => createTask($body['title'] ?? ''), 'ok' => true];
});
route('DELETE', '/tasks/{id}', function (string $id) {
deleteTask((int)$id);
http_response_code(204);
return null;
});
Диспетчер:
<?php
$method = $_SERVER['REQUEST_METHOD'];
$path = parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH) ?: '/';
header('Content-Type: application/json; charset=utf-8');
$match = matchRoute($method, $path);
if ($match !== null) {
$result = ($match['handler'])(...$match['params']);
if ($result !== null) {
echo json_encode($result, JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR);
}
} else {
http_response_code(404);
echo json_encode(['error' => 'Not Found']);
}
Настройка веб-сервера
Чтобы все запросы попадали в index.php, нужна перезапись URL.
Встроенный сервер PHP (для разработки):
php -S localhost:8000 -t public/
Встроенный сервер PHP направляет запросы к несуществующим файлам на index.php, но не все: если последний сегмент URI похож на файл (/report.csv), без router-скрипта он отдаст свой 404. Надёжнее передать index.php как router-скрипт: php -S localhost:8000 -t public public/index.php.
Для Nginx:
location / {
try_files $uri /index.php$is_args$args;
}
Для Apache то же правило пишут в public/.htaccess:
RewriteEngine On
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule ^ index.php [QSA,L]
Без такого правила веб-сервер сам ответит 404 на /tasks/42 (файла с таким
именем нет), и запрос до PHP не дойдёт. Единую точку входа, через которую идут
все запросы, называют фронт-контроллером.
Структура проекта
project/
├── public/
│ └── index.php # точка входа (роутер)
├── src/
│ ├── routes.php # определения роутов
│ ├── handlers.php # обработчики (функции)
│ └── db.php # подключение к БД
└── config.php # настройки
public/index.php:
<?php
declare(strict_types=1);
require __DIR__ . '/../config.php';
require __DIR__ . '/../src/db.php';
require __DIR__ . '/../src/handlers.php';
require __DIR__ . '/../src/routes.php';
// Диспетчер (код выше)
ℹ️ Почему public/?
Только
public/доступен из веба. Файлыsrc/иconfig.phpлежат выше - их нельзя запросить через браузер. Это защита от утечки кода и конфигов.
Обработка ошибок в роутере
Глобальный try/catch с разными типами исключений:
<?php
try {
$match = matchRoute($method, $path);
if ($match !== null) {
$result = ($match['handler'])(...$match['params']);
if ($result !== null) {
echo json_encode($result, JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR);
}
} else {
http_response_code(404);
echo json_encode(['error' => 'Not Found']);
}
} catch (JsonException $e) {
http_response_code(400);
echo json_encode(['error' => 'Invalid JSON: ' . $e->getMessage()]);
} catch (PDOException $e) {
error_log('DB error: ' . $e->getMessage());
http_response_code(500);
echo json_encode(['error' => 'Internal Server Error']);
} catch (Throwable $e) {
error_log('Unhandled: ' . $e->getMessage());
http_response_code(500);
echo json_encode(['error' => 'Internal Server Error']);
}
⚠️ Не показывай детали ошибок пользователю
$e->getMessage()может содержать SQL-запрос, путь к файлу, стек вызовов. В продакшне всегда логируй в файл, а пользователю показывай общее сообщение.
Что дальше?
Наш роутер - учебный. В реальных проектах используют библиотеки: nikic/fast-route (минималистичный), league/route, или полноценные фреймворки (Laravel, Symfony). Но принцип тот же: метод + паттерн → обработчик. Полноценное REST-API с валидацией и статус-кодами - в уроке 23.
Типичные ошибки
- Сравнение
REQUEST_URIбезparse_url. Запрос/tasks?page=2не совпадёт с роутом/tasks- в строке остался?page=2. Всегда вытаскивай путь черезparse_url($uri, PHP_URL_PATH). - Регулярка без anchors
^и$. Паттерн/users/(\d+)совпадёт с/admin/users/42/delete. Оборачивай в#^...$#, как в Шаге 3. - Регистрозависимое сравнение путей.
/Usersи/usersдля роутера - разные роуты. В REST API пути обычно case-sensitive (а в сегментах вроде/files/{name}регистр значим), поэтомуstrtolower()всего пути - не обязательная нормализация. Выбери поведение осознанно и задокументируй его; если нужна нечувствительность к регистру - применяй её к статическим сегментам. - Метод из
$_SERVER['REQUEST_METHOD']без normalization. Прокси и тесты иногда шлютgetилиGet. Делайstrtoupper($_SERVER['REQUEST_METHOD'] ?? 'GET'), иначе валидные запросы упадут в 404. - Trailing slash как два разных роута.
/usersи/users/обычно один ресурс, но матчатся раздельно. Нормализуй:$path = rtrim($path, '/') ?: '/';- иначе клиенты ловят 404 на пустом месте.
Best practices
- Различай 404 (нет пути) и 405 (метод не подходит): если путь нашёлся, но метод другой - отвечай
405 Method Not Allowedи заголовкомAllow: GET, POST. - Нормализуй путь один раз в диспетчере:
parse_url+rtrim- дальше роуты пишутся без сюрпризов. - Регистрируй роуты декларативно (массив или билдер), а не через
if/elseif- так проще тестировать и логировать404. - В продакшне бери
nikic/fast-routeили Symfony Routing с атрибутом#[Route('/tasks/{id}', methods: ['GET'])]- свой роутер хорош как учебный, но не как фундамент API. - Покрой роутинг unit-тестами: матчинг паттернов и извлечение параметров - чистая функция без БД, тестируется за минуты и ловит регрессии при добавлении новых роутов.
Готовый роутер в связке с репозиторием на PDO и тестами собран в мини-проекте «Список задач» - там видно, как он живёт рядом с остальными слоями.
Мини-задание
- Добавь роут
GET /health→{ "status": "ok" } - Добавь роут
POST /echo→ возвращает полученный JSON обратно - Реализуй роут
GET /tasks/{id}с динамическим параметром - Добавь обработку ошибок (try/catch с разными типами исключений)
- Вынеси роуты в отдельный файл
src/routes.php