An Introduction to Services

Tweet

While admittedly the concept comes from the empirical field rather than academic, it applies quite well to the pragmatism of the real world – most software applications behave pretty much like whimsical babies with an unavoidably “tendency” to grow in size and complexity over time. There’s nothing inherently wrong with having babies growing up healthy here and there, but the situation can be radically different with applications, especially when they become bloated, twisted monsters having little to do with the sweet, tiny creatures they once were.

The problem isn’t growth per se, as having a future-proof application spreading its wings wide toward further horizons can be a sign of good design. The real issue is when the expansion process is achieved at the expense of redundant boilerplate implementations of things scattered throughout different layers. We’ve all been there (mea culpa) and we all know that logic duplication is a serious software disease.

Even when well-trusted programming techniques help strip out duplicated logic, sometimes they’re just not enough to fix the issue by themselves. A clear example of this is MVC; the model (the Domain Model, not the obtrusive, catch-all database one) does its business in relaxed isolation, then the skinny controllers grab the model’s data through a mapper or repository pass it on to the view or any other output handler for further rendering. The scheme may deliver, but it doesn’t scale well.

Say the model data should be massaged in some additional manner and interfaced to an external API such as Facebook, Twitter, a third-party mailer, you name it, at multiple places. In such cases, the whole massaging/interfacing process is application logic from top to bottom, hence the controllers’ responsibility. Before you know it, you’re forced to duplicate the same logic across a bunch of controllers, thus putting your toes on the forbidden terrain of logic duplication. Busted!

If you’re like me, you’re probably wondering how to tackle the problem without hitting your head against a brick wall. In fact, there’s a few approaches that do the job quite well. There’s one in particular I find appealing because it plays nicely with Domain Models, and therefore with Domain-Driven Design. And what’s more, if you’ve peeked at the article’s title, you’ve probably guessed I’m referring to Services.

What is a Service?

A services is an abstraction layer placed on top of the domain model which encapsulates common application logic behind a single API so that it can be easily consumed by different client layers.

Don’t let the definition freak you out, as if you’ve been using MVC for a while the chances are you’ve used a service already. Controllers are often called services, as they carry out application logic and additionally are capable of interfacing to several client layers, namely views. Of course in a more demanding environment, plain controllers fail short in handling several clients without the aforementioned duplicating, so that’s why the construction of a standalone layer is more suitable in such cases.

Creating a Simplistic Domain Model

Services are real killers when working with enterprise-level applications whose backbone rests on the pillars of a rich Domain Model and where the interplay with multiple clients is the rule rather than the exception. This doesn’t mean that you just can’t use a service for your next pet blog project, because in fact you can, and most likely nobody will punish you for such an epic effort.

I have to admit my own words will come back to haunt me sooner or later, though, as my “naughty” plan here is to create a service from scratch which will interface a domain model’s data, composed of a few user objects, to two independent client layers. Sounds overkill, sure, but hopefully didactic in the end.

The following diagram shows in a nutshell how this experimental service will function at its most basic level:

Service Diagram

The service’s behavior is rather trivial. Its responsibility can be boiled down to just pulling in data from the domain model, which will be then JSON-encoded/serialized, and exposed to a couple of clients (Client Layer A and Client Layer B). The beauty of this scheme is that the entire encoding/serialization logic will live and breath behind the API of a service class placed on top of the model, thus shielding the application from redundant implementation issues while still leaving the door open to plugging in additional clients further down the road.

Assuming that building the service will flow from bottom to top, the first tier to be built is the the Data Access Layer (DAL). And since the tasks bounded to the infrastructure will be limited to storing /fetching model data from the database, this layer will look pretty much the same as the one I wrote in a previous article.

With the DAL doing its thing, let’s go one step up and start distilling the domain model. This one will be rather primitive, tasked with modeling generic users:

<?php
namespace Model;

abstract class AbstractEntity
{
    public function __set($field, $value) {
        if (!property_exists($this, $field)) {
            throw new InvalidArgumentException(
                "Setting the field '$field' is not valid for this entity.");
        }

        $mutator = "set" . ucfirst(strtolower($field));
        method_exists($this, $mutator) &&
            is_callable(array($this, $mutator))
            ? $this->$mutator($value) : $this->$field = $value;

        return $this;
    }

    public function __get($field) {
        if (!property_exists($this, $field)) {
            throw new InvalidArgumentException(
                "Getting the field '$field' is not valid for this entity.");
        }

        $accessor = "get" . ucfirst(strtolower($field));
        return method_exists($this, $accessor) &&
            is_callable(array($this, $accessor))
            ? $this->$accessor() : $this->$field;
    }

