The Template Is Not The View

As server-side web developers, we tend to think of our templating system as providing the View layer in a Model-View-Controller architecture. I have recently come to the conclusion that this is an incorrect approach. Instead, we need to think of the HTTP response as the View.

When an HTTP client makes an HTTP request, what does it get in return? It does not receive only the body of the HTTP response. The client receives the body and the headers of the HTTP response. The response as a whole is what the web application delivers as its presentation to the client.

Templating systems, as far as I can tell, deal only with the body of the HTTP response. In practice, the rest of the response is generally handled by the Controller; for example, setting the status, setting cookies, and modifying headers.

Let’s say we accept the idea that the HTTP response is the View (i.e., the presentation that is delivered to the client). If we accept that idea, then for a clean separation of concerns a la SeparatedPresentation, we need to combine both the template work and the header work into their own layer. That layer needs to be completely separated from the Controller and Model.

Thus, anything that deals with the response, including the setting of headers, should be considered the View layer. If you are setting headers in a Controller, you are losing that clean separation of concerns. To remedy this, your Controller needs to hand off to a layer that builds the response on its own; this is the proper place for the tempalting system to be invoked, not the Controller.

In summary: the template is not the View. The response is the View. We should separate our concerns accordingly.

Afterword

If you like the line of thinking presented here, please check out the Action-Domain-Responder refinement of the MVC pattern. It’s still a work-in-progress so be sure to leave your comments and criticism either here on this blog or as a new issue at Github.

“The Only Reason You Think You Are Smart Is Because An Idiot Called You A Genius”

This article about being able to be graduated by university applies to developers, too: begin by substituting “your first few projects” for “high school” and “the development community at large” for “college”.

You may think you are smart because you got high grades in high school, but the reality is that you’re not really as smart as you think you are; you just went to a high school where everyone was stupid so you just seem smart in comparison.

Compared to the much smarter students who normally attend our college, you’re going to find yourself at the bottom of the class. While the smarter students find passing their classes to be relatively easy, and even fun, that’s not going to be the case for you. For you, college will be hard work, difficult and unpleasant, if you want to graduate.

You have the ability to graduate if you put in the effort, and take advantage of the extra tutoring services we have available for you, but college will not be a fun experience for you. I still recommend that you attend our college, but if you think that you’re not willing to work very hard, to study while the smarter kids are having fun at beer parties, then you would be better off not attending our college.

via Who gets to graduate? | Lion of the Blogosphere.

(Title quote from Moses Ngone.)

5 Years Of PHP-FIG

A nice note from Brett Bieber:

Five years ago today, a group of PHP framework thought leaders came together to discuss interoperability and coordination. We met in a small room, talked our issues out together, agreed and disagreed respectfully.

At the time we were labeling our cause: “PHP Standards and Best Practices for PHP 5.3+ Frameworks and Libraries”

For better or worse, the group has evolved since then, but my hope is for continued success and interoperability.

Congrats to all the members, new and old.

Via the PHP-FIG Google Group.

Stephan Hochdörfer and Action-Domain-Responder

I’ve been asking for feedback on the Action-Domain-Responder pattern, a refinement of MVC, to discover how it’s being used in the wild already, and to solicit criticism of the pattern to find weak points.

The key points of Action-Domain-Responder:

  • Instead of a controller class with many action methods, each Action is its own class (or closure, like with Slim).

  • The Action interacts with the Domain (model), and feeds data to a Responder (view).

  • The Responder is entirely responsible for building the response, including all headers as well as the body of the response. This means that in ADR, the template is not the view; the response is the view.

Stephan Höchdorfer has been using single-Action classes for a while now. Here is my summary of his article:

  • “we are using action classes in our application framework for almost the last decade”

  • “action classes tend to be rather small, typically less than 100 loc for us”

  • “another bonus point for action classes: It is easier to search for a class name than a method name”

  • “Controllers tend to have a lot of dependencies. … people came up with a few “creative” solutions for this problem, mainly the creation of lazly loaded dependencies”

  • “action classes depend on what they really needed. Typically that’s just a few services for a single action. Again that makes the code way easier to understand and easier to test.”

  • “Action classes in contrast to controller classes can be reusable.”

