Action-Domain-Responder and the “Domain Payload” Pattern

tl;dr: Instead of inspecting a Domain result to determine how to present it, consider using a Domain Payload Object to wrap the results of Domain interaction and simulataneously indicate the status of the attempted interaction. The Domain already knows what the results mean; let it provide that information explicitly instead of attempting to re-discover it at presentation time.

In Action-Domain-Responder the Action passes input to the Domain layer, which then returns some data for the Action to pass to the Responder. In simple scenarios, it might be enough for the Responder to inspect the data to determine how it should present that data. In more complex scenarios, though, it would make more sense for the Domain to pass back the data in a way that indicates the status of the data. Instead of the Responder inspecting the Domain results, the Domain should tell us what kind of results they are.

For example, let’s look at an example of some older code to update a Blog post. This is MVC-ish code, not ADR code; we’ll refactor along the way.

<?php
class BlogController
{
    // POST /blog/{id}
    public function update($id)
    {
        $blog = $this->model->fetch($id);
        if (! $blog) {
            // 404 Not Found
            // (no blog entry with that ID)
            $this->response->status->set(404);
            $this->view->setData(array('id' => $id));
            $content = $this->view->render('not-found');
            $this->response->body->setContent($content);
            return;
        }

        $data = $this->request->post->get('blog');
        if (! $blog->update($data)) {
            // update failure, but why?
            if (! $blog->isValid()) {
                // 422 Unprocessable Entity
                // (not valid)
                $this->response->status->set(422);
                $this->view->setData(array('blog' => $blog));
                $content = $this->view->render('update');
                $this->response->body->setContent($content);
                return;
            } else {
                // 500 Server Error
                // (i.e., valid data, but update failed for some other reason)
                $this->response->status->set(500);
                return;
            }
        }

        // 200 OK
        // (i.e., the update worked)
        $this->response->status->set(200);
        $this->view->setData(array('blog' => $blog));
        $content = $this->view->render('update');
        $this->response->body->setContent($content);
    }
}
?>

We can see that there is some amount of model work going on here (look for a blog post, attempt to update it if it exists, check for error conditions on the update attempt). There is also some amount of presentation work going on; remember, the view is not the template – the view is the response. So, even though the view templates are separated, the HTTP status codes are also part of the presentation, meaning that there is an insuffcient level of separation of concerns.

In converting this to Action-Domain-Responder, we can pretty easily extract the model work to a Domain, and the presentation work to a Responder, resulting in something like the following. (Note that the Domain layer now adds values to the returned $blog entity to indicate different failure states.)

<?php
class BlogUpdateAction
{
    // POST /blog/{id}
    public function __invoke($id)
    {
        $data = $this->request->post->get('blog');
        $blog = $this->domain->update($id, $data);
        $this->responder->setData('id' => $id, 'blog' => $blog);
        $this->responder->__invoke();
    }
}

class BlogUpdateResponder
{
    public function __invoke()
    {
        if (! $this->data->blog) {
            // 404 Not Found
            // (no blog entry with that ID)
            $this->response->setStatus(404);
            $this->view->setData($this->data);
            $content = $this->view->render('not-found');
            $this->response->body->setContent($content);
            return;
        }

        if ($this->data->blog->updateFailed()) {
            // 500 Server Error
            // (i.e., valid data, but update failed for some other reason)
            $this->response->status->set(500);
            return;
        }

        if (! $this->data->blog->isValid()) {
            // 422 Unprocessable Entity
            // (invalid data submitted)
            $this->response->setStatus(422);
            $this->view->setData($this->data);
            $content = $this->view->render('update');
            $this->response->body->setContent($content);
            return;
        }

        // 200 OK
        // (i.e., the update worked)
        $this->view->setData($this->data);
        $content = $this->view->render('update');
        $this->response->body->setContent($content);
    }
}
?>

But at this point we’re still inspecting the Domain result to see how we should present it. This strikes me as a lot of work to determine something the Domain already knows.

Instead of re-discovering the Domain status in the Responder, we should let the Domain tell us not only the data, but also what to think about that data. The Domain should give us an indication as to what it tried to do, and whether it succeeded or not. Then we can completely skip the inspection of the Domain results and present those results without lots of additional work.

The key to doing this is something called a Domain Payload Object. (Initially I called this a “Domain Result” but my recent reading of Vernon’s Implementing Domain Driven Design revealed the term to me. I love finding the right word for a concept!)

With a Domain Payload, we wrap the Domain results in an object that carries those results for us. We can then extend the semantics of the Domain Payload to tell us what kind of payload it carries. Something as simple as the class name of the Domain Payload can give us that information.

In the ADR example code we will find a series of Domain Payload objects. While these map closely to HTTP response codes for simplicity’s sake, other Domains are very likely to have different kinds of payload statuses. The point is that each Payload object explicitly tells us what the results indicate: entity not found, invalid data in the entity, database error, successful update, and so on.