    public function toArray() {
        return get_object_vars($this);
    }
}
<?php
namespace Model;

interface UserInterface
{
     public function setId($id);
     public function getId();

     public function setName($name);
     public function getName();

     public function setEmail($email);
     public function getEmail();

     public function setRanking($ranking);
     public function getRanking();
}
<?php
namespace Model;

class User extends AbstractEntity implements UserInterface
{
    const LOW_POSTER = "low";
    const MEDIUM_POSTER = "medium";
    const TOP_POSTER = "high";

    protected $id;
    protected $name;
    protected $email;
    protected $ranking;

    public function __construct($name, $email, $ranking = self::LOW_POSTER) {
        $this->setName($name);
        $this->setEmail($email);
        $this->setRanking($ranking);
    }

    public function setId($id) {
        if ($this->id !== null) {
            throw new BadMethodCallException(
                "The ID for this user has been set already.");
        }
        if (!is_int($id) || $id < 1) {
            throw new InvalidArgumentException(
                "The user ID is invalid.");
        }
        $this->id = $id;
        return $this;
    }

    public function getId() {
        return $this->id;
    }

    public function setName($name) {
        if (strlen($name) < 2 || strlen($name) > 30) {
            throw new InvalidArgumentException(
                "The user name is invalid.");
        }
        $this->name = htmlspecialchars(trim($name), ENT_QUOTES);
        return $this;
    }

    public function getName() {
        return $this->name;
    }

    public function setEmail($email) {
        if (!filter_var($email, FILTER_VALIDATE_EMAIL)) {
            throw new InvalidArgumentException(
                "The user email is invalid.");
        }
        $this->email = $email;
        return $this;
    }

    public function getEmail() {
        return $this->email;
    }

    public function setRanking($ranking) {
        switch ($ranking) {
            case self::LOW_POSTER:
            case self::MEDIUM_POSTER:
            case self::TOP_POSTER:
                $this->ranking = $ranking;
                break;
            default:
                throw new InvalidArgumentException(
                    "The post ranking '$ranking' is invalid.");
        }
        return $this;
    }

    public function getRanking() {
        return $this->ranking;
    }
}

Asides from doing some typical setter/getter mapping, and performing basic validation on the data, the behavior of the AbstractEntity and User classes don’t go any further than that. Regardless, they come in handy for bringing up to life a small, yet clean, domain model which can be tweaked at will.

The model should be hooked up to the DAL in some fashion without losing the pristine independence they have from each other. One straight and simple manner to accomplish this is through the facilities of a data mapper.

Interfacing the Model with the DAL

If you’ve ever tackled the process, you’ll know that building a full-stack data mapper capable of handling multiple domain objects and catching any impedance mismatches on the fly is not a simple task, and in many cases is an effective repellent for even the boldest of coders. But since the domain model here is rather simple, the user mapper I plan to deploy here is pretty straightforward.

<?php
namespace ModelMapper;
use ModelUserInterface;

interface UserMapperInterface
{
    public function fetchById($id);    
    public function fetchAll(array $conditions = array());
    
    public function insert(UserInterface $user);
    public function delete($id);
}
<?php
namespace ModelMapper;
use LibraryDatabaseDatabaseAdapterInterface,
    ModelUserInterface,
    ModelUser;

class UserMapper implements UserMapperInterface
{    
    protected $entityTable = "users";
    
    public function __construct(DatabaseAdapterInterface $adapter) {
        $this->adapter = $adapter;
    }
    
    public function fetchById($id) {
        $this->adapter->select($this->entityTable,
            array("id" => $id));        
        if (!$row = $this->adapter->fetch()) {
            return null;
        }
        return $this->createUser($row);
    }
    
    public function fetchAll(array $conditions = array()) {
        $users = array();
        $this->adapter->select($this->entityTable, $conditions);
        $rows = $this->adapter->fetchAll();
        
        if ($rows) {
            foreach ($rows as $row) {
                $users[] = $this->createUser($row);
            }
        }
        return $users;
    }
    
    public function insert(UserInterface $user) {
        $user->id = $this->adapter->insert($this->entityTable, array(
            "name"    => $user->name,
            "email"   => $user->email,
            "ranking" => $user->ranking));
        return $user->id;
    }
    
