Skip to content

Lesson 3 of 15 · Architectural Styles

The Request Lifecycle Through the Layers

Advanced•
lesson•
November 16, 2026•
~12 min read

One request, one method

A guest fills out the booking form on the hotel's site: a room, a date range, how many adults and children. They click Reserve. That's a POST /reservations.

In the codebase this lesson assumes you're working in today, that request lands in one controller method. The controller pulls the room, checks it isn't already booked for those dates, prices the stay, builds an Eloquent model, saves it, and returns a response. Every one of those steps lives in the same method, in a class that also knows about HTTP. If the hotel later wants staff to request a walk-in reservation from a terminal, or wants to replay a batch of reservations from an import file, the only option is copying the method and adapting the parts that talk to HTTP, because none of the parts that don't were ever separated out.

The previous lesson made the case for splitting that method into layers with a narrow surface between them. It didn't show what happens to a single request once the split exists: which file it touches first, what that file is allowed to know, and what it hands to the next one.

Walking the request down

Nine files shown here carry this request from the wire to the database and back. Each one is named before its code, and each import matters as much as the logic. The Http/ folders here illustrate the layered style from the previous lesson; the lessons after this one move to slices. The route file aside, the other eight sit in the Booking module like this:

TEXT
Hearth/Booking/ ├── Http/ # presentation │ ├── Requests/ │ │ └── RequestReservationRequest.php │ └── Controllers/ │ └── RequestReservationController.php ├── RequestReservationCommand.php # application: input ├── RequestReservation.php # application service ├── Reservation/ # domain │ ├── Reservation.php │ └── Reservations.php # repository interface ├── RequestReservation/ │ └── ReservationRequested.php # event └── Infrastructure/ # infrastructure └── EloquentReservations.php

The route names the entry point and nothing else.

PHP
<?php declare(strict_types=1); use Hearth\Booking\Http\Controllers\RequestReservationController; use Illuminate\Support\Facades\Route; Route::post('/reservations', RequestReservationController::class);

Before the controller sees anything, Hearth/Booking/Http/Requests/RequestReservationRequest.php checks the request is shaped correctly. It does not check whether the room is available or what the stay costs, only whether the input has the right shape to be worth passing further in.

PHP
<?php declare(strict_types=1); namespace Hearth\Booking\Http\Requests; use Illuminate\Foundation\Http\FormRequest; final class RequestReservationRequest extends FormRequest { public function authorize(): bool { return true; } /** * @return array<string, array<int, string>> */ public function rules(): array { return [ 'guest_id' => ['required', 'uuid'], 'room_id' => ['required', 'uuid'], 'check_in' => ['required', 'date'], 'check_out' => ['required', 'date', 'after:check_in'], 'adults' => ['required', 'integer', 'min:1'], 'children' => ['required', 'integer', 'min:0'], ]; } }

The controller in Hearth/Booking/Http/Controllers/RequestReservationController.php does one job: turn a validated HTTP request into a command the application layer understands, and turn the result back into a response.

PHP
<?php declare(strict_types=1); namespace Hearth\Booking\Http\Controllers; use Carbon\CarbonImmutable; use Hearth\Booking\DateRange; use Hearth\Booking\GuestCount; use Hearth\Booking\GuestId; use Hearth\Booking\Http\Requests\RequestReservationRequest; use Hearth\Booking\RequestReservation; use Hearth\Booking\RequestReservationCommand; use Hearth\Booking\RoomId; use Illuminate\Http\JsonResponse; final readonly class RequestReservationController { public function __construct( private RequestReservation $requestReservation, ) { } public function __invoke(RequestReservationRequest $request): JsonResponse { $id = $this->requestReservation->handle(new RequestReservationCommand( guestId: new GuestId($request->string('guest_id')->toString()), roomId: new RoomId($request->string('room_id')->toString()), stayDates: new DateRange( checkIn: CarbonImmutable::parse($request->string('check_in')->toString()), checkOut: CarbonImmutable::parse($request->string('check_out')->toString()), ), guestCount: new GuestCount( adults: $request->integer('adults'), children: $request->integer('children'), ), )); return new JsonResponse(['id' => $id->toString()], 201); } }

GuestId, RoomId and ReservationId are UUID wrappers with toString(), next() and equals(). The command the controller builds is a plain, inert value. It carries data across the boundary and decides nothing.

