Cykl życia requestu Laravel: Od public/index.php do Response

10 min. czytania

Gdy request na produkcji zwraca dane niewłaściwego tenanta, policy widzi model inny niż oczekujesz albo wartość znika między middleware a kontrolerem, odruchem jest dopisanie kolejnego loga. To może znaleźć objaw, ale nie odpowie, która część Laravel jest właścicielem wartości ani jak długo może ona istnieć.

Cykl życia requestu Laravel jest właśnie taką mapą. Wyjaśnia, jak front controller tworzy aplikację, jak kernel HTTP buduje pipeline middleware, kiedy zachodzą routing i model binding oraz dlaczego response wraca przez ten sam stos. Rysuje też ważną granicę dla długowiecznych workerów Octane: bootstrap aplikacji nie jest tym samym co obsłużenie pojedynczego requestu.

Nie jest to zachęta do zastępowania wnętrza frameworka. Większość aplikacji powinna korzystać ze zwykłych tras, middleware, kontrolerów, form requestów i service providerów. Znajomość ich kolejności sprawia, że punkty rozszerzeń są przewidywalne.

Zacznij od front controllera, nie od pliku tras

Przy zwykłym requeście webowym serwer kieruje każdy request do zasobu innego niż statyczny do public/index.php. W aktualnym Laravel ten plik celowo jest mały: ładuje autoloader Composera, pobiera gotową aplikację, przechwytuje oparty na Symfony request HTTP i prosi Laravel o jego obsłużenie.

php
<?php

declare(strict_types=1);

use Illuminate\Foundation\Application;
use Illuminate\Http\Request;

require __DIR__.'/../vendor/autoload.php';

/** @var Application $app */
$app = require_once __DIR__.'/../bootstrap/app.php';

$app->handleRequest(Request::capture());

Request::capture() raz odczytuje superglobalne PHP i zmienia je w Illuminate\Http\Request. Dlatego kontroler powinien otrzymać request od Laravel zamiast budować go z $_POST: własna konstrukcja ominęłaby normalizację frameworka, obsługę zaufanych proxy, helpery wejścia i fixture'y testowe.

Instancja aplikacji pochodzi z bootstrap/app.php. W Laravel 12 i 13 to tutaj aplikacja deklaruje trasy, aliasy middleware, konfigurację wyjątków i pozostałe hooki bootstrapa. Framework nadal wewnętrznie ma kernel HTTP; aplikacje nie potrzebują już klasy app/Http/Kernel.php tylko po to, by wypisać middleware.

php
<?php

declare(strict_types=1);

use App\Http\Middleware\RequireOrganization;
use Illuminate\Foundation\Application;
use Illuminate\Foundation\Configuration\Exceptions;
use Illuminate\Foundation\Configuration\Middleware;
use Illuminate\Http\Request;
use Symfony\Component\HttpFoundation\JsonResponse;

return Application::configure(basePath: dirname(__DIR__))
    ->withRouting(
        web: __DIR__.'/../routes/web.php',
        api: __DIR__.'/../routes/api.php',
        commands: __DIR__.'/../routes/console.php',
        health: '/up',
    )
    ->withMiddleware(function (Middleware $middleware): void {
        $middleware->alias([
            'organization' => RequireOrganization::class,
        ]);
    })
    ->withExceptions(function (Exceptions $exceptions): void {
        $exceptions->render(function (\DomainException $exception, Request $request): ?JsonResponse {
            if (! $request->expectsJson()) {
                return null;
            }

            return response()->json([
                'message' => $exception->getMessage(),
            ], 422);
        });
    })
    ->create();

Closure konfiguruje aplikację. Nie wykonuje się ponownie za każdym razem, gdy pasuje trasa, i nie jest miejscem na requestowe zapytania do bazy. Providery i hooki bootstrapa ustanawiają możliwości; middleware i akcja trasy wykorzystują je dla jednego requestu.

Bootstrap aplikacji i obsłużenie requestu to różne fazy

W klasycznym wdrożeniu PHP-FPM świeży proces PHP obsługuje request, a następnie kończy działanie. Przez to bootstrap i obsługa wyglądają na nierozłączne. Nie są.

Laravel ładuje konfigurację, rejestruje service providery, tworzy bindingi i bootuje providery, zanim przekaże przechwycony request przez globalne middleware i router. Metoda register() providera opisuje bindingi kontenera. boot() wykonuje się po rejestracji providerów, może więc korzystać z bindingów, zdarzeń, tras i makr. Żadna z nich nie jest właściwym miejscem na odczyt aktualnego konta z requestu.