    public function delete($id) {
        if ($id instanceof UserInterface) {
            $id = $id->id;
        }
        return $this->adapter->delete($this->entityTable,
            array("id = $id"));
    }

    protected function createUser(array $row) {
        $user = new User($row["name"], $row["email"],
            $row["ranking"]);
        $user->id = $row["id"];
        return $user;
    }
}

Sure the UserMapper class is miles away for being a production-ready component, but it performs decently. In short, it runs a few CRUD operations on the domain model and reconstitutes User objects via its createUser() method. (I’ve left user updates as an exercise to the reader, so be ready for a pinch of extra fun).

Moreover, with the mapper comfortably resting between the model and DAL, the implementation of a service that outputs JSON-encoded data to the outer world should now become a more malleable process. As usual, concrete code samples are hard to beat when it comes to further elaborating this concept. So, let’s now build up the service in a few steps.

Building a Pluggable Service Layer

There’s a general consensus, which goes along the lines of Fowler‘s and Evan‘s thoughts that services should be thin containers wrapping only application logic. Business logic, on the other hand, should be shifted to inside the boundaries of the domain model. And as I like to stick to the clever suggestions that come from the higher-ups, the service here will adhere to these.

Having said that, it’s time to create the service layer’s first element. This one is a basic interface which will enable us to inject different encoder/serializer strategies into the service’s internals at runtime without amending a single line of client code:

<?php
namespace Service;

interface EncoderInterface
{
    public function encode();
}

With the above interface in place, spawning a few implementers is really simple. Moreover, the following JSON wrapper proves why my claim is true:

<?php
namespace Service;

class JsonEncoder implements EncoderInterface
{
    protected $data = array();
    
    public function setData(array $data) {
        foreach ($data as $key => $value) {
            if (is_object($value)) {
                $array = array();
                $reflect = new ReflectionObject($value);

                foreach ($reflect->getProperties() as $prop) {
                    $prop->setAccessible(true);
                    $array[$prop->getName()] =
                        $prop->getValue($value);
                }
                $data[$key] = $array;
            }
        }
        
        $this->data = $data;
        return $this;
    }
    
    public function encode() {
        return array_map("json_encode", $this->data);
    }
}

If you found easy to grasp how the JsonEncoder does its thing, make sure to check the one below which sets a naive PHP serializer:

<?php
namespace Service;

class Serializer implements EncoderInterface
{
    protected $data = array();
    
    public function setData(array $data) {
        $this->data = $data;
        return $this;
    }

    public function encode() {
        return array_map("serialize", $this->data);
    }
}

Because of the functionality provided by the encoder and the serializer out the box, the implementation of a service that JSON-encodes and serializes model data can be now embraced with confidence. Here’s how this service looks:

<?php
namespace Service;
use ModelMapperUserMapperInterface;

class UserService
{
    protected $userMapper;
    protected $encoder;

    public function __construct(UserMapperInterface $userMapper, EncoderInterface $encoder = null) {
        $this->userMapper = $userMapper;
        $this->encoder = $encoder;
    }

    public function setEncoder(EncoderInterface $encoder) {
        $this->encoder = $encoder;
        return $this;
    }

    public function getEncoder() {
        if ($this->encoder === null) {
            throw new RuntimeException(
                "There is not an encoder to use.");
        }
        return $this->encoder;
    }
    
    public function fetchById($id) {
        return $this->userMapper->fetchById($id);
    }

    public function fetchAll(array $conditions = array()) {
        return $this->userMapper->fetchAll($conditions); 
    }
    
    public function fetchByIdEncoded($id) {
        $user = $this->fetchById($id);
        return $this->getEncoder()->setData(array($user))->encode();
    }
    
    public function fetchAllEncoded(array $conditions = array()) {
        $users = $this->fetchAll($conditions);
        return $this->getEncoder()->setData($users)->encode($users);
    }
}

At a glance, it seems the UserService class is irreverently sitting on the user mapper with the sole purpose of eating up its finders or acting like a plain repository. But in fact it does a lot more than that, as its fetchByIdEncoded() and fetchAllEncoded() methods encapsulate in one place all the logic necessary for encoding/serializing model data according to the encoder passed in to the constructor or setter.

While the class’ functionality is limited, it shows in a nutshell how to build a service layer that mediates between the model and a couple of clients which expect to get in data in a specific format. Of course I’d be a jerk if I didn’t show you how to finally get things rolling with such a service, So, the example below uses it for fetching users from the database:

<?php
use LibraryLoaderAutoloader,
    LibraryDatabasePdoAdapter,
    ModelMapperUserMapper,
    ServiceUserService,
    ServiceSerializer,
    ServiceJsonEncoder;

require_once __DIR__ . "/Library/Loader/Autoloader.php";
$autoloader = new Autoloader;
$autoloader->register();

$adapter = new PdoAdapter("mysql:dbname=mydatabase", "myfancyusername", "mysecretpassword");

$userService = new UserService(new UserMapper($adapter));

$userService->setEncoder(new JsonEncoder);
print_r($userService->fetchAllEncoded());
print_r($userService->fetchByIdEncoded(1));

$userService->setEncoder(new Serializer());
print_r($userService->fetchAllEncoded(array("ranking" => "high")));
print_r($userService->fetchByIdEncoded(1));

Despite a few obvious limitations, it’s clear to see that the service is a flexible component, which not only encodes user objects according to some predefined format, but also allows adding more encoders along the way thanks to the strategy pattern‘s facilities. Of course, its most engaging virtue is the ability for placing common application logic behind a clean API, a must for applications that need to perform a host of additional centralized tasks such as further processing domain model data, validation, logging, and more.

Summary

Even while services are still making their first timid steps in PHP’s mainstream (except for some specific platforms like FLOW3 and a few other frameworks that shyly provide a base blueprint for creating services in a painless manner), they’re solid, well-proven solutions in the enterprise world where systems usually rest on the foundations of a rich domain model and interact with a wide variety of client layers.

Despite this rather overwhelming scenario, there’s nothing that explicitly prevents you from sinking your teeth into the goodies of services in smaller, more modest environments, especially if you’re playing around with some core concepts of DDD. So, now that you know what’s going on under the hood of services, feel free to give them a shot. You won’t regret it.

Image via kentoh / Shutterstock

Free book: Jump Start HTML5 Basics