Those were the highlights for me; you should read the whole essay to find your own: http://blog.bitexpert.de/blog/controller-classes-vs.-action-classes

In addition, please write up your own commands and criticism regarding Action-Domain-Responder, so that I can improve the offering as much as possible.

The Eternal Struggle Between Business and Programmers

The Business and the Programmers want the same thing. They want the same thing: to deliver a more predictable stream of important features that will make the market happy—or, at least, knowing the fickle market, that will risk disappointing them the least.

This. Is. Glorious.

The Business and the Programmers needs to agree on two things, each conceding a key point to the other. The Business needs to agree that the Programmers have heretofore gone more quickly than they really can, that they cannot sustain this pace, and that to do so merely hastens the ultimate decline of the entire product line, and perhaps the company. The Programmers need to agree that the Business has a legitimate need to deliver more features, that everyone’s livelihood depends on this, and that trying to ask for more than the Programmers can deliver forms part of the Business’s “job”, as it were. The market compels them to do this. In this equation, the Programmers have the responsibility to do whatever they can to maximise their ongoing delivery speed, and that includes regular, agreessive refactoring.

Finally, both the Business and the Programmers have to agree that they have wasted too much time arguing about this and need to move forward. They want the same thing! They can have it!

via The Eternal Struggle Between Business and Programmers – The Code Whisperer.

Aura.View and Aura.Html 2.0.0-beta1 Released!

Aura.View 2.0.0-beta1 is a reduced implementation of the v1 View package. …

The templates can still be include files, but (and this is new) they can also be closures. This means that you can completely avoid the file system for templates if you like. …

There are no longer any escapers or helpers included, although the package does include a bare-bones HelperRegistry so you can add your own callables as helpers.

Aura.Html 2.0.0-beta1 contains a collection of helpers extracted from the v1 Aura.View package. These helpers are completely standalone and are not dependent on any particular view system: instantiate a HelperLocator from the Aura.Html package and you can use the helpers from any PHP code. …

All of the HTML5 input types are supported. This makes building form elements very easy, especially since the data structure for each element is just an array. Any library that can generate the recognized array structure can be used to feed the form input helpers. …

In addition, [Aura.Html] includes a powerful escaping mechanism derived from Zend\Escaper and modified for conceptual integrity with the rest of Aura. The Aura.Html Escaper exposes static methods to make escaping as non-verbose as possible.

Read the whole thing at http://auraphp.com/blog/2014/05/15/view-html-2beta1/!

Quick Hits: ADR Pattern Progress, MLAPHP Softcover, Aura Notices

Just some short updates today, since last week was so very busy:

1. The “Action-Domain-Responder” (née “Action-Domain-Response”) refinement of the MVC pattern has received some positive criticism and attention. In addition to example code updates, I have added responses (heh) to critiques regarding the Resource-Method-Representation pattern, and will soon be adding a response regarding “Entity-Interactor-Boundary” (aka “Entity-Contol-Boundary”). Many thanks to the commenters who recognized that they were already doing something along the lines of ADR; this helps to validate the pattern as something that already occurs “in the wild.” If you like the pattern offering, please star it at Github.

2. Modernizing Legacy Applications in PHP is now available for purchase in softcover via Lulu.com.

3. It looks like the next two Aura v2 releases will be Aura.View (the view system, specifically the “reduced” branch) and Aura.Html (the HTML helper collection that can be used by any view system). I’ve done a lot of work on them in the past few days and they’re beginning to feel like they’re ready.

Cheers all!

Action-Domain-Response: A Tentative MVC Refinement

UPDATE: This article has been turned into a working draft, with PHP-based example code, at https://github.com/pmjones/mvc-refinement.