php
<?php

declare(strict_types=1);

namespace App\Providers;

use App\Billing\InvoiceNumberGenerator;
use App\Billing\SequentialInvoiceNumberGenerator;
use Illuminate\Support\ServiceProvider;

final class BillingServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        $this->app->bind(
            InvoiceNumberGenerator::class,
            SequentialInvoiceNumberGenerator::class,
        );
    }
}

Nie rozwiązuj bieżącego requestu w singletonie podczas register(). Może przypadkiem działać w PHP-FPM i zmienić się w wyciek stanu między requestami pod Octane.

Middleware są zagnieżdżone, nie tworzą płaskiej checklisty

Kernel buduje pipeline. Middleware globalne otaczają każdy request; gdy router wybierze trasę, Laravel dodaje grupę middleware tej trasy i aliasy. Każde middleware decyduje, czy wywołać kolejną warstwę. Wychodzący response rozwija się potem przez warstwy w odwrotnej kolejności.

Ten kształt łatwiej zobaczyć w middleware śledzącym niż na diagramie. Dodaje on identyfikator korelacyjny przed wywołaniem następnej warstwy, zapisuje go do response po powrocie z kontrolera i zapisuje końcową metrykę w terminate() po wysłaniu response.

php
<?php

declare(strict_types=1);

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Illuminate\Support\Str;
use Symfony\Component\HttpFoundation\Response;

final class TraceRequest
{
    public function handle(Request $request, Closure $next): Response
    {
        $traceId = $request->headers->get('X-Request-Id', (string) Str::uuid());

        $request->attributes->set('trace_id', $traceId);

        $response = $next($request);
        $response->headers->set('X-Request-Id', $traceId);

        return $response;
    }

    public function terminate(Request $request, Response $response): void
    {
        logger()->info('HTTP request completed', [
            'trace_id' => $request->attributes->get('trace_id'),
            'status' => $response->getStatusCode(),
        ]);
    }
}

Metoda handle() zawiera kod wykonywany przed i po reszcie pipeline'u. Jeśli zwróci przekierowanie, response albo rzuci wyjątek przed $next($request), kontroler nigdy nie wystartuje. To właściwe dla uwierzytelniania, maintenance mode, rate limitingu i nieprawidłowego nagłówka tenanta. To złe miejsce na regułę potrzebną tylko jednemu endpointowi: dla węższej odpowiedzialności użyj form requestu, policy albo akcji.

Rejestruj globalną odpowiedzialność świadomie, a alias stosuj wyłącznie na trasach, które go potrzebują:

php
<?php

declare(strict_types=1);

use App\Http\Controllers\InvoiceController;
use Illuminate\Support\Facades\Route;

Route::middleware(['auth', 'organization'])
    ->get('/invoices/{invoice}', InvoiceController::class)
    ->name('invoices.show');

Wywołanie append(TraceRequest::class) zostaw w bootstrap/app.php, nie w pliku tras. Middleware trasy działa dopiero po zidentyfikowaniu trasy przez Laravel; globalne middleware działa tak wcześnie, że parametry trasy jeszcze nie istnieją.

Routing, bindingi, autoryzacja i akcja

Gdy routing middleware wchodzi do routera, Laravel dopasowuje metodę i URI, podstawia parametry trasy, wykonuje route model binding i wywołuje akcję. Binding wykonuje middleware SubstituteBindings, które zawierają grupy web i api, więc middleware ustawione przed nim widzą surowe wartości parametrów. Implicit binding zmienia {invoice} w Invoice przez jego route key. Własny klucz, na przykład publiczny UUID, ukrywa identyfikatory bazy w URL, ale nie autoryzuje dostępu. Kontroler nadal musi sprawdzić zalogowanego aktora.

php
<?php

declare(strict_types=1);

namespace App\Http\Controllers;

use App\Models\Invoice;
use Illuminate\Foundation\Auth\Access\AuthorizesRequests;
use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;

final class InvoiceController
{
    use AuthorizesRequests;

    public function __invoke(Request $request, Invoice $invoice): JsonResponse
    {
        $this->authorize('view', $invoice);

        return response()->json([
            'id' => $invoice->public_id,
            'number' => $invoice->number,
            'total_cents' => $invoice->total_cents,
            'currency' => $invoice->currency,
        ]);
    }
}