Grab a free copy of one our latest ebooks! Packed with hints and tips on HTML5's most powerful new features.

  • http://jeungun.wordpress.com Jeune

    Great article! I use this design too in all of my apps.

  • Alex Gervasio

    Hey, putting your feet down in the pool of DDD too? Welcome aboard :-). Glad you liked the writeup.

    • http://jeungun.wordpress.com Jeune

      I never actually learned it from DDD. Learned it from Martin Fowler’s Patterns of Enterprise Application Architecture.

      • Alex Gervasio

        Alright, I got it now. One of the nicest things about PoEEA is that it packages all in the same menu both enterprise-level stuff and basic yet fundamental patterns, such as Separated Interfaces or Layer Supertype.

  • Kise S.

    nice reading, thank you

    • Alex Gervasio

      Glad to know the article has been informative.
      Thanks.

  • Steve

    Alex,
    This was a really nice way to demonstrate how to effectively use a Service Layer. I have been implementing a sevice layer into the most recent project that I am doing that in the end will require many different service strategies. I like your ideas and will be able to incorporate them into this undertaking. Thank you.
    Steve

    • Alex Gervasio

      Hey Steve,
      I’m happy to see the tutorial has been instructive, considering the fact you’ve been playing around with services for a while.
      Thanks for the comments.

  • Sharlon Balbalosa

    I am learning how to implement DDD but I don’t know how to handle relationship most of the examples I saw is using a data mapper with 1-1 association with their domain. What if I have a two domain with one-many relationship where does the relationship reflect is it in the mapper, if so what will the mapper looks like?

    • Alex Gervasio

      Sharlon,
      I guess the lack of approachable examples out there that show how to implement functional data mappers, capable of handling the most typical relationships that can be defined between domain objects obeys to a rather simple reason: mappers are in most cases complex to set up beasts, which not only must deal with the so-called impedance mismatches when it comes to persisting the model in the database, a web service, and so forth, but they must be clever enough to create complex object graphs, when reconstituting back domain objects between requests. That’s a bunch of heavy logic, certainly pretty hard to package in just a few ready to-use snippets that can tweaked and twisted at will.
      Anyway, (and I’m not being just an unbearable braggart, trust me) if you’re interested in peeking at a customizable relational data mapper implementation, you may want to check an article I wrote on the topic right here http://phpmaster.com/integrating-the-data-mappers/, which shows how to exploit the benefits of plain Dependency Injection (sorry, neither annotations, nor XML, YAML files are used to get things rolling) to handle a one-to-many relationship between a few blog post objects and the comments clinging of them. Of course, peeking at the internals of some libraries like Doctrine http://www.doctrine-project.org/, RedBeanPHP http://redbeanphp.com or PhpDataMapper http://phpdatamapper.com/ may help as well, even though catching the mappers’ driving logic surely will take you a little longer.
      I hope that helps you out.

  • Kyle

    Great article Alex.
    Question about keeping business logic in the domain model: do you feel this is absolutely necessary? I hear a lot of DDD purists say that by moving business logic to a service class, we’re essentially reverting back to procedural programming. I disagree with the notion, because (admittedly dependent on how you structure your services) we’re just moving our member variable into a different type, and then creating a new class with methods that alter a variable of that type.
    This requires more documentation and policy, as it would become easy to create service objects that could just as easily be static function calls. But to me the benefits of separating my concerns and leaving each class with a single responsibility outweigh the negatives of someone possibly using the code as it wasn’t intended.
    I’m curious what your thoughts are, as you seem to be up to your waist, and my feet are just getting wet. Thanks again!

    • Alex Gervasio

      Hey Kyle,
      Glad you enjoyed the article. In regard to your questions, well, definitively you can be more or less restrictive in implementing a domain model. Maybe you can even make some subtle concessions in the way that the objects are going to interact with each other and put a pinch of business logic in a service (to me that’s simply cheating on yourself); however, you should never miss the primary, primordial purpose of the pattern, which justifies the hard effort you went through for building up the model in the first place: create a set of interrelated business objects, with well-defined responsibilities and constraints, which in all the cases are persistence agnostic.
      If, for whatever reason, you start shifting business logic to inside the boundaries of a service, sooner or later you’ll end up with an anemic, rotted model, barely sustaining some setters/getters, which certainly have nothing to do with the rich structure you had in mind at first. So, why did you go with a domain model, if you’re either deliberately or unintentionally twisting it into a skinny structure that behaves pretty much like a moronic data holder with no behavior embedded into it? Pretty pointless, indeed.
      With that said, make sure your classes honor OOP basic principles: they’re just blueprints for objects with data and behavior, hence they should carry state. Don’t get caught in the trap of using class constructs as namespaces for doing procedural programming, nicely disguised behind a crowd of static methods. They open up the doors of mutable global state, and are old-fashioned, even when it comes to controlling object instantiation (read Singletons). Dependency Injection delivers a lot better, as it breaks up tight coupling, and allows to take advantage of the benefits that Polymorphism provides right out the box, as well as programming to interfaces.
      I hope that sheds some light on your questions. Thanks for the feedback.

  • http://about.me/bruno.skvorc Bruno

    I believe the JsonEncoder suffers from a typo in the encode method. It should be $this->_data instead of $this->data, no?

    • Alex Gervasio

      Thanks Bruno for catching the typo. In fact, I prefixed the class members using underscores, but for some reason they got missed during the edition process. I’ll notify Tim, our venerable editor to fix up that.

      • http://about.me/bruno.skvorc Bruno

        No problem. Thanks a lot for your articles, been reading them on devshed as well, very helpful. Do you have a twitter/gplus handle? I’d love to be notified when you push out something new, wherever it is.

        • Alex Gervasio

          Hey Bruno,
          No twitter/G+ accounts, at least for now. Anyway, feel free to stop by here any time. There will be more tuts I wrote going live (hopefully) shortly. And of course, you can have even more fun and peek at other nice articles around here.

  • jay

    Thanks for sharing the knowledge,it is really informative ..thank you

    • Alex Gervasio

      Glad to hear that. Thanks!

  • Sandra

    Hi
    These tutorials are very interesting.
    Is it possible to download a complete example (entity, service layer and data layer)?
    Also, what is your opinion in terms of performance?
    A simpler structure would not it faster?

    • Alex Gervasio

      Hi Sandra,
      Glad you liked the write up. Sorry, there are no downloadable examples you just can test out of the box. Anyway, it’s pretty easy to hook up a customizable DAL like the one shown here to the mappers and put all the things to work in sweet synchronicity.
      Regarding your performance question, stacking extra abstraction layers in your programs surely impacts the overall performance, especially when compared to slim MVC implementations. Sometimes though, the magnitude of a project makes the use of services a must, so there’s not a lot of options to consider in such use cases.
      Thanks for the feedback.

  • David

    Great articles. I was just wondering do you recommend to have a “Service” for each entity/domain object? Or do you think Services should be broader, dealing with bigger chunks of application logic? Example: A post on a website has the post itself and comments. Should you only have a Post Service and not a Post and a Comment Service? Thanks.