tl;dr: Action-Domain-Responder is a natural fit for the HTTP user-interface portions of Clean Architecture (or Hexagonal), especially with Domain Driven Design. Just be sure to remember to separate the HTTP response presentation from the action code.
\nJeroen de Dauw has a fantastic post on Implementing the Clean Architecture in PHP, with Domain Driven Design elements. You should read the whole thing, and examine the implementation codebase, for a number of useful insights. Though I might quibble over some elements of the implementation, I think it is a good offering, and serves as a solid reference point.
\nIn his article, Jeroen notes they are using Silex for their HTTP user-interface system, and describes the logic of each route action:
\n\n\nInside this [Silex action] we construct our framework agnostic request model and invoke the Use case with it. Then we hand over the response model to a presenter to create the appropriate HTML or other such format.
\n
That is a very near paraphrase of Action-Domain-Responder:
\nIn Jeroen\u2019s implementation, each Action is a closure defined in the routes.php file. The Action marshals input from the HTTP request using a \u201crequest model\u201d (an input object tailored to the domain) and passes it to a \u201cuse case.\u201d Each \u201cuse case\u201d is an entry point into the Domain, and returns a \u201cresponse model\u201d (the domain result).
The only place where Jeroen\u2019s implementation deviates from ADR is that the Action code builds the presentation itself, instead of handing off to a Responder. (This may be a result of adhering to the idioms and expectations specific to Silex.)
\nBecause the rest of the implementation is so well done, refactoring to a separated presentation in the form of a Responder is a straightforward exercise. Let\u2019s see what that might look like.
\nFirst, as an example, review the code in the check-iban action. The following reorganization of that action code makes the ADR pattern more obvious:
\n<?php\n$app->get(\n 'check-iban',\n function( Request $request ) use ( $app, $ffFactory ) {\n\n // marshal input\n $input = new Iban( $request->query->get( 'iban', '' ) );\n\n // invoke domain and get back result\n $result = $ffFactory->newCheckIbanUseCase()->checkIban($input);\n\n // presentation\n return $app->json(\n $ffFactory->newIbanPresenter()->present( $result )\n );\n }\n);\n?>\nVery clear and straightforward. However, the presentation work is embedded in the action with the $app->json(...) call. (My guess is that\u2019s probably a result of working with existing Silex idioms.)
Another good example is the list-comments.html action. Reorganizing the logic to make the ADR pattern more obvious gives us the following:
\n<?php\n$app->get(\n 'list-comments.html',\n function( Request $request ) use ( $app, $ffFactory ) {\n\n // marshal input\n $input = new CommentListingRequest(\n 10,\n (int)$request->query->get( 'page', '1' )\n );\n\n // invoke domain and get back result\n $result = $ffFactory\n ->newListCommentsUseCase()\n ->listComments( $input );\n\n // presentation\n return new Response(\n $ffFactory->newCommentListHtmlPresenter()->present(\n $result,\n (int)$request->query->get( 'page', '1' )\n )\n );\n }\n);\n?>\nAgain, the presentation work is embedded in the action code.
\nIn general, it is better to completely separate the presentation work from the action code. Remember that in an HTTP context, the presentation is not just the body of the HTTP response. Instead, the presentation is the entire HTTP response, including headers and status. (For more on this, see The Template Is Not The View.)
\nWith the above examples, because they are already so well structured, it would be easy to extract the presentation to a Responder class. For example, the list-comments action could have the presentation work completely removed like so:
<?php\n// hypothetical class with the extracted logic\nclass ListCommentsHtmlResponder\n{\n public function buildResponse($request, $result, $ffFactory)\n {\n return new Response(\n $ffFactory->newCommentListHtmlPresenter()->present(\n $result,\n (int)$request->query->get( 'page', '1' )\n )\n );\n }\n}\n\n// the refactored action code\n$app->get(\n 'list-comments.html',\n function( Request $request ) use ( $app, $ffFactory ) {\n\n // marshal input\n $input = new CommentListingRequest(\n 10,\n (int)$request->query->get( 'page', '1' )\n );\n\n // invoke domain and get back result\n $result = $ffFactory->newListCommentsUseCase()->listComments($input);\n\n // hand result to responder\n return $ffFactory->newListCommentsHtmlResponder()->buildResponse(\n $request,\n $result,\n $ffFactory\n );\n }\n);\n?>\nNow the presentation work of building an HTTP response is cleanly separated from the rest of the action code.
\nWhen separating concerns along these lines, you begin to see the similarities in the presentation work, and can start to reduce repetition across the codebase. For example, any Action that delivers a JSON response might use the same base JSON Responder.
\nEventually, you may realize that the logic of each action is effectively identical. That is, you always collect input, pass that input through the domain to get back a result, and pass that result to a response builder.
\nWhen that realization occurs, you can build a single action handler that coordinates between injected input marshals, domain entry points, and response builders. That\u2019s exactly what the Arbiter ActionHandler does, and Radar uses that in turn to specify the input + domain + responder callables for each route.
\nAt that point, you are out of the business of writing action methods entirely. Then the user-interface code can focus on marshaling inputs going to the domain, and on presenting the results coming out of the domain \u2013 which is exactly how things should be.
\nJeroen\u2019s writeup also reveals that at least some of the elements in his implementation are returning something like Domain Payload objects. Cf. the ValidationResult class, used in the validate-payment-data action among other places.
\nI\u2019m a big fan of the Domain Payload pattern in ADR, and using a Domain Payload for all returns received by the action code. Doing so simplifies the response-building logic even further; for example, by collecting common \u201csuccess\u201d and \u201cfailure\u201d presentation work across different JSON responders.
\nThen there\u2019s this bit about containers:
\n\n\nWe decided to go with our own top level factory, rather than using the dependency injection mechanism provided by Silex: Pimple. Our factory internally actually uses Pimple, though this is not visible from the outside. With this approach we gain a nicer access to service construction, since we can have a getLogger() method with LoggerInterface return type hint, rather than accessing $app[\u2018logger\u2019] or some such, which forces us to bind to a string and leaves us without type hint.
\n
This resonates with some other ideas I\u2019ve been toying with, namely that the user-interface container might better be separated from the domain container. They can be wired up separately from each other, making it easier to package the Domain portions independently from the user-interface portions, and enforcing a \u201cphysical\u201d boundary between the two.
\nOverall, congratulations to Jeroen on putting together such a good writeup.
\nRead the Reddit discussion about this post here.
\n" }