Practical PHP Patterns: Service Layer

The last domain logic pattern we will treat in this series is the Service Layer one. In its simplest form, a Service Layer is a set of service classes that deal with application logic, and that are characterized from being used from different front-ends.

Source code, at every level of abstraction, is the representation of data entities and their related behavior, particularly in an object-oriented paradigm. There are different types of logic which this behavior can be partitioned into:

• business logic is encapsulated in a Domain Model, and it is specific to the particular domain the application works in. The added value of an enterprise application ensues primarily from its business logic.
• application logic is in the scope of a Service Layer, and it is not strictly domain-specific, although its implementation may be. For example, translating objects into an XML or Json representation is part of application logic, even if it is executed with application-specific classes which depends on an underlying Domain Model. The task of representing data in a particular format is oblivious to the domain, as it does not belong to forums or social networks platforms only, or to an electronic or chemistry domain.
• presentation logic finds in an user interface its quintessence, and it can be considered as the subset of application logic which governs the end user view of the system. I would not consider a difference of format in the whole representation of an object as presentation logic, though, as it falls into the realm of reusability I would want to keep in a Service Layer.

Commonly this different concerns of an application are organized in different layers, where each layer resides on the top of the previous one. In classic approaches, there is an infrastructure layer which the business logic layer depends on, and which deals for example with persistence issues. In more evolved approaches, however, keeping the Domain Model as the very core of the application is the most sound choice, moving infrastructure in a Service Layer which can plug in the Domain Model via implementing certain adapter interfaces (like a Repository or a Factory).

Thus a Service Layer is particularly useful for example when there are different front-ends to a common Domain Model. These front-ends, such as user interfaces or REST Apis, delegate the application logic to a Service Layer, which encapsulates it. Pushing this logic into the Domain Model would clutter the core of the application, since is is not strictly necessary to work with it.

Responsibilities of a Service Layer include, for starters, CRUD functions over objects of the respective Domain Model. Some of these responsibilities may be already included in the Domain Model (Factories for Entities and Value Objects), while other ones are usually only specified as interfaces with the implementations left to an infrastructure Service Layer (Repositories).

Example of the latter components are the bread and butter of a Service Layer. Persistence-related actions such as saving objects in a database, data translation (to and from Json, XML, yaml), integration of mail and every service which do not reside in the same PHP execution environment of the Domain Model is a candidate for a class or component in a Service Layer, whose implementations can be stubbed out in acceptance testing.

Note that services are also implemented in a Domain Model when they do not contain knowledge which spans outside of the domain and of basic language structures. Generally speaking, services are a point of connection between different Entities and objects, which accomodate operations that would couple the other objects together if implemented directly on them. Only when there are more concerns involved than the execution of logic on domain objects - persistence or orthogonal operations - these services shall be moved to an upper level component like a Service Layer.

In some cases, the Service Layer becomes overly generic and orthogonal to the underlying Domain Model, to the point that it is recycled in different applications. Object-relational mappers are part of the infrastructure, and a common example of reusable services. Though, the composition of libraries objects (has-a relationship) is preferable to the direct usage of them, or to their subclassing. Generic frameworks and libraries have a catch-all Api, while a specific Service Layer defines only the use cases actually employed by the front-ends - for example removing the unnecessary update of crucial entities that should be immutable by modelling.

Finally, a Service Layer can work without an underlying Domain Model, by interfacing to external web (and non-web) services. If there is local state involved, however, it is difficult to avoid having a basic Domain Model just to define data structures that the Services pass around. The client code, which resides in front-end, has no knowledge of the difference between methods that act over a local Domain Model or an external entity: the Service Layer effectively isolates the upper layer from changes in the lower one.

The code sample builds on the sample presented in the Domain Model article, continuing with the idea of an upper level layer. The sample features two service classes, one as a stubbed implementation of an interface of the Domain Model and one that it is employed only at an higher level.

<?php
require_once 'domain.php';

/**
 * Adapter for an interface defined in the lower layer
 */
class DumbEmailRepository implements EmailRepository
{
    public function getEmailsFor($address)
    {
        // fake implementation
        $mail = new Email();
        $mail->setSender('alice@example.com');
        $mail->setRecipient('bob@example.com');
        $mail->setSubject('Important stuff');
        $mail->setText('I wanted to talk you about...');
        return array(
            $mail
        );
    }
}

/**
 * Service that belongs only to the very Service Layer. 
 * It may have an interface, but it will be kept in this layer.
 */
class EmailTransferService
{
    /**
     * Transforming an object to XML is a common task for a Service Layer.
     * However, dependencies towards the Domain Model are well-accepted
     * but they don't mean that this layer's classes should be 
     * included in the lower layer.
     * Keeping the XML transformation in one place aids different front-ends
     * in sharing code.
     */
    public function toXml(Email $mail)
    {
        return "<mail>\n"
             . "    <sender>" . $mail->getSender() . "</sender>\n"
             . "    <recipient>" . $mail->getRecipient() . "</recipient>\n"
             . "    <subject>" . $this->_encode($mail->getSubject()) . "</subject>\n"
             . "    <text>" . $this->_encode($mail->getText()) . "</text>\n"
             . "</mail>\n";
    }

    protected function _encode($text)
    {
        return htmlentities($text);
    }
}

// client code
$repository = new DumbEmailRepository();
$transferService = new EmailTransferService();
foreach ($repository->getEmailsFor('bob@example.com') as $mail) {
    echo $transferService->toXml($mail);
}