The BlogUpdateAction remains straightforward. However, the example BlogService‘s update() method now does all the update work, and it wraps all returned results in a Domain Payload that indicates the result status.

Finally, the BlogUpdateResponder, which itself extends an AbstractResponder, can match a Domain Payload class name to a method that presents the payload results.

Voila: no more inspection of the results to figure out presentation. We let the Domain tell us what it tried to do and whether it worked or not (and what the cause of the failure was, if any). At the presentation layer, our Responder can honor (or ignore) that information at its convenience.

New Aura v2 Stable Releases, and More

New v2 releases, and hey, what’s this about Aura.Di finally getting auto-resolution of typehinted parameters?

First, we have brand new 2.0.0 stable releases of these v2 packages!

Next, the Aura.Di package just got bumped to 2.0.0-beta2. This package in particular has seen some great new improvements, most notably auto-resolution of typehinted constructor parameters, and a brand-new README. Check it out at https://github.com/auraphp/Aura.Di.

Emphasis not in original; read the whole notice at http://auraphp.com/blog/2014/09/03/new-releases/.

Auto-resolution of typehinted parameters is something I’ve been against since the beginning of Aura.Di. After having used implicit magical convention for a long time, I have learned to prefer explicit configuration. However, auto-resolution turned out to be relatively simple to add, and the tradeoff of not having to explicitly specify every lazyNew('ClassName') every time on every parameter seems reasonable. (One hopes one does not get burned later for having made this concession.)

On Project Structure; or, The Framework/App Is Not Special

(I apologize for the hasty writing here; this subject makes me impatient.)

Reading this post from Code Rabbi makes me reflect on project structure and organization. Frankly, most project structures (as from CodeIgniter, Cake, and all the popular frameworks since then) strike me as misdirected. They’re examples of why the project maintainers think their code is somehow special and different, and that the application built from it is also somehow special and different.

Your framework and application code are not special. Their code does not go in a special place. There’s no need for a top-level “app” directory with its own special subdirectories. There’s no need for a special naming convention to keep your different application-specfic code in specific places.

We had PSR-0, and now have PSR-4, and the Composer autoloader, to handle all that for you. Just use namespaces. All you need for code at the top level of your project is a “src” directory, where all your app code goes, just like all your library code goes in a “src” directory in a library package.

Instead of /app/controllers and /app/models, you have /src/Controller and /src/Model, or however else you want to organize your namespaced code. Then there’s no need for a special autoloading system or for hard-coded paths just for your application-level code. Add one single line to Composer that points to the src directory and voila, everything inside it loads for you.

That’s it. Nothing special. Just like every other library in your system.

(Again, this was hastily written. Please ask for clarficiation if you feel you need it.)

DRY is about Knowledge

From Matthias Verraes:

“Don’t Repeat Yourself” was never about code. It’s about knowledge. It’s about cohesion. If two pieces of code represent the exact same knowledge, they will always change together. Having to change them both is risky: you might forget one of them. On the other hand, if two identical pieces of code represent different knowledge, they will change independently. De-duplicating them introduces risk, because changing the knowledge for one object, might accidentally change it for the other object.

This is a great observation, one I had not considered before. It makes me feel a lot better about the very few and very minor duplications of code in the various independent and decoupled libraries in Aura. In short, DRY is not a reason to couple code libraries with similar behaviors; instead, it is a reason to have a single canonical source of knowledge within a system.

Back On The Market!

After a year spent writing my book, working on Aura, speaking at conferences and user groups, advising startups, and proposing new design patterns, I am back on the market.

I’ve been writing PHP code since 1999, and in that time I’ve been everything from a junior developer to a VP of Engineering. If you have a PHP codebase that requires some attention, especially a legacy app that needs to be modernized, I’m your man. I’m also excellent as a leader, mentor, manager, and architect, on small teams and on large ones.

Resume and references available on request. Contact me by email (pmjones88 at gmail) or on Twitter @pmjones if you want to talk!>

UPDATE (Tue 19 Aug): Well that was quick. I’m off the market again, and looking forward to productive efforts with my new employer. My deepest gratitude to everyone who expressed interest; I am truly humbled by the whole experience. Thank you to all.

Soccer, Development, and The Value Of Teamwork

The lesson of soccer is that individual effort will often suffice when things are relatively easy. But in order to surmount the more difficult challenges, you will almost always need reliable teammates of one sort or another.

I assert the same is true in development efforts. A single developer working alone can do good work, but a team of frontend devs, backend devs, devops, and DBAs can do stuff that is truly amazing. Combine your comparative advantages instead of trying to do everything yourself. Via Vox Popoli: Calcio is life.

Action-Domain-Responder, Content Negotiation, and Routers

