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.

Aura.SqlQuery 2.0.0 Stable Release

Aura.SqlQuery provides provides a truly independent, fully decoupled package of query-building tools for PHP 5.3 and up. With it, you can use object-oriented techniques to create SELECT, INSERT, UPDATE, and DELETE queries. The package comes with a set of common base query objects, and provides specialized objects for MySQL, PostgreSQL, SQLite, and Microsoft SQL Server.

When we say “truly independent and fully decoupled” we really mean it. The SqlQuery package has no dependencies on any particular database connection system or abstraction layer. For example, you can build a SELECT query, then pass the finished query string to a PDO connection, a mysql connection, or through the database abstraction layer of your choice. This means the package is suitable for any framework or application that needs a query-building mechanism.

Via Aura.SqlQuery v2 Stable Release.

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.

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.

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

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.

First Aura v2 Beta Releases of Web_Project, Cli_Project, and Framework_Project

Earlier this week, we put the final touches on the “micro/macro” frameworks for v2 web projects and v2 command line projects. Although these had been delayed a bit while working out the Aura.Di v2 beta release, they both now have their first “Google beta” releases!

… The idea is that [Aura.Web_Project] starts as a very minimal system, with only router, dispatcher, request, and response functionality. But thanks to the Composer-assisted configuration system, it’s very easy to add whatever functionality you want, making the project as large or as small as you need. …

Aura.Cli_Project takes exactly the same approach, but for command-line applications. It consists of a “context” and standard I/O system (the equivalents of a request and response), along with a console and dispatcher. It uses the same configuration system as Web_Project, so you start with a very minimal system that grows only as you need it.

Each project is little more than a skeleton around a core “kernel” package. The Aura.Web_Kernel is what actually provides the glue to connect the underlying library packages together, as does the Aura.Cli_Kernel.

Keeping the kernel separate from the project means we can update the kernel without having to re-install a project.

via First v2 Beta Releases of Web_Project, Cli_Project, and Framework_Project.

Composer-Assisted Two-Stage Configuration in Aura

After a long period of consideration, research, and experiment, we have found a non-static solution for programmatic configuration through a DI container. It is part of a two-stage configuration process, implemented through a ContainerBuilder.

The two stages are “define” and “modify”:

  • In the “define” stage, the Config object defines constructor params, setter method values, and services. This is the equivalent of the previous single-stage Solar and Aura v1 configuration system.

  • The ContainerBuilder then locks the Container so that its definitions cannot be changed, and then begins the “modify” stage. In this second stage, we retrieve service objects from the Container and modify them programmatically.

So now, instead of each Aura package carrying a pair of define and modify includes in a subdirectory named for the config mode, we have a single class file for each config mode. The class file is in a subnamespace _Config under the package namespace. Here are two examples, one from the Aura.Web_Kernel package, and one from the Aura.Web_Project package.

Because they are classes, you can call other methods as needed, subclass or inherit, use traits, create instance properties and local variables for configuration logic, and so on. You could even call include in the methods if you wanted, keeping the class as a scaffold for much larger configuration files. This gives great flexibility to the confguration system.

To make sure the Aura project installation can find all the package config files, we use the {"extra": {"aura": { ... } } } elements of the composer.json in each package to provide a mapping from the config mode to the config class.

Read the whole article at Composer-Assisted Two-Stage Configuration.