Controllers and Domain Exceptions
A few months ago I had a great email conversation with a correspondent about how to handle business logic exceptions in his controller code. His message follows, lightly edited for brevity and clarity:
I think controller has single responsibility - to mediate communication between caller's context and actual business logic services. (I believe business logic services should be unaware of caller's context, be it HTTP request or CLI.)
Given that services should be unaware of who called them, they should not throw HTTP-specific exceptions. So instead of throwing a Symfony HttpNotFound Exception, the service would throw ObjectNotFound (which is HTTP agnostic) in cases where DB record could not be found.
Yet at the same time the logic that converts exceptions to HTTP responses expects HTTP-specific Symfony exceptions. This means that the exception thrown by service needs to be transformed into Symfony exception.
One of solutions I see to this is that the controller could take that responsibility. It would catch domain exceptions thrown by service and wrap them into appropriate HTTP exceptions.
class FooController
{
public function fooAction()
{
try {
$this->service->doSomething('foo');
} catch (ObjectNotFound $e) {
throw new NotFoundHttpException('Not Found', $e);
} catch (InvalidDataException $e) {
throw new BadRequestHttpException('Invalid value', $e);
} // ...
}
}The downside I see with this approach is that if I have many controllers I will have code duplication. This also could lead to big amount of catch blocks, because of many possible exceptions that could be thrown.
Another approach would be to not have try/catch blocks in controller and let the exceptions thrown by service bubble up the stack, leaving the exception handling to exception handler. This approach would solve the code duplication issue and many try/catch block issue. However, because the response builder only accepts Symfony exceptions, they would need to be mapped somewhere.
It also feels to me that this way the controller is made cleaner, but part of controllers responsibility is delegated to something else, thus breaking encapsulation. I feel like it's controllers job to decide what status code should be retuned in each case, yet at the same time, cases usually are the same.
I truly hope you will be able to share your thoughts on this and the ways you would tackle this.
If you find yourself in this situation, the first question to ask yourself is, “Why am I handling domain exceptions in my user interface code?” (Remember: Model-View-Controller and Action-Domain-Responder are user interface patterns; in this case, the user interface is composed of an HTTP request and response.) Domain exceptions should be handled by the domain logic in a domain-appropriate fashion.
My correspondent’s first intuition (using domain-level exceptions, not HTTP-specific ones) has the right spirit. However, instead of having the domain service throw exceptions for the user interface controller to catch and handle, I suggest that the service return a Domain Payload with domain-specific status reporting. Then the user interface can inspect the Domain Payload to determine how to respond. I expand on that approach in this post.
By way of example, instead of this in your controller …
class FooController
{
public function fooAction()
{
try {
$this->service->doSomething('foo');
} catch (ObjectNotFound $e) {
throw new NotFoundHttpException('Not Found', $e);
} catch (InvalidDataException $e) {
throw new BadRequestHttpException('Invalid value', $e);
} // ...
}
}
… try something more like this:
class FooController
{
public function fooAction()
{
$payload = $this->service->doSomething('foo');
switch ($payload->getStatus()) {
case $payload::OBJECT_NOT_FOUND:
throw new NotFoundHttpException($payload->getMessage());
case $payload::INVALID_DATA:
throw new BadRequestHttpException($payload->getMessage());
// ...
}
}
}
(I am not a fan of using exceptions to manage flow control; I’d rather return a new Response object. However, I am trying to stick as closely to the original example as possible so that the differences are more easily examined.)
The idea here is to keep domain logic in the domain layer (in this case, a service). The service should validate the input, and if it fails, return a “not-valid” payload. The service should catch all exceptions, and return a payload that describes the kind of error that occurred. You can then refine your controller to examine the Domain Payload and handle it however you want.
Using a Domain Payload in this way is not a huge leap. Essentially you move from a try/catch block and exception classes, to a switch/case block and status constants. What’s important is that you are now handling domain-level exceptions in the domain and not in the user interface layer. You are also encapsulating the status information reported by the domain, so that you can pass the Domain Payload object around for something other than the controller to inspect and handle.
Encapsulation via Domain Payload opens the path to a more significant refactoring that will help reduce repetition of response-building logic across many controller actions. That next refactoring is to separate out the response-building work to a Responder, and use the Responder in the controller action to return a response. You can then pass the Domain Payload to the Responder for it to handle.
class FooController
{
public function fooAction()
{
$payload = $this->service->doSomething('foo');
return $this->responder->respond($payload);
}
}
class FooResponder
{
public function respond($payload)
{
switch ($payload->getStatus()) {
case $payload::OBJECT_NOT_FOUND:
throw new NotFoundHttpException('Not Found', $e);
case $payload::INVALID_DATA:
throw new BadRequestHttpException('Invalid value', $e);
// ...
}
}
}
Once you do that, you’ll realize the majority of your response-building logic can go into a common or base Responder. Custom cases can then be be handled by controller- or format-specific Responders.
And then you’ll realize all your Action logic is all pretty much the same: collect input from the Request, pass that input to a Domain-layer service to get back a Domain Payload result, and pass that result to a Responder to get back a Response. At that point you’ll be able to get rid of controllers entirely, in favor of a single standardized action handler.
Read the Reddit discussion about this post here.