PHP
<?php declare(strict_types=1); namespace Hearth\Booking; use Hearth\Booking\DateRange; use Hearth\Booking\GuestCount; use Hearth\Booking\GuestId; use Hearth\Booking\RoomId; final readonly class RequestReservationCommand { public function __construct( public GuestId $guestId, public RoomId $roomId, public DateRange $stayDates, public GuestCount $guestCount, ) { } }

Hearth/Booking/RequestReservation.php is where the orchestration happens: check whether the room is free, get a price, ask the domain to decide whether a reservation can exist, then persist it.

PHP
<?php declare(strict_types=1); namespace Hearth\Booking; use Carbon\CarbonImmutable; use Hearth\Booking\Reservation\CancellationPolicy; use Hearth\Booking\Reservation\Reservation; use Hearth\Booking\Reservation\ReservationId; use Hearth\Booking\Reservation\Reservations; use Hearth\Booking\Reservation\RoomNotAvailable; final readonly class RequestReservation { public function __construct( private Reservations $reservations, private Rooms $rooms, private ReservationPriceFactory $priceFactory, private CancellationPolicy $cancellationPolicy, ) { } public function handle(RequestReservationCommand $command): ReservationId { $overlapping = $this->reservations->overlapping($command->roomId, $command->stayDates); if ($overlapping !== []) { throw new RoomNotAvailable($command->roomId, $command->stayDates); } $room = $this->rooms->withId($command->roomId); $totalPrice = $this->priceFactory->build($room, $command->stayDates, $command->guestCount); $reservation = Reservation::request( $command->guestId, $command->roomId, $command->stayDates, $command->guestCount, $totalPrice, $this->cancellationPolicy, CarbonImmutable::now(), ); $this->reservations->save($reservation); return $reservation->id; } }

ReservationPriceFactory::build() takes a room, the dates and the guest count here. Notice what the application service does and doesn't decide. It decides the order of operations: check availability, price the stay, hand both plus the timestamp and the policy to the domain. It does not decide what makes a valid reservation, or reach into Reservation's internals to set one up by hand. That decision belongs to Hearth/Booking/Reservation/Reservation.php, the one file in this chain that gets a say in whether the operation is allowed to happen at all.

Reservation is an aggregate, the one class that owns a reservation's rules and everything inside it.

PHP
<?php declare(strict_types=1); namespace Hearth\Booking\Reservation; use Carbon\CarbonImmutable; use Hearth\Booking\DateRange; use Hearth\Booking\GuestCount; use Hearth\Booking\GuestId; use Hearth\Booking\Money; use Hearth\Booking\RequestReservation\ReservationRequested; use Hearth\Booking\RoomId; final class Reservation { /** @var list<object> */ private array $events = []; public function __construct( public readonly ReservationId $id, public readonly GuestId $guestId, public readonly RoomId $roomId, public readonly DateRange $stayDates, public readonly GuestCount $guestCount, public readonly Money $totalPrice, public readonly CancellationPolicy $cancellationPolicy, public ReservationStatus $status, ) { } public static function request( GuestId $guestId, RoomId $roomId, DateRange $stayDates, GuestCount $guestCount, Money $totalPrice, CancellationPolicy $cancellationPolicy, CarbonImmutable $requestedAt, ): self { $reservation = new self( ReservationId::next(), $guestId, $roomId, $stayDates, $guestCount, $totalPrice, $cancellationPolicy, ReservationStatus::REQUESTED, ); $reservation->events[] = new ReservationRequested( $reservation->id->toString(), $guestId->toString(), $roomId->toString(), $requestedAt, ); return $reservation; } }

The event it records is a plain value, Hearth/Booking/RequestReservation/ReservationRequested.php. It carries ids as strings so a listener in another module can read it without importing Booking's value objects:

PHP
<?php declare(strict_types=1); namespace Hearth\Booking\RequestReservation; use Carbon\CarbonImmutable; final readonly class ReservationRequested { public function __construct( public string $reservationId, public string $guestId, public string $roomId, public CarbonImmutable $requestedAt, ) { } }

This trimmed class leaves out the status-changing methods and releaseEvents(). The public constructor is what ReservationRecord::toDomain() uses to rebuild a stored reservation.

Reservation::request() doesn't know it was reached from a form. It takes a guest, a room, a date range, a guest count, a price, a cancellation policy, and a timestamp, and it's the only place that turns those seven values into a requested reservation and records ReservationRequested while doing it. Recording the event on the object beats dispatching it inline from the handler; RequestReservation::handle() would release and dispatch what Reservation recorded, and that call is left out above to keep this walk on the layers rather than the event mechanics.

