\n\ntl;dr: Instead of inspecting a Domain result to determine how to present it, consider using a Domain Payload Object to wrap the results of Domain interaction and simulataneously indicate the status of the attempted interaction. The Domain already knows what the results mean; let it provide that information explicitly instead of attempting to re-discover it at presentation time.
\n
In Action-Domain-Responder the Action passes input to the Domain layer, which then returns some data for the Action to pass to the Responder. In simple scenarios, it might be enough for the Responder to inspect the data to determine how it should present that data. In more complex scenarios, though, it would make more sense for the Domain to pass back the data in a way that indicates the status of the data. Instead of the Responder inspecting the Domain results, the Domain should tell us what kind of results they are.
\nFor example, let\u2019s look at an example of some older code to update a Blog post. This is MVC-ish code, not ADR code; we\u2019ll refactor along the way.
\n<?php\nclass BlogController\n{\n // POST /blog/{id}\n public function update($id)\n {\n $blog = $this->model->fetch($id);\n if (! $blog) {\n // 404 Not Found\n // (no blog entry with that ID)\n $this->response->status->set(404);\n $this->view->setData(array('id' => $id));\n $content = $this->view->render('not-found');\n $this->response->body->setContent($content);\n return;\n }\n\n $data = $this->request->post->get('blog');\n if (! $blog->update($data)) {\n // update failure, but why?\n if (! $blog->isValid()) {\n // 422 Unprocessable Entity\n // (not valid)\n $this->response->status->set(422);\n $this->view->setData(array('blog' => $blog));\n $content = $this->view->render('update');\n $this->response->body->setContent($content);\n return;\n } else {\n // 500 Server Error\n // (i.e., valid data, but update failed for some other reason)\n $this->response->status->set(500);\n return;\n }\n }\n\n // 200 OK\n // (i.e., the update worked)\n $this->response->status->set(200);\n $this->view->setData(array('blog' => $blog));\n $content = $this->view->render('update');\n $this->response->body->setContent($content);\n }\n}\n?>\nWe can see that there is some amount of model work going on here (look for a blog post, attempt to update it if it exists, check for error conditions on the update attempt). There is also some amount of presentation work going on; remember, the view is not the template \u2013 the view is the response. So, even though the view templates are separated, the HTTP status codes are also part of the presentation, meaning that there is an insuffcient level of separation of concerns.
\nIn converting this to Action-Domain-Responder, we can pretty easily extract the model work to a Domain, and the presentation work to a Responder, resulting in something like the following. (Note that the Domain layer now adds values to the returned $blog entity to indicate different failure states.)
<?php\nclass BlogUpdateAction\n{\n // POST /blog/{id}\n public function __invoke($id)\n {\n $data = $this->request->post->get('blog');\n $blog = $this->domain->update($id, $data);\n $this->responder->setData('id' => $id, 'blog' => $blog);\n $this->responder->__invoke();\n }\n}\n\nclass BlogUpdateResponder\n{\n public function __invoke()\n {\n if (! $this->data->blog) {\n // 404 Not Found\n // (no blog entry with that ID)\n $this->response->setStatus(404);\n $this->view->setData($this->data);\n $content = $this->view->render('not-found');\n $this->response->body->setContent($content);\n return;\n }\n\n if ($this->data->blog->updateFailed()) {\n // 500 Server Error\n // (i.e., valid data, but update failed for some other reason)\n $this->response->status->set(500);\n return;\n }\n\n if (! $this->data->blog->isValid()) {\n // 422 Unprocessable Entity\n // (invalid data submitted)\n $this->response->setStatus(422);\n $this->view->setData($this->data);\n $content = $this->view->render('update');\n $this->response->body->setContent($content);\n return;\n }\n\n // 200 OK\n // (i.e., the update worked)\n $this->view->setData($this->data);\n $content = $this->view->render('update');\n $this->response->body->setContent($content);\n }\n}\n?>\nBut at this point we\u2019re still inspecting the Domain result to see how we should present it. This strikes me as a lot of work to determine something the Domain already knows.
\nInstead of re-discovering the Domain status in the Responder, we should let the Domain tell us not only the data, but also what to think about that data. The Domain should give us an indication as to what it tried to do, and whether it succeeded or not. Then we can completely skip the inspection of the Domain results and present those results without lots of additional work.
\nThe key to doing this is something called a Domain Payload Object. (Initially I called this a \u201cDomain Result\u201d but my recent reading of Vernon\u2019s Implementing Domain Driven Design revealed the term to me. I love finding the right word for a concept!)
\nWith a Domain Payload, we wrap the Domain results in an object that carries those results for us. We can then extend the semantics of the Domain Payload to tell us what kind of payload it carries. Something as simple as the class name of the Domain Payload can give us that information.
\nIn the ADR example code we will find a series of Domain Payload objects. While these map closely to HTTP response codes for simplicity\u2019s sake, other Domains are very likely to have different kinds of payload statuses. The point is that each Payload object explicitly tells us what the results indicate: entity not found, invalid data in the entity, database error, successful update, and so on.
\nThe BlogUpdateAction remains straightforward. However, the example BlogService\u2018s update() method now does all the update work, and it wraps all returned results in a Domain Payload that indicates the result status.
\nFinally, the BlogUpdateResponder, which itself extends an AbstractResponder, can match a Domain Payload class name to a method that presents the payload results.
\nVoila: no more inspection of the results to figure out presentation. We let the Domain tell us what it tried to do and whether it worked or not (and what the cause of the failure was, if any). At the presentation layer, our Responder can honor (or ignore) that information at its convenience.
\nRead the Reddit discussion about this post here.
\n" }