Service Classes, Payloads, and Responders

Revath Kumar has a good blog post up about extracting domain logic from controllers and putting that logic in a service class. After reading it, I commented that with a little extra work, it would be easy to modify the example to something closer to the Action-Domain-Responder pattern. In doing so, we would get a better separation of concerns (especially in presentation).

Using the code that Revath gives in his blog post as a basis, we can do the following:

  1. In the service class, instead of sometimes throwing exceptions and sometimes returning arrays, we always return Payload instances. These explicitly state the result of the domain activity (“input not valid”, “order created”, “order not created”, “error”). Making the status information explicit in the Payload means that we don’t need to catch exceptions in the controller action, and that we don’t need to examine the domain objects themselves to interpret what occurred in the domain. The service class can now say explicitly what occurred in a standardized way.

  2. In the controller action, now that we don’t need to catch exceptions, we can concentrate on a much smaller set of logic: get the user input, pass it to the domain, get back the domain payload, and pass the payload to a responder.

  3. Finally, we introduce a Responder, whose job is to build (and in this case send) the response. The responder logic ends up being simplified as well.

The modified code looks like this:

use Aura\Payload\Payload;

class OrdersController extends Controller {
  public function actionCreate() {
    $orderData = Yii::app()->request->getParam('order');
    $order = new OrdersService();
    $payload = $order->create($orderData);
    $responder = new OrdersResponder();

class OrdersResponder extends Responder {
  public function sendCreateResponse($payload) {
    $result = array('messages' => $payload->getMessages());
    if ($payload->getStatus() === Payload::CREATED) {
      $this->_sendResponse(200, $result);
    } else {
      $result['status'] = 'error';
      $this->_sendResponse(403, $result);

class OrdersService {

  protected function newPayload($status) {
    return new Payload($status);

  public function create($orderData) {
    if(empty($orderData['items'])) {
      return $this->newPayload(Payload::NOT_VALID)
          "Order items can't be empty."
    $items = $orderData['items'];
    try {
      $order = new Orders;
      $orderTransaction = $order->dbConnection->beginTransaction();

      $address = Addresses::createIfDidntExist($orderData);
      $orderData['address_id'] = $address->id;
      $amount = 0;
      foreach ($items as $key => $item) {
        $amount += $item['total'];
      $amount += $orderData['extra_charge'];
      $orderData['amount'] = $amount;
      $order->attributes = $orderData;
      if($order->save()) {
        if(OrderItems::batchSave($items, $order->id)) {
          return $this->newPayload(Payload::CREATED)
              "Order placed successfully."
        return $this->newPayload(Payload::NOT_CREATED)
            "Failed to save the items."
      else {
        // handle validation errors
        return $this->newPayload(Payload::ERROR)
    catch(Exception $e) {
      return $this->newPayload(Payload::ERROR)
          "Something wrong happened"

Now, there are still obvious candidates for improvement here. For example, we could begin separating the controller action methods into their own individual action classes. But baby steps are the right way to go when refactoring.

This small set of changes gives us a better separation of concerns, especially in terms of presentation. Remember, the “presentation” in a request/response environment is the entire HTTP response, not just the response body. The above changes make it so that HTTP headers and status code presentation work are no longer mixed in with the controller; they are now handled by a separate Responder object.

Are you stuck with a legacy PHP application? You should buy my book because it gives you a step-by-step guide to improving your codebase, all while keeping it running the whole time.

9 thoughts on “Service Classes, Payloads, and Responders

  1. What the code from Revath’s blog post shows is that somehow, people often find ‘HTML’ vs ‘JSON/XML/…’ responses different.
    If a controller is to return HTML, nobody would even think of generating that HTML inside their controller. Doing so would make no sense and everybody would agree that it is ugly.
    Yet when a controller needs to return some JSON or AJAX or whatever else computer readable format, often we see exactly that: Out of the blue the controller is now directly generating the response body, setting HTTP headers, etc.

    Having something that is called a ‘responder’ instead of something called a ‘view’ makes it more explicit that its job is to “handle the response” instead of “handle what the user is going to see”.

    Something I’d really like would be if the responser where to check what “type of request” was made. In the context of a web shop, adding a product to your cart could be an AJAX call, where the response is some JSON indicating if everything is OK or that there where errors. However, it could also be a form post, in which case you’d probably want to redirect the user to the cart on success, or back to the product in case of an error. (Though with controllers / actions this small, having different controllers / actions for both these “things” using different responders / views wouldn’t be much of an issue.)
    I’m not sure how that would work though; perhaps parsing the accept header of the request could work but I’m not sure that would be bullet proof.

  2. I think putting many service method return in a payload object limits the reusability, and Service Layer API explicitness.
    What do you think of building payload object in the controller and then pass it to the Responser object?

Leave a Reply

Your email address will not be published. Required fields are marked *