While talking about Action-Domain-Responder on the Crafting Code Tour, one of the common questions I got was: “Where does content negotiation happen?” My response was always: “Where does it happen in Model-View-Controller?” That opened up a discussion on how content negotiation is a tricky bit that can go in different places, depending on how you want the concerns separated, and is not a problem specific to ADR.

However, I’ve not really been satisfied with that outcome. I enjoyed the question and the discussion, but it never seemed to resolve itself. We were left with this tension between resource conservation and proper separation of concerns. Should negotiation happen in the the Action (Controller), the Domain (Model), or the Responder (View)?

At first it seems like this is clearly a (re)presentation issue, and as such ought to go in the Responder or View. But if the Responder cannot present an acceptable content type for the request, that means we have done a lot of work in the Domain to build objects that will be discarded in favor of a “406 Not Acceptable” response. This is not a good use of our limited resources.

Perhaps the Domain is the place for negotiation? I think we can dismiss this outright. The Domain should not be in charge of returning different presentations of its data.

Finally, we might try negotiation in the Action (Controller). Here we examine the request, and query the Responder to see what content types it can present in responses. (Alternatively, we embed the available content types in both the Action and Responder, duplicating that information somewhat.) If the negotiation fails in the Action, we skip the Domain work and instruct the Responder to return a “406 Not Acceptable”. But that means the Action is now responsible for at least a little bit of the response-building logic. It’s not horrible, but it does not seem as clean as it could be.

After thinking about this for a while, I am beginning to think it is reasonable to perform what I will call a “first filter” on the Accept header at the Front Controller level, specifically in the Router. We already consider the Router as a guard to map incoming requests to appropriate Actions, inspecting the path, HTTP method, and other request information. Inspecting the acceptable types seems a reasonable addition to these elements.

A full content negotiation at the Router level is probably overkill. Really, all the Router needs to know is what content types are provided through particular Route (whether an MVC or ADR one). The matching logic can do a naive check of the Accept request header to see if one of the provided types is present with a non-zero “q” value. If none of the types is present, the Router can move along to the next route, possibly tracking the failure so a Dispatcher can directly invoke a Responder for routing failures. This way, the Router never invokes a non-matching Action, thereby conserving the Domain resources. If the match is successful, the Responder can do the “real” content negotiation work, using an Accept header value passed to it as input from the Action along with the Domain data.

As a proof of concept, I have modified the Aura.Router library to recognize “accept” specifications on the route, and the tests indicate it seems to work just fine.

An Updated Preview Of Aura.Auth

It can be difficult to find a truly standalone, authentication-only library, and Aura.Auth fits that bill.

The library is still under development, but the major pieces are all now in place:

Each layer can handle custom implementations. There are instructions for custom adapters, custom session managers (including session-less authentication), and custom services.

Via An Updated Preview Of Aura.Auth.

Modernizing Legacy PHP: From Service Locator To Dependency Injection

In an earlier article I described how to start moving away from singletons in favor of dependency injection. It occurs to me that the process for moving away from Service Locator is almost exactly the same, except that we use the container outside the class instead of inside it.

Let’s say we have a class that uses a Service Locator. First we examine the class for all uses of the locator. Then, we create constructor parameters for the dependencies it extracts from the locator, and add setter code for those dependencies in the constructor body. For example, we can convert the above Service Locator example classes to these dependency-injected variations:

<?php
class FooClass
{
    protected $db;
    public function __construct(Database $db)
    {
        $this->db = $db;
    }
}

class BarClass
{
    protected $db;
    public function __construct(Database $db)
    {
        $this->db = $db;
    }
}
?>

Finally, any time we instantiate one of these dependency-injected classes, we use the locator outside the class to retrieve the dependencies. We then pass them to the new call for the class. For example:

<?php
// for FooClass
$db = $container->get('db');
$foo = new FooClass($db);

// for BarClass
$db = StaticContainer::get('db');
$bar = new BarClass($db);
?>

Now the class dependencies are explicit and predictable, instead of implicit and unpredictable (i.e., the class might depend on any combination of dependencies hidden inside the container). It is also somewhat easier to build a test, since we only have to build the dependencies themselves, not the container that holds the dependencies.

Afterword

Are you overwhelmed by a legacy PHP application? Have you inherited a spaghetti mess of code? Does it use globals everywhere, so that a fix in one place causes a bug somewhere else? Does every feature addition feel like slogging through a swamp of includes?

It doesn’t have to be that way. “Modernizing Legacy Applications in PHP” gives you step-by-step instructions on how to get your legacy code under control by eliminating globals and separating concerns. Each chapter shows you exactly one task and how to accomplish it, along with common questions related to that task.

When you are done, you will come and go through your code like the wind. Your application will have become autoloaded, dependency injected, unit tested, layer separated, and front controlled. And you will have kept it running the whole time.

Buy the book today!