Middleware autoryzacyjne może odrzucić nieuwierzytelnionego użytkownika przed tym punktem. Policy podejmuje decyzję zależną od zasobu już po bindingu. Traktowanie ich jako alternatyw tworzy albo zduplikowane sprawdzenia, albo lukę autoryzacyjną. Użyteczna kolejność brzmi: ustanów tożsamość, rozwiąż zasób, potem zdecyduj, czy ta tożsamość może wykonać akcję na tym zasobie.

Jeśli request zawiedzie w dowolnej warstwie, konfiguracja wyjątków Laravel otrzymuje wyjątek i zamienia go w response. Nie łap każdego wyjątku w kontrolerze tylko po to, aby zwrócić ogólne 500. Nieoczekiwane wyjątki powinny zachować stack trace i ścieżkę raportowania; oczekiwane błędy domenowe mapuj na centralnej granicy, do której należy reprezentacja HTTP.

Droga powrotna jest nadal częścią requestu

JsonResponse, przekierowanie, widok, streamed response albo odpowiedź Inertia z kontrolera nie trafiają bezpośrednio do Nginx. Przechodzą na zewnątrz przez każde middleware, które wywołało $next. Wtedy często ustawiane są nagłówki response, cookies, obsługa CORS i cleanup podobny do transakcji.

Terminowalne middleware otrzymuje request i response, gdy response jest już przygotowany. Zależnie od SAPI i serwera Laravel może zakończyć odpowiedź dla klienta przed pracą terminującą, ale nie jest to trwała kolejka zadań. Wolne wywołanie API, eksport faktur z retry czy istotny webhook powinny trafić do jobu z kolejką, ponowieniami i monitoringiem, nie do terminate().

php
<?php

declare(strict_types=1);

namespace App\Jobs;

use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Queue\SerializesModels;

final class RecordRequestMetric implements ShouldQueue
{
    use Dispatchable;
    use InteractsWithQueue;
    use Queueable;
    use SerializesModels;

    public function __construct(
        public readonly string $traceId,
        public readonly int $status,
    ) {
    }

    public function handle(): void
    {
        logger()->info('Persisted HTTP metric', [
            'trace_id' => $this->traceId,
            'status' => $this->status,
        ]);
    }
}

Dla istotnej pracy dispatchuj job z akcji będącej właścicielem zdarzenia biznesowego, gdy to właściwe po zatwierdzeniu transakcji. Zalogowanie requestu nie jest tym samym co udowodnienie, że płatność została zapisana.

Cache zmienia start aplikacji, nie jej semantykę