(This post is an offering of a first draft, not a final version. I feel very much like I am slowly feeling my way toward something, rather than declaring a completed definition out-of-hand. It may end up being a dead end, or it may already exist in some form with which I am not familiar. Even so, I want to present it for thoughtful, considerate commentary.

The term MVC has experienced some semantic diffusion from its original meaning, especially in a web context. Because of this diffusion, the Action-Domain-Response pattern description is intended as a web-specific refinement of the MVC pattern.

I think ADR more closely fits what we actually do in web development on a daily basis. For example, this pattern is partly revealed by how we generally do web routing and dispatch. We generally route and dispatch not to a controller class per se, but to a particular action method within a controller class.

It is also partly revealed by the fact that we commonly think of the template as the View, when in a web context it may be more accurate to say that the HTTP response is the View. As such, I think ADR may represent a better separation of concerns than MVC does in a web context.

Action-Domain-Response

Organizes a single interaction between a web client and a web application into three distinct roles.

    Action ---> Response
      ||
    Domain 

Terms

Action (taken from <form action="...">) is the logic that connects the Domain and Response.

Domain is the domain logic. It manipulates the domain, session, application, and environment data, modifying state and persistence as needed.

Response is logic to build an HTTP response or response description. It deals with body content, templates and views, headers and cookies, status codes, and so on.

Narrative

Operational Description

  1. The web handler dispatches the incoming request to an Action.

  2. The Action interacts with the Domain and gets back Domain data.

  3. The Action feeds the Domain data to the Response logic, and then gives control to the Reponse.

  4. The web handler sends the response back to the client.

Compare and Contrast With MVC

The dominant pattern describing web interactions is Model-View-Controller. Is Action-Domain-Response really just Model-View-Controller in drag? We can see that the ADR terms map very neatly to MVC terms:

Model      <--> Domain
View       <--> Response
Controller <--> Action

The two seem very similar. How are they different?

Typically, the View does not consider response headers, only the response body. Also typically, a Controller has more than one action method in it, and managing the different preconditions for these action methods carries its own overhead.

Model vs Domain

I can think of no significant differences here, other than that the Response does not interact with the Domain in meaningful ways. The Response might use Domain objects like entities and collections, but only for presentation purposes; it does not modify the Domain or feed information back to the Domain as described under MVC.

Controller vs Action

In common usage, most Controller classes in an MVC architecture contain several methods corresponding to different actions. Because these differing action methods reside in the same Controller, the Controller ends up needing additional wrapper logic to deal with each method properly, such as pre- and post-action hooks. A notable exception here is in micro-frameworks, where each Controller is an individual closure or invokable object, mapping more closely to a single Action (cf. Slim).

In an ADR architecture, a single Action is the main purpose of a class or closure. Multiple Actions would be represented by multiple classes.

The Action interacts with the Domain in the same way a Controller interacts with a Model, but does not interact with a View or template system. It sets data on the Response and hands over control to it.

View vs Response

In an MVC architecture, a Controller method will usually generate body content via a View (e.g. a Template View or a Two Step View). The Controller then injects the generated body content into the response. The Controller action method will manipulate the response directly to set any needed headers.

Some Controller action methods may present alternative content-types for the same domain data. Because these alternatives may not be consistent over all the different methods, this leads to the presentation logic being somewhat different in each method, each with its own preconditions.

In an ADR architecture, each Action has a separate corresponding Response. When the Action is done with the Domain, it delivers any needed Domain data to the Response and then hands off to the Response completely. The Response is entirely in charge of setting headers, picking content types, rendering a View for the body content, and so on.

Other MVC Pattern Alternatives

How does ADR compare to other MVC alternatives?

DCI (Data-Context-Interaction)

DCI is described as a complement to MVC, not a replacement for MVC. I think it is fair to call it a complement to ADR as well.

MVP (Model-View-Presenter)

MVP has been retired in favor of Supervising Controller and Passive View, neither of which seem to fit the ADR description very closely.

PAC (Presentation-Abstraction-Control)

From Wikipedia:

PAC is used as a hierarchical structure of agents, each consisting of a triad of presentation, abstraction and control parts. The agents (or triads) communicate with each other only through the control part of each triad. It also differs from MVC in that within each triad, it completely insulates the presentation (view in MVC) and the abstraction (model in MVC). This provides the option to separately multithread the model and view which can give the user experience of very short program start times, as the user interface (presentation) can be shown before the abstraction has fully initialized.

This does not seem to fit the description of ADR very well.

Model-View-ViewModel

MVVM seems more suited to desktop applications than web interactions. (Recall that ADR is specifically intended for web interactions.)

Examples of MVC vs ADR

MVC Starting Point

An MVC directory structure for a naive blogging system might look like the following. Note that the index and read views present an alternative JSON type, and the comments template is a “partial” that also presents an alternative JSON type.

controllers/
    BlogController.php # index(), create(), read(), update(), delete()
models/
    BlogModel.php
views/
    blog/
        index.html.php
        index.json.php
        create.html.php
        read.html.php
        read.json.php
        update.html.php
        delete.html.php
        _comments.html.php
        _comments.json.php

Here’s another type of MVC directory structure:

Blog/
    BlogController.php  # index(), create(), read(), update(), delete()
    BlogModel.php
    views/
        index.html.php
        index.json.php
        create.html.php
        read.html.php
        read.json.php
        update.html.php
        delete.html.php
        _comments.html.php
        _comments.json.php

A typical Controller class in MVC might looks something like the following. Note that there are multiple actions within the Controller class, and that the action method deals with the response headers.

<?php
use Framework\Controller;

class BlogController extends Controller
{
    public function create()
    {
        // is this a POST request?
        if ($this->request->isPost()) {

            // retain incoming data
            $data = $this->request->getPost('blog');

            // create a blog post instance
            $blog = $this->blog_model->newInstance($data);

            // is the new instance valid?
            if ($blog->isValid()) {
                // yes, save and redirect to editing
                $blog->save();
                $this->response->redirect('/blog/edit/{$blog->id}');
                return;
            } else {
                // no, show the "create" form with the blog instance
                $this->response->setContent($this->view->render(
                    'create.html.php',
                    array('blog' => $blog),
                ));
                return;
            }
        } else {
            // not a POST request, show the "create" form with defaults
            $this->response->setContent($this->view->render(
                'create.html.php',
                array('blog' => $this->blog_model->getDefault())
            ));
        }
    }

    public function index()
    {
        // ...
    }

    public function read($id)
    {
        // ...
    }

    public function update($id)
    {
        // ...
    }

    public function delete($id)
    {
        // ...
    }
}
?>

The create() logic could be reduced somewhat by moving even more of the model interactions into a Service Layer, but the point remains that the Controller typically sets the response headers and content.

ADR Comparison

In comparison, an ADR directory structure might instead look like this. Note how each Action has a corresponding Response.

Blog/
    Action/
        BlogIndexAction.php
        BlogCreateAction.php
        BlogReadAction.php
        BlogUpdateAction.php
        BlogDeleteAction.php
    Domain/
        # Model, Gateway, Mapper, Entity, Collection, Service, etc.
    Response/
        BlogIndexResponse.php
        BlogCreateResponse.php
        BlogReadResponse.php
        BlogUpdateResponse.php
        BlogDeleteResponse.php
        html/
            index.html.php
            create.html.php
            read.html.php
            update.html.php
            delete.html.php
            _comments.html.php
        json/
            index.json.php
            read.json.php
            _comments.json.php

The Action and Response class pair corresponding to the above Controller create() example might look like this:

<?php
use Framework\Action;

class BlogCreateAction extends Action
{
    public function __invoke()
    {
        // is this a POST request?
        if ($this->request->isPost()) {

            // yes, retain incoming data
            $data = $this->request->getPost('blog');

            // create a blog post instance
            $blog = $this->blog_model->newInstance($data);

            // is the new instance valid?
            if ($blog->isValid()) {
                $blog->save();
            }

        } else {
            // not a POST request, use default values
            $blog = $this->blog_model->getDefault();
        }

        // set data into the response
        $this->response->setData(array('blog' => $blog));
        $this->response->__invoke();
    }
}
?>
<?php
use Framework\Response;

class BlogCreateResponse extends Response
{
    public function __invoke()
    {
        // is there an ID on the blog instance?
        if ($this->data->blog->id) {
            // yes, which means it was saved already.
            // redirect to editing.
            $this->setRedirect('/blog/edit/{$blog->id}');
        } else {
            // no, which means it has not been saved yet.
            // show the creation form with the current response data.
            $this->setContent($this->view->render(
                'create.html.php',
                $this->data
            ));
        }
    }
}
?>

Again, we can see numerous refactoring opportunities here, especially in the domain model work. The point is that the Action does not perform any Response work at all. That work is handled entirely by the Response logic.

Benefits and Drawbacks

One benefit overall is that the pattern more closely describes the day-to-day work of web interactions. A request comes in and gets dispatched to an action; the action interacts with the domain, and then builds a response. The response work, including both headers and content, is cleanly separated from the action work.

One drawback is that we end up with more classes in the application. Not only does each Action go in its own class, each Response also goes in its own class.

This drawback may not be so terrible in the longer term. Invididual classes may lead cleaner or less-deep inheritance hierachies. It may also lead to better testability of the Action separate from the Response. These will play themselves out differently in different systems.

Some Rules For Good Naming

This Grumpy Programmer mailing-list essay got me thinking:

There is one point of contention I have with Laravel — some of the naming conventions that have causes numerous Twitter flame wars and blog posts. I speak, of course, about facades. … [T]he facade thing is a warning to remain vigilant and do your research into what everyone else calls something. Common vocabulary is critical when it comes time to solve difficult problems.

I completely agree with the emphasis on using a common vocabulary. One issue here is that naming things properly is very, very hard. It is one of the only two hard problems in programming.

Are there any rules (even rules-of-thumb) that can we use to make it easier to pick good names for the classes and concepts in our projects?

What’s In A Name?

Above all, a good name makes it obvious what we are describing. It provides clarity by itself without the need for further explanation.

However, because a word can be ambiguous, we have to pick the proper context for the use of a name. Using the right context when picking a name is paramount.

Unfortunately, in programming, there may be overlapping contexts. Giving a name to a domain class or concept can be especially difficult because of this overlap. Do we name an element for what the domain experts call it in their normal day-to-day work, or for its layer in the overall system, or for the pattern of its design?

Not A Novel Context

The first thing we have to remember, then, is that we are not writing a novel in English. Instead, we are writing software instructions. We are writing these instructions in something other than a normal human language. We are writing these instructions for a computer, and simultaneously writing them for human readers of that programming language.

With that in mind, I suggest the following order of priority for picking the proper context for a name:

  1. First is the vocabulary, common idioms, and core resources of the programming language itself. If the language itself, its core classes and methods, or the common expressions of its professional programmers associate particular vocabulary words with a concept, activity, or behavior, we should choose from among those words first when attempting to pick a name.

  2. Second is the vocabulary and common idioms related to previously identified patterns of software design. If there is a software design pattern that matches the concept we are trying to express, its name should be our next-best choice.

  3. Third is the vocabulary, idioms, jargon, and slang related to the domain. If there is no appropriate word from the programming language, and no relevant software design pattern, then falling back to the domain for the naming context is our next priority.

  4. The absolute last context should be words from normal everyday interactions. We use these words only after exhausting the other three contextual options. This is the least-appropriate context for picking a name.

This priority order is probably the opposite of what many would prefer. As human beings, we are more fluent and familiar with the vocabulary of our everyday writing and speech. It took many years of hard work to acquire that vocabulary in the first place, and we are unwilling to do additional hard work to acquire yet another vocabulary that applies more appropriately the context of programming. We would prefer to reuse the words we already know, instead of learning how to apply new words.

Even so, to be good at communicating the concepts of software programming to other programmers, it is incumbent upon us as professionals to expand our vocabulary. We must learn these new terms and their proper use. This is especially difficult with patterns of software development.

Patterns Are Defined By Behavior

When it comes to patterns, we have to remember that the patterns themselves pre-exist their names. The names were applied only after seeing the same patterns over and over again in many different programs. This means that it is the behavior of a construct that determines what its appropriate pattern-related name should be. If we write code like this …

<?php
class Foo
{
    public function newInstance($bar)
    {
        return new $bar;
    }
}
?>

… and we never mention the word “factory”, the code is still representative of the Factory pattern. A rose by any other name may smell as sweet, but if we call it a daisy then nobody will be able to guess that it has thorns. Similarly, a “factory” by any other name still creates and returns objects. Calling the above construct anything other than “factory” (or a factory-related name) removes clarity instead of providing it.

Picking The Closest Pattern

As a related issue, it’s not enough to look through pattern definitions and find one that is “close enough.” We must find the best one we can that matches the most parts of the concept we are trying to express in a name. This can be a lot of effort.

By analogy, we should not call a “motorcycle” a “bicycle” and expect to be understood fully. Yes, a “motorcycle” matches up with a “bicycle” in important ways: they both have two wheels, we steer and brake with our hands instead of our feet, we sit on a seat above the frame, and so on.

But for all their similarities, they are clearly different things. Better to call a motorcycle by its proper name so that we impart better understanding. Likewise, better to call something a Proxy instead of a Facade when appropriate.

Avoid Claiming A Special Context

When picking a context for a name, it is very tempting to define our own special context that lets us pick a name we prefer, perhaps for marketing or other non-technical reasons. We need to avoid this temptation.

Imagine if General Motors, in its marketing materials, called a “Kia” a “Maserati” and went on to describe its offerings in terms of its so-called Maserati. Such a description would make no sense in the wider world of automobile manufacture. Calling a “Kia” a “Maserati” while “in the context of GM” is symptomatic of the Humpty-Dumpty rationale:

“When I use a word,” Humpty Dumpty said, in a rather scornful tone, “it means just what I choose it to mean — neither more nor less.” “The question is,” said Alice, “whether you can make words mean so many different things.” “The question is,” said Humpty Dumpty, “which is to be master — that’s all.”

Claiming your own special context adds a layer of unnecessary obfuscation and cognitive friction. It removes clarity in naming.

Summary

In summary, I opine that these are the guidelines we need to keep in mind when picking names:

  • We are writing software instructions, not prose or poetry.

  • Pick from existing names that provide clarity within the appropriate context.

  • The order of priority for the appropriate context is: programming language, software patterns, domain terms, and finally everyday speech.

  • When using a pattern name, find the best match, not one that is merely close-enough.

  • Avoid claiming a special context for names so that you can make them mean what you want, instead of what they mean within a more widely shared context.


UPDATE: Some commenters from the Laravel community are being, shall we say, uncivil in their statements. Comments that are not civil, polite, respectful, and on-topic will be deleted out of hand. I reserve the right to further police comments as I see fit.

Submit To The Central Scrutinizer

(N.b.: I was unable to write this post without saying “ssscrrrrutinizer” out loud over and over. I blame my friend Ray Chavarie for inflicting Frank Zappa on me at an impressionable time in my life.)

After finishing Uncle Bob’s excellent Clean Code recently, I have been looking at my own code in Aura v2 even more critically. I started trying to apply more of the Clean Code principles to the different libraries, and thought I had done pretty well. But then I saw a scrutinizer.yml file in Luis Cordova’s Gush project, and I was curious about it.

I visited scrutinizer-ci.com to read up on the project, and man was I floored. Here is a service that will analyze your project on Github and assign it a quality grade that aligns really well with the Clean Code principles (among others). After you register a repository with Scrutinizer and perform the first analysis, you can fine-tune the process with a config file so that the Scrutinizer looks in the right directories for source code, gives you code coverage analysis, and so on.

For one of my first experiments with the Scrutinizer, I started with the Aura.Sql_Schema v2 package. I thought it would come out pretty well, but even after pointing the Scrutinizer in the right direction, it only scored an 8.61 or so. I guess that’s OK — but could we do better?

Using the Hot Spots page I was able to find the worst offenders in the classes and methods. Because we have 100% test coverage on all Aura code, it was a only matter of applying appropriate refactorings — the tests help to assure that changes don’t break anything. (The Scrutinizer will even suggest refactorings for you to apply.)

After the refactoring processes, the Scrutinizer reported a 9.46. You can see the Scrutinizer report for Aura.Sql_Schema here. There’s still room for improvement, but at least I know where the greatest improvement opportunities are.

Now that I’ve got a few days’ experience with Scrutinizer, I find it a very valuable tool. It’s very helpful as an objective assesment of code quality, so much so that I have added Scrutinizer badges to each Aura v2 package readme. You can see all the badges for all the packages on the v2 packages page.

Maybe the rest of the world knew about Scrutinizer before this, and I’m late to the game. I had not heard about it until recently, and now that I’m aware of it, I think it’s a great service for any developer concerned about code quality. Congratulations to @schmittjoh and everyone else involved in Scrutinizer. Very nicely done!

UPDATE: In response to a question elsewhere: yes, Scrutinizer is free for open-source projects.