Skip to content

Lesson 8 of 15 · Architectural Styles

Action-Domain-Responder (ADR)

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

The controller that learned HTTP

The Hexagonal Architecture lesson left RequestReservationController with one job: turn the request into a RequestReservationCommand, dispatch it, and return the new id as JSON with a 201. Then the booking form on Hearth's website started posting to the same route. A browser does not want JSON back. It wants a redirect to the reservation page and a message to show when it gets there.

The controller grew to handle both, in Hearth/Booking/RequestReservation/RequestReservationController.php:

PHP
<?php declare(strict_types=1); namespace Hearth\Booking\RequestReservation; use Carbon\CarbonImmutable; use Hearth\Booking\DateRange; use Hearth\Booking\GuestCount; use Hearth\Booking\GuestId; use Hearth\Booking\RoomId; use Illuminate\Contracts\Bus\Dispatcher; use Illuminate\Http\JsonResponse; use Illuminate\Routing\Redirector; use Symfony\Component\HttpFoundation\Response; final readonly class RequestReservationController { public function __construct( private Dispatcher $bus, private Redirector $redirector, ) { } public function __invoke(RequestReservationRequest $request): Response { $id = $this->bus->dispatchSync(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'), ), )); $location = '/reservations/'.$id->toString(); if ($request->expectsJson()) { return new JsonResponse(['id' => $id->toString()], Response::HTTP_CREATED, ['Location' => $location]); } return $this->redirector ->to($location, Response::HTTP_SEE_OTHER) ->with('status', 'Your reservation request is in. We will email you once it is confirmed.'); } }

The domain call has not changed. Everything after it is HTTP: which kind of client sent the request, which status code fits, which header carries the new URL, and what goes into the session. Those are four decisions about the response, sitting in the method that holds the one decision the business cares about. The next change to the response, a caching header for the mobile app or a different page for group bookings, lands there too, between the command and the return.

Where ADR comes from

Paul M. Jones ran into the same problem in March 2014, while writing Chapter 10 of Modernizing Legacy Applications in PHP, the chapter on extracting presentation logic into view files. In his words, "there was no logical place to put the refactored HTTP response header work. HTTP headers and status are not business logic, but at the same time, no template system had any support for them."

His answer was a pattern he drafted in May 2014 as Action Domain Response, then renamed Action Domain Responder "to make it clear the component is not itself the HTTP response, but instead something which builds the HTTP response." He describes it as an alternative to "Model 2" MVC, the name Sun Microsystems gave to its server-side adaptation of MVC, which server-side developers now call MVC.

This ADR is unrelated to the Architecture Decision Records, which share the acronym.

Three roles, one direction

ADR splits one HTTP interaction into three roles. Jones's README defines them:

  • Action "is the logic to connect the Domain and Responder. It invokes the Domain with inputs collected from the HTTP Request, then invokes the Responder with the data needed to build an HTTP Response."

  • Domain "is an entry point to the domain logic forming the core of the application. It may be a Transaction Script, Service Layer, Application Service, or something similar."

  • Responder "is the presentation logic to build an HTTP Response using data it receives from the Action. It deals with status codes, headers and cookies, content, formatting and transformation, templates and views, and so on."

The calls run one way. The Action calls the Domain, then hands the result to the Responder. The Responder never calls back: it "does not itself request new information from the Domain or send information back to the Domain." Everything it needs arrives as arguments.

Hearth already has two of the three roles. The controller from the Hexagonal Architecture lesson is an invokable class with a single method, which matches what Jones calls "a canonical Action ... implemented as an individual class with only one main method." The command handler behind the bus is the Domain entry point. The Responder is the missing piece.

ADR in Hearth

The Responder lives in the slice, next to the controller, and its test goes in the module's Tests/ folder:

TEXT
Hearth/Booking/ ├── RequestReservation/ │ ├── RequestReservationController.php # Action │ ├── RequestReservationRequest.php │ ├── RequestReservationCommand.php │ ├── RequestReservationCommandHandler.php # Domain │ └── RequestReservationResponder.php # Responder (new) └── Tests/ └── RequestReservationResponderTest.php

The Responder, in Hearth/Booking/RequestReservation/RequestReservationResponder.php:

PHP
<?php declare(strict_types=1); namespace Hearth\Booking\RequestReservation; use Hearth\Booking\Reservation\ReservationId; use Illuminate\Http\JsonResponse; use Illuminate\Http\Request; use Illuminate\Routing\Redirector; use Symfony\Component\HttpFoundation\Response; final readonly class RequestReservationResponder { public function __construct(private Redirector $redirector) { } public function respond(Request $request, ReservationId $id): Response { $location = '/reservations/'.$id->toString(); if ($request->expectsJson()) { return new JsonResponse(['id' => $id->toString()], Response::HTTP_CREATED, ['Location' => $location]); } return $this->redirector ->to($location, Response::HTTP_SEE_OTHER) ->with('status', 'Your reservation request is in. We will email you once it is confirmed.'); } }

It takes the request and the domain result and returns a Symfony Response, the parent class of both JsonResponse and RedirectResponse. expectsJson() is true when the Accept header asks for JSON, or when an AJAX call accepts any type. The mobile app sends Accept: application/json and gets the 201 with a Location header. A browser posting the form gets a 303, which tells it to load the reservation page with a GET. The Redirector comes in through the constructor because the container's shared instance is given the session store when it is created, and ->with() needs that store to flash the message.

The controller goes back to one job:

PHP
<?php declare(strict_types=1); namespace Hearth\Booking\RequestReservation; use Carbon\CarbonImmutable; use Hearth\Booking\DateRange; use Hearth\Booking\GuestCount; use Hearth\Booking\GuestId; use Hearth\Booking\RoomId; use Illuminate\Contracts\Bus\Dispatcher; use Symfony\Component\HttpFoundation\Response; final readonly class RequestReservationController { public function __construct( private Dispatcher $bus, private RequestReservationResponder $responder, ) { } public function __invoke(RequestReservationRequest $request): Response { $id = $this->bus->dispatchSync(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 $this->responder->respond($request, $id); } }

The class keeps the name RequestReservationController. A Laravel developer expects the class a route points at to be called a controller, and in ADR terms it plays the Action. The next lesson writes the architecture rules that keep framework code at the edges, and they count both Controller and Responder classes as edge code.

Testing the Responder

The Responder has a small contract: given this request and this result, return this response. You can test that contract without sending a request through the router and the middleware. The test still extends Laravel's TestCase, because the Redirector comes from the container. It lives in Hearth/Booking/Tests/RequestReservationResponderTest.php:

PHP
<?php declare(strict_types=1); namespace Hearth\Booking\Tests; use Hearth\Booking\RequestReservation\RequestReservationResponder; use Hearth\Booking\Reservation\ReservationId; use Illuminate\Http\Request; use PHPUnit\Framework\Attributes\Test; use Tests\TestCase; final class RequestReservationResponderTest extends TestCase { #[Test] public function it_answers_a_json_client_with_201_and_the_new_location(): void { $id = ReservationId::next(); $request = Request::create('/reservations', 'POST', server: ['HTTP_ACCEPT' => 'application/json']); $response = $this->app->make(RequestReservationResponder::class)->respond($request, $id); $this->assertSame(201, $response->getStatusCode()); $this->assertSame('/reservations/'.$id->toString(), $response->headers->get('Location')); $this->assertSame(['id' => $id->toString()], json_decode((string) $response->getContent(), true)); } #[Test] public function it_sends_a_browser_to_the_reservation_page(): void { $id = ReservationId::next(); $request = Request::create('/reservations', 'POST'); $response = $this->app->make(RequestReservationResponder::class)->respond($request, $id); $this->assertSame(303, $response->getStatusCode()); $this->assertStringEndsWith('/reservations/'.$id->toString(), (string) $response->headers->get('Location')); } }

The first test pins the API contract: the status, the Location header and the body. The second pins the browser path. The redirect URL is absolute, because the Redirector prefixes the root URL of the current request, so the test checks how it ends. Neither test touches the database or the command handler. The handler has its own tests, which the Testing Across the Boundary lesson writes against fakes.

ADR next to MVC and Clean's presenter

A Laravel controller usually builds its own response, by returning view(...) or response()->json(...). A resource controller also groups seven actions (index, create, store, show, edit, update, destroy) in one class. ADR moves the response work into its own class and keeps one action per class. One Responder can still serve several Actions: Jones writes that "a particular Responder may be used by more than one Action." If confirming and cancelling a reservation answer in the same shape, one ReservationResponder can build both.

Clean Architecture's presenter, from the Clean Architecture lesson, also builds the output, but it sits somewhere else. In Clean, the interactor returns nothing and pushes its result through an output boundary, which the presenter implements. In ADR, the Domain returns a value and never learns that a Responder exists, because the Action does the hand-off. Hearth's handler returns a ReservationId and did not change in this lesson. That is why ADR fits the command-and-handler shape this course uses, without the interactor ceremony that lesson described.

Laravel ships a hook with a similar job. A controller can return any object that implements Illuminate\Contracts\Support\Responsable, and the router calls its toResponse($request) method to get the real response. A Responsable object built from the domain result is another way to write a Responder. I prefer the injected class above: its dependencies sit in its constructor, and the hand-off is visible in the Action.

When a Responder earns its place

A Responder pays when the response has more than one shape or carries real decisions. Hearth's content negotiation is one case. Others are status codes that depend on the result, headers such as Location or cache rules, and a template plus the data that feeds it. It also pays when several actions share one response format and you want that format defined once.

It does not pay for a controller that ends in return new JsonResponse(['id' => $id->toString()], 201);. That line is already the whole Responder. Wrapping it in a class adds a file and a constructor argument and moves nothing out of the way. The controller from the Hexagonal Architecture lesson was fine as written until the second client arrived.

Pitfalls

A Responder that reads from the database. The page after the redirect needs the reservation's details, so someone injects Reservations into the Responder and loads the reservation there. Now presentation code calls the domain, the one direction ADR rules out. Pass what the response needs from the Action, or let the page that loads with GET fetch its own data.

Business decisions in the Responder. "If the reservation is for a group, promise a call from the front desk" is a rule. It belongs in the domain, which can return the outcome. The Responder formats outcomes and does not decide them.

Domain exceptions mapped in two places. Domain exceptions map to responses in one place, the withExceptions() closure in bootstrap/app.php. Catching them in the Action to hand to the Responder splits that mapping across files. Keep the Responder for the results the Domain returns.

The one thing to remember

When the code that shapes a response grows past a line or two, give it its own class. The Action reads the request and calls the domain, the Responder turns the result into HTTP, and the domain never learns either one exists.

Course Content