Refactoring To Action-Domain-Responder

The v1 version of the Aura framework includes a controller to handle web assets. The idea for this controller was that an Aura package might have images, scripts, and stylesheets that need to be publicly available, but in development you don’t necessarily want to copy them to a public document root every time you change them. The framework dispatches all “/asset/*” routes to the asset controller, which in turn reads the requested package asset from the file system and places its contents into the response body. Performance-wise this is horrible, so in a production environment one would use a build process to copy all the package assets to a static asset server, but in a local development environment it is a valuable convenience.

Take a look at the v1 version of the asset controller. It is constructed as a Page Controller within an MVC architecture. The default actionIndex() method receives an Aura package name in the form of Vendor.Package and a trailing file path indicating the asset to load from that package, then reads that file from the package and loads it into the response body.

That v1 version is a mess. The Controller handles the response-building entirely, and there is no Model separation at all. Let’s try refactoring it to an Action-Domain-Responder architecture and clean it up some for a v2 version. (For this example refactoring, we have Hari KT to thank for getting us started.)

  1. First, we need to extract the Domain portions of the code. After some discussion, we determined that the Domain here is the file-reading portions of the code. Instead of an Aura-specific Vendor.Package algorithm, we build a map of vendor/package keys that point to arbitrary directory prefixes (typically but not necessarily in a Composer installation). Finally, we figure that the caching elements would be better as part of a build process rather than on-the-fly, so we remove those caching elements; this reduces a significant portion of the Domain work.

  2. Next, we extract the response-building activity to a separate Responder class. The response-building work turns out to be relatively straightforward: if the asset has a path, that means the service found it, and we should present it as 200 OK; if not, we present it as 404 NOT FOUND.

  3. Last, we rename the Controller to an Action, and name its one-and-only “main” entry point as __invoke(). We modify the code in the Action to (1) invoke the Domain with the incoming request input, (2) place the Domain data into the Responder, and (3) return the Responder.

The end result is three classes instead of one: AssetService to handle Domain work, AssetResponder to handle the response presentation, and AssetAction to handle the incoming request and pass data from the Domain to the Responder.

Compared to the original Controller class, we clearly have more classes, and (aside from the fact that we removed the caching functionality) we likely have somewhat more code as well. But each class, and each method in each class, is relatively short, and the package overall is much more testable:

  • the AssetServiceTest is completely freed up from the Action and Responder (as it should have been in the original MVC code)

  • the AssetResponderTest does not need either the AssetAction or the AssetService, and is able to examine both the body and the headers of the response

  • the AssetActionTest does little more than to check if __invoke() returns a Responder, and see if the assigned data was retained

This separation has the effect of making the underlying components much more independent of each other and a lot easier to test. If we wanted to get really serious we would use interfaces and test doubles to fully isolate the classes.

Right now, some readers are looking at this example and wondering “How is this different from refactoring to a better-separated MVC?” The main difference in this particular example is that, in a webbish MVC setup, the work of setting response headers is generally handled in the Controller. Doing so does not give us as clean a Separated Presentation as we see under ADR. (Remember: on the web, the template is not the view; the response is the view.) In addition, to test the full response (i.e., the headers as well as the body) we would need to run the controller action code instead of just the separated presentation code.

Two final notes:

  • This example is not the only way to do Action-Domain-Responder. The Action could invoke the Responder directly, instead of allowing the calling code to invoke it. The Action might receive a ResponderFactory instead of a Responder object directly. The Responder might receive a ResponseFactory instead of a Response object directly. The Action might just be a closure in a micro-framework route. The point is that we now have a cleanly separated presentation, where the response-building work is completely extracted from the Action, and the Domain work is simiarly completely extracted from the

  • The Action returns a Responder and not a response object; this is predicated on how Aura.Dispatcher works. When the dispatcher invokes a Controller or Action, it checks the return value from that invocation; if that return value is itself invokable, the dispatcher does so recursively until the return result is no longer invokable. This means that the Dispatcher becomes responsible for invoking the Responder returned from the Action; the invoked Responder returns the completed response object.)

That is all; if you have comments on the Action-Domain-Responder paper, please leave them here or as issues out at Github.

Legacy Refactor Question: What About Singletons?

In my talk and my book on refactoring legacy PHP code, one of the early steps is to start removing globals and replace them with dependency injection (not a container, just injecting dependencies by hand.) I addressed the use of the global keyword and the $_GET (et al) superglobals, but I did not address singletons directly. I had a Reddit correspondent ask about singletons recently, and how to refactor away from them; I answered on Reddit, where you can read the full conversation.

A Round Of Aura 1.x Library Releases

Over the weekend we released updated versions of every 1.x library.

Most of these were “hygiene” releases, with docblock updates, extra tests, and minor bug fixes. However, the Router has two new methods to append and prepend route collections, and the Uri package adds support for schemeless URLs, ftp/ftps schemes, single label hosts, and an updated Public Suffix List.

Many thanks to everyone who made these releases possible, especially to Hari KT for insisting on the need for hygiene releases, and to Jeremy Kendall for his work on the Uri package.

A Round Of 1.x Releases.

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/!