Persistence is two files: the Reservations interface in Hearth/Booking/Reservation/Reservations.php, which the application service depends on, and the class that implements it. ReservationRecord is the Eloquent model for the reservations table, and fromDomain() and toDomain() are its mapping methods, not shown here.

PHP
<?php declare(strict_types=1); namespace Hearth\Booking\Reservation; use Hearth\Booking\DateRange; use Hearth\Booking\RoomId; interface Reservations { public function withId(ReservationId $id): Reservation; public function save(Reservation $reservation): void; /** * @return list<Reservation> */ public function overlapping(RoomId $roomId, DateRange $stayDates): array; }
PHP
<?php declare(strict_types=1); namespace Hearth\Booking\Infrastructure; use Hearth\Booking\DateRange; use Hearth\Booking\Reservation\Reservation; use Hearth\Booking\Reservation\ReservationId; use Hearth\Booking\Reservation\Reservations; use Hearth\Booking\Reservation\ReservationStatus; use Hearth\Booking\RoomId; final readonly class EloquentReservations implements Reservations { public function withId(ReservationId $id): Reservation { $model = ReservationRecord::query()->findOrFail($id->toString()); return $model->toDomain(); } public function save(Reservation $reservation): void { ReservationRecord::query()->updateOrCreate( ['id' => $reservation->id->toString()], ReservationRecord::fromDomain($reservation), ); } /** * @return list<Reservation> */ public function overlapping(RoomId $roomId, DateRange $stayDates): array { return ReservationRecord::query() ->where('room_id', $roomId->toString()) ->where('status', '!=', ReservationStatus::CANCELLED->value) ->where('check_in', '<', $stayDates->checkOut) ->where('check_out', '>', $stayDates->checkIn) ->get() ->map(static fn (ReservationRecord $model): Reservation => $model->toDomain()) ->all(); } }

Of the nine files shown, only three know HTTP exists: the route, the Form Request, and the controller.

What each layer is allowed to know

Presentation knows HTTP, or whatever transport it's translating for, and the application service it calls. It does not know what a valid reservation looks like. The import that would break this: a controller with use Hearth\Booking\Reservation\Reservation;, constructing a reservation by hand instead of building a command and calling the application service.

Application knows the domain: Reservation, the value objects, the repository interface and the price factory it depends on. It does not know where the command came from. The import that would break this: an application service with use Illuminate\Http\Request;, reaching into the raw request instead of trusting the command it was handed.

Domain knows itself and the shared value objects everything else also uses. It does not know Eloquent, the queue, or the framework at all. The import that would break this: use Hearth\Booking\Infrastructure\ReservationRecord; inside Reservation, making the class that's supposed to decide whether a reservation is valid depend on the shape of a database table.

Infrastructure knows the domain, because it has to translate to and from it, and it knows whatever vendor or framework code it's wrapping. It does not call back into the application layer. The import that would break this: use Hearth\Booking\RequestReservation; inside an Eloquent model observer, letting a database event trigger orchestration that belongs in the application service.

Running the same use case from somewhere else

The hotel also lets staff request a walk-in reservation from a terminal, and it runs a nightly job that replays a batch of reservations from a CSV an ops person uploaded. Both need the exact rules the booking form enforces: check availability, get a price, let the domain decide.

Hearth/Booking/Console/RequestReservationConsoleCommand.php drives the same application service from the terminal. Laravel 13 can define a command's signature and description with #[Signature] and #[Description] attributes, and this one does.

PHP
<?php declare(strict_types=1); namespace Hearth\Booking\Console; use Carbon\CarbonImmutable; use Hearth\Booking\DateRange; use Hearth\Booking\GuestCount; use Hearth\Booking\GuestId; use Hearth\Booking\RequestReservation; use Hearth\Booking\RequestReservationCommand; use Hearth\Booking\RoomId; use Illuminate\Console\Attributes\Description; use Illuminate\Console\Attributes\Signature; use Illuminate\Console\Command; #[Signature('reservations:request {guest} {room} {check-in} {check-out} {adults=1} {children=0}')] #[Description('Request a reservation the same way the booking form does')] final class RequestReservationConsoleCommand extends Command { public function handle(RequestReservation $requestReservation): int { $id = $requestReservation->handle(new RequestReservationCommand( guestId: new GuestId($this->argument('guest')), roomId: new RoomId($this->argument('room')), stayDates: new DateRange( checkIn: CarbonImmutable::parse($this->argument('check-in')), checkOut: CarbonImmutable::parse($this->argument('check-out')), ), guestCount: new GuestCount( adults: (int) $this->argument('adults'), children: (int) $this->argument('children'), ), )); $this->info("Reservation {$id->toString()} requested."); return Command::SUCCESS; } }