Wdrożenie produkcyjne często uruchamia komendy optymalizacyjne Laravel. Cache konfiguracji kompiluje wartości zwracane przez config/*.php do jednego pliku. Potem wywołanie env() z kontrolera lub serwisu jest niewiarygodne, ponieważ Laravel nie musi już ładować pliku środowiska w runtime. Odczyt środowiska umieść w konfiguracji, a w kodzie aplikacji wstrzyknij wartość lub użyj config().

php
<?php

declare(strict_types=1);

namespace App\Notifications;

final readonly class SenderAddress
{
    public function __construct(
        public string $address,
    ) {
    }

    public static function fromConfiguration(): self
    {
        return new self(
            address: (string) config('mail.from.address'),
        );
    }
}
bash
php artisan optimize
php artisan config:clear
php artisan route:list

optimize jest wygodą wdrożeniową dla wspieranych cache'y, takich jak config, trasy, zdarzenia i skompilowane widoki. Nie jest ogólnym przyciskiem wydajności, a cache tras jest najbezpieczniejszy z trasami kontrolerów: trasy closure są serializowane z dodatkowymi ograniczeniami. Jeśli wdrożenie zmienia wartość środowiskową, zbuduj cache konfiguracji w środowisku, które go uruchomi, i wyczyść/zbuduj go w ramach tego wdrożenia — nie przez edycję .env, gdy workery nadal działają ze starą konfiguracją w pamięci.

Octane pokazuje decyzje o czasie życia

Octane utrzymuje workera przy życiu przez wiele requestów. Providery bootują raz na workera, a singleton pozostaje w nim do jego recyklingu. Singleton przechwytujący mutowalny stan requestu może więc przekazać następnemu klientowi identyfikator tenanta poprzedniego klienta.

To jest niebezpieczne:

php
<?php

declare(strict_types=1);

namespace App\Tenancy;

use Illuminate\Http\Request;

final readonly class CurrentTenant
{
    public function __construct(
        public string $tenantId,
    ) {
    }

    public static function fromRequest(Request $request): self
    {
        return new self((string) $request->header('X-Tenant-Id'));
    }
}

// Nie rób tego w providerze:
// $this->app->singleton(CurrentTenant::class, fn (): CurrentTenant => CurrentTenant::fromRequest(request()));

Zamiast tego zbindowaj kontekst requestu jako scoped i wypełnij go przez middleware. Laravel czyści instancje scoped po requeście albo jobie kolejki, więc kolejne przejście lifecycle dostaje świeży kontekst.

php
<?php

declare(strict_types=1);

namespace App\Providers;

use App\Tenancy\CurrentTenant;
use Illuminate\Support\ServiceProvider;

final class TenancyServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        $this->app->scoped(CurrentTenant::class, function (): CurrentTenant {
            throw new \LogicException('CurrentTenant must be set by tenancy middleware.');
        });
    }
}

Middleware może potem rozwiązać osobny mutowalny kontekst albo przekazać dane tenanta jawnie do akcji. Najlepszy wybór zależy od tego, jak głęboko kontekst tenanta przechodzi przez granice: jawne parametry łatwiej testować, natomiast scoped context może ograniczyć powtarzalny plumbing w ostrożnie zaprojektowanej warstwie tenancy.

Nie używaj Octane::tick() jako naprawy wyciekającego stanu requestu. Służy do świadomej, okresowej konserwacji workera. Właściwe bindingi, jawne czyszczenie stanu zewnętrznych klientów i recykling workerów to podstawowe mechanizmy bezpieczeństwa.

Kiedy nie używać hooków lifecycle

Nie dodawaj globalnego middleware tylko dlatego, że kontroler potrzebuje jednej wartości pochodnej. Przekaż wartość do akcji, użyj form requestu do walidacji wejścia albo policy do autoryzacji. Nie wkładaj transakcyjnej pracy biznesowej do middleware terminowalnego; zakolejkuj ją po commicie. Nie używaj service providera do odpytywania bazy o aktywnego użytkownika, locale albo tenanta. I nie twórz własnego kernela ani nie wywołuj ręcznie kontenera, by „kontrolować” rozwiązywanie, gdy trasa, binding, provider albo middleware już wyraża zamiar.

Alternatywą nie jest unikanie abstrakcji za wszelką cenę. Jest nią najwęższy punkt rozszerzenia Laravel będący właścicielem odpowiedzialności: provider dla konfiguracji aplikacji, middleware dla reguł transportowych całego requestu, form request dla wejścia, policy dla dostępu, akcja dla zachowania use case'u i job dla trwałej pracy asynchronicznej.

Tryby awarii, które sprawdź przed produkcją

Lifecycle tworzy awarie, których test jednostkowy samego kontrolera nie zauważy:

  • Globalne middleware zakłada istnienie parametrów trasy i zawodzi przed routingiem.
  • Route binding zwraca model innego tenanta, a policy nie istnieje albo jest napisana błędnie.
  • Zadanie z terminate() jest traktowane jako niezawodna praca i znika przy restarcie workera.
  • Wdrożenie zmienia .env bez przebudowania cache konfiguracji.
  • Singleton Octane przechowuje stan requestu lub zalogowanego użytkownika i przekazuje go do kolejnego requestu.

Napisz testy feature, które prowadzą trasę przez jej middleware i policy, a potem uruchom realistyczne wdrożenie z aktywnym cache. Dla Octane dodaj test lub kontrolę operacyjną wysyłającą dwa requesty z różnymi tożsamościami tenantów do tego samego workera. Kontroler jest tylko jedną stacją na trasie od socketu do response; poprawność produkcyjna zależy od całej drogi.

Powiązane artykuły

Wsparcie istniejącego systemu

Potrzebujesz pomocy z działającą aplikacją?

Pomagam firmom rozwijać działające systemy, porządkować wdrożenia i dodawać nowe funkcje bez dokładania chaosu do projektu.

Komentarze (0)
Zaloguj się, aby dodać komentarz

Musisz być zalogowany, aby dodać komentarz.

Zaloguj się

Potrzebujesz kogoś, kto weźmie odpowiedzialność za kolejny krok?

Porozmawiajmy o Twoim projekcie i określmy zakres, który ma sens dla Twoich celów.