Маршрутизація

Маршрутизатор зіставляє вхідний HTTP-запит (метод + шлях) з обробником (функцією/методом для виконання). Ця сторінка охоплює все, що може маршрутизатор — методи, параметри, іменовані маршрути, групи, middleware, маршрутизацію через атрибути та продакшен-кеш.

Ментальна модель: ви кажете маршрутизатору «коли GET потрапляє на /users/42, виклич цю функцію». Маршрутизатор перекладає це у швидку таблицю пошуку під час завантаження, а потім зіставляє кожен запит із нею.

П’ять базових методів

$app->get   ('/path', $handler);
$app->post  ('/path', $handler);
$app->put   ('/path', $handler);
$app->patch ('/path', $handler);
$app->delete('/path', $handler);

Менш поширені:

$app->any('/path', $handler);                        // GET POST PUT PATCH DELETE OPTIONS HEAD
$app->map(['GET', 'HEAD'], '/path', $handler);       // конкретний набір

Кожен виклик $app->get(...) повертає об’єкт Route, на якому можна будувати плавний ланцюжок (->name(), ->middleware()). Докладніше про це нижче.

Типи обробників

Обробник — це все, що викликається. Lift приймає п’ять різновидів і поводиться з усіма однаково:

// 1. Замикання
$app->get('/ping', fn() => 'pong');

// 2. Замикання з типізованими залежностями (автозв’язуються контейнером)
$app->get('/orders', function (Request $req, OrderService $svc) {
    return $svc->all();
});

// 3. [Class::class, 'method'] — клас розв’язується через DI-контейнер
$app->get('/users', [UserController::class, 'index']);

// 4. Invokable-клас (має __invoke)
$app->get('/healthcheck', HealthcheckAction::class);

// 5. Звичайне ім’я функції у вигляді рядка
$app->get('/old-school', 'my_handler_function');

Для варіантів 2 і 3 Lift дивиться на типи параметрів і автоматично бере екземпляри з контейнера. Вам ніколи не потрібно «реєструвати» контролери; вони автозв’язуються.

Що може повернути обробник

Повернене значення	Що ви отримуєте назад
Об’єкт `Response`	Передається без змін
`array` або `object`	`Response::json(...)`
`string`	`Response::html(...)`
`null`	`Response::noContent()` (204)
будь-що інше (скаляр)	`Response::text((string) $v)`

Тож fn() => ['ok' => true] і fn() => Response::json(['ok' => true]) еквівалентні. Використовуйте те, що читається краще.

Параметри маршруту

Усе, що всередині {...}, захоплюється й стає доступним через $req->param(...):

$app->get('/users/{id}', function (Request $req) {
    $id = $req->param('id');     // завжди рядок
    return ['id' => $id];
});

Отримати всі параметри разом:

$all = $req->params();           // ['id' => '42']

Regex-обмеження

За замовчуванням {param} відповідає [^/]+ — будь-якому символу, окрім /. Щоб вимагати конкретний шаблон, додайте :regex:

$app->get('/posts/{id:\d+}',             $handler);  // лише цифри
$app->get('/files/{name:[a-z0-9-]+}',    $handler);  // slug
$app->get('/cards/{code:[A-Z]{3}-\d{4}}', $handler); // "ABC-1234"

Шлях, який не відповідає regex, провалюється до наступного маршруту (або до 404, якщо нічого не підходить) — ваш обробник ніколи не викликається з некоректним значенням.

НЕПРАВИЛЬНО: іменовані групи PCRE у стилі (?P<name>...) — Lift використовує власний синтаксис плейсхолдерів, а не сирий PCRE. ПРАВИЛЬНО: {name} або {name:pattern}.

Необов’язкові сегменти

Lift не підтримує необов’язкові сегменти шляху всередині одного маршруту (стиль /users[/{id}]). Замість цього зареєструйте два маршрути:

$app->get('/users',       fn() => 'list');
$app->get('/users/{id}',  fn($req) => 'show ' . $req->param('id'));

Іменовані маршрути та генерація URL

Дайте маршруту ім’я через ->name(...), потім будуйте URL за іменем за допомогою $app->url(...):

$app->get('/users/{id}',        $h)->name('users.show');
$app->get('/articles/{slug}',   $h)->name('articles.show');

$app->url('users.show',    ['id'   => 42]);          // /users/42
$app->url('articles.show', ['slug' => 'hello']);     // /articles/hello

Угода про іменування — за вами: users.show, users:show, users-show усі працюють. Угода, що використовується в документації та генераторах, — resource.action (users.index, users.show, users.store, users.update, users.destroy).

Якщо ім’я не існує, $app->url(...) викидає RuntimeException.

Групи маршрутів

Група розділяє спільний префікс шляху (та опційно middleware) серед багатьох маршрутів.

$app->group('/api/v1', function ($group) {
    $group->get   ('/users',          [UserController::class, 'index']);
    $group->get   ('/users/{id:\d+}', [UserController::class, 'show']);
    $group->post  ('/users',          [UserController::class, 'store']);
    $group->put   ('/users/{id:\d+}', [UserController::class, 'update']);
    $group->delete('/users/{id:\d+}', [UserController::class, 'destroy']);
});

Вкладені групи

$app->group('/api', function ($api) {
    $api->group('/v1', function ($v1) {
        $v1->get('/ping', fn() => ['pong' => 'v1']);
    });

    $api->group('/v2', function ($v2) {
        $v2->get('/ping', fn() => ['pong' => 'v2']);
    });
});

Middleware групи

Middleware, застосований до групи, виконується для кожного маршруту всередині неї (та успадковується у вкладені групи):

$app->group('/admin', function ($g) {
    $g->get('/users',    [AdminController::class, 'users']);
    $g->get('/settings', [AdminController::class, 'settings']);
})->middleware(AuthMiddleware::class, RequireAdminMiddleware::class);

Порядок має значення. Middleware, вказаний першим, виконується найзовнішнім — тобто бачить запит раніше за наступні middleware і бачить відповідь після них.

Помаршрутний middleware

Прикріпіть middleware до одного маршруту через ланцюжок ->middleware(...):

$app->post('/users', [UserController::class, 'store'])
    ->middleware(AuthMiddleware::class, RateLimitMiddleware::class);

Порядок виконання на запит:

Глобальний middleware (у порядку $app->use())
  → Middleware групи (від зовнішнього до внутрішнього)
    → Middleware маршруту (у порядку оголошення)
      → Обробник
    ← Middleware маршруту
  ← Middleware групи
← Глобальний middleware

Кожен шар може перервати ланцюжок, повернувши Response замість виклику $handler->handle($request).

404 і 405

Ситуація	Викинуте виняток	Відповідь за замовчуванням
URL не відповідає жодному маршруту	`Lift\Exception\NotFoundException`	404 JSON
URL відповідає маршруту, але з невірним методом	`Lift\Exception\MethodNotAllowedException`	405 JSON

Ви можете налаштувати відповідь через $app->onError(...):

use Lift\Exception\NotFoundException;
use Lift\Exception\MethodNotAllowedException;

$app->onError(function (\Throwable $e, Request $req) {
    if ($e instanceof NotFoundException) {
        return Response::html('<h1>404 — сторінку не знайдено</h1>', 404);
    }
    if ($e instanceof MethodNotAllowedException) {
        return Response::json(['error' => 'method not allowed'], 405);
    }
    return Response::json(['error' => 'server error'], 500);
});

Або під’єднайте конкретний тип винятку:

$app->onException(NotFoundException::class, fn() => Response::html('Not here.', 404));

Повний перелік винятків → Обробка помилок.