Hearth/Booking/Jobs/RequestReservationFromBulkImport.php drives it from the queue, one job per row of the import. Laravel 13's job class implements ShouldQueue and uses the Queueable trait from Illuminate\Foundation\Queue\Queueable. Its constructor takes plain strings and integers rather than value objects, because job payloads get serialized onto the queue, and value objects are rebuilt inside handle(), where the container can inject the application service fresh.

PHP
<?php declare(strict_types=1); namespace Hearth\Booking\Jobs; use Carbon\CarbonImmutable; use Hearth\Booking\DateRange; use Hearth\Booking\GuestCount; use Hearth\Booking\GuestId; use Hearth\Booking\RequestReservation; use Hearth\Booking\RequestReservationCommand; use Hearth\Booking\RoomId; use Illuminate\Contracts\Queue\ShouldQueue; use Illuminate\Foundation\Queue\Queueable; final class RequestReservationFromBulkImport implements ShouldQueue { use Queueable; public function __construct( private readonly string $guestId, private readonly string $roomId, private readonly string $checkIn, private readonly string $checkOut, private readonly int $adults, private readonly int $children, ) { } public function handle(RequestReservation $requestReservation): void { $requestReservation->handle(new RequestReservationCommand( guestId: new GuestId($this->guestId), roomId: new RoomId($this->roomId), stayDates: new DateRange( checkIn: CarbonImmutable::parse($this->checkIn), checkOut: CarbonImmutable::parse($this->checkOut), ), guestCount: new GuestCount($this->adults, $this->children), )); } }

Compare the three entry points. The console command parses CLI arguments instead of an HTTP request and prints a line instead of returning JSON. The job reads constructor properties instead of a request and returns nothing instead of a response. Everything from RequestReservationCommand inward, the application service, the price factory, Reservation, the repository, is the same object graph, called the same way, deciding the same thing.

Where the layers leak in real code

The application service returns an Eloquent model. RequestReservation::handle() returns a ReservationRecord instead of a ReservationId, so the controller reads $model->status and serializes Eloquent attributes straight into the response. It starts to hurt once the console command or the bulk-import job needs the same result shaped differently, because now two callers are reading column names instead of a domain type, and a migration that renames a column breaks both of them.

The domain object calls auth()->user(). Something inside Reservation or a policy it uses reaches for the currently authenticated user to decide a rule, because that's the fastest way to get an identity in a controller-first codebase. It works until the exact use case this lesson just ran from the console and the queue needs the same rule, and there's no authenticated request in either of those contexts. The domain object either throws or silently gets null.

The Form Request contains a business rule. A withValidator closure in RequestReservationRequest queries the Reservations repository itself to check the room is free, so the check never makes it into RequestReservation::handle(). It works while the HTTP form is the only entry point, and becomes a real bug once the console command and the bulk-import job, which never touch the Form Request, can create an overlapping reservation.

The controller opens a transaction. __invoke() wraps the call to RequestReservation::handle() in DB::transaction(), because someone once had a partial write and reached for the nearest fix. It costs nothing while HTTP is the only caller, and becomes a liability once the console command and the job both need the same guarantee and have to remember to wrap their own call the same way, and the day one of them forgets is the day a failure between two writes is not rolled back.

Pitfalls

Skipping the Form Request's shape checks because the domain will catch it. The domain's value objects can refuse bad input, but a malformed UUID or a missing field is cheaper to reject as a 422 at the edge than as an exception thrown from a value object constructor three layers in.

Tracing every request by hand on a codebase where a second entry point will never exist. The walk in this lesson earns its keep once a real second caller shows up, or is clearly coming. A contact form with one HTTP entry point and no plans for a CLI or a queue doesn't need this shape.

The one thing to remember

A layered design proves itself the moment you can point the same application service at a second real caller and watch nothing in the middle change. Walk one request all the way down and back up before you trust your layers.

Course Content