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:
-
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.
-
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.
-
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();
$responder->sendCreateResponse($payload);
}
}
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)
->setMessages([
"Order items can't be empty."
]);
}
$items = $orderData['items'];
unset($orderData['items']);
try {
$order = new Orders;
$orderTransaction = $order->dbConnection->beginTransaction();
$address = Addresses::createIfDidntExist($orderData);
unset($orderData['address']);
$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)) {
$orderTransaction->commit();
$this->sendMail($order->id);
return $this->newPayload(Payload::CREATED)
->setMessages([
"Order placed successfully."
]);
}
$orderTransaction->rollback();
return $this->newPayload(Payload::NOT_CREATED)
->setMessages([
"Failed to save the items."
]);
}
else {
// handle validation errors
$orderTransaction->rollback();
return $this->newPayload(Payload::ERROR)
->setMessages($order->getErrors());
}
}
catch(Exception $e) {
$orderTransaction->rollback();
return $this->newPayload(Payload::ERROR)
->setMessages([
"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.
Read the Reddit discussion about this post here.
