A PSR-7 Web Router Implementation, and Bookdown Documentation

From the Aura blog:

Our first 3.x package is now available for review, a PSR-7 implementation of Aura.Router. It includes some feature upgrades such as custom rules and more powerful route definitions.

On a side note, the package documentation uses Bookdown for its documentation. You can see the generated documentation here. Bookdown allows us to keep documentation sources in each library repository. We can then collect them all into a single “book” on the Aura site using a bookdown.json file with remote “content” elements.

Read the rest at the Aura blog.

Aura 3 Plans

From the Aura blog:

  • The Past

    • Aura 1.x framework packages will see no new releases, and may be archived.

    • Aura 1.x library packages are near the end of active development; to prevent orphaning and end-of-life, ownership and authority over them they may be transferred to interested parties.

  • The Present

    • Aura 2.x packages that are currently stable will remain the center of development attention, with some modifications to Composer and PHPUnit support files, and with added testing on PHP 7.

    • Aura 2.x packages that are not currently stable will not see stable 2.x releases; they will become 3.x candidate packages.

  • The Future

    • Aura 3.x packages will target PHP 5.6, and additionally test on PHP 7.

    • Aura 3.x library packages will be allowed to depend on interface packages, though not other implementation packages.

    • Aura 3.x will not provide a framework under the Aura name, although the 2.x framework should be able to use 3.x components. Frameworks of Aura packages may be provided as separate projects.

    • Aura 3.x and later packages will have independent major version release cycles.

Read the entire post here.

Using Aura.Html with League\Plates

Aura has its own native PHP template package, Aura.View, a direct descendant of Savant and Solar_View, as well as a cousin to Zend_View.

The v1 Aura.View package used to include a helper system. Once we realized that there was no reason to tie the helper system directly to the view system, we released the helpers as a standalone Aura.Html package. This means the helpers can be used in any PHP presentation code, framework-based or otherwise.

As an example, let’s try integrating the helpers with Plates, a relative newcomer in the native PHP templating world. Plates allows you to register functions with its template engine, which means we can pull individual helpers out of Aura.Html and drop them into Plates, like so:

<?php
$plates = new League\Plates\Engine('/path/to/templates');
$helper = (new Aura\Html\HelperLocatorFactory())->newInstance();

$plates->registerFunction('anchor',     $helper->get('anchor'));
$plates->registerFunction('anchorRaw',  $helper->get('anchorRaw'));
$plates->registerFunction('base',       $helper->get('base'));
$plates->registerFunction('form',       $helper->get('form'));
$plates->registerFunction('img',        $helper->get('img'));
$plates->registerFunction('input',      $helper->get('input'));
$plates->registerFunction('label',      $helper->get('label'));
$plates->registerFunction('links',      $helper->get('links'));
$plates->registerFunction('metas',      $helper->get('metas'));
$plates->registerFunction('ol',         $helper->get('ol'));
$plates->registerFunction('scripts',    $helper->get('scripts'));
$plates->registerFunction('styles',     $helper->get('styles'));
$plates->registerFunction('tag',        $helper->get('tag'));
$plates->registerFunction('title',      $helper->get('title'));
$plates->registerFunction('ul',         $helper->get('ul'));
?>

Now you can use the tag helpers and form-building helpers from Aura.Html in your Plates templates. For example, if your Plates template looks like this …

<html>
<head>
<?= $this->title('My Title'); ?>
</head>
<body>
<p>Try out <?= $this->anchor(
    'https://github.com/auraphp/Aura.Html',
    'Aura.Html'
); ?>
with <?= $this->anchor(
    'http://platesphp.com',
    'Plates'
); ?> !</p>
</body>
</html>

… it will render to:

<html>
<head>
    <title>My Title</title>
</head>
<body>
<p>Try out <a href="https://github.com/auraphp/Aura.Html">Aura.Html</a>
with <a href="http://platesphp.com">Plates</a> !</p>
</body>
</html>

Try out Aura.Html today, and see how much you like it with your output system of choice. (We’re partial to Aura.View for that task, but then, we would be.)

UPDATE: As usual, Hari KT is ahead of the curve with his post on this same topic from a year ago: http://harikt.com/blog/2014/05/13/extending-plates-with-aura-html-helpers/.

UPDATE 2: Someone asked how easy it is to use Aura.Html with Aura.View. It’s 3-lines-easy: see https://github.com/auraphp/Aura.View#custom-helper-managers.

What’s The Difference Between Tightly-, Loosely-, and De-Coupled ?

In a tweetstorm that spun up late last week, Taylor Otwell produced the following commentary:

look guys I’m “decoupled” because this package doesn’t have composer dependencies!!! HAHAHAHA LOL

how many composer packages a given package has does NOT affect YOUR code’s decoupling.

that is a matter of programming to an interface, etc.

you people seriously do not understand decoupling. at all.

if you type hint AuraAnything that is a HARD, CONCRETE dependency. THAT is coupling.

IlluminateContracts are all interfaces. abstractions. not concretions. THAT’s decoupling.

IlluminateContractsViewFactory could be a Laravel view factory, could be an Aura one. That’s decoupling.

how many composer pkgs the IMPLEMENTOR needs is an implementation detail my consuming code need not care about

consuming code ONLY cares about programming to an interface for decoupling.

you [@philsturgeon] and brandon [savage] and paul [jones] don’t understand basic programming concepts like coupling

and think somehow coupling is tied to composer

Aura ships hard concretions = you are tightly coupled to Aura.

which should my consuming code give a shit if Aura is decoupled AMONGST ITSELF. Nobody gives a shit.

i only care if MY code is coupled to Aura.

and since Aura makes you depends on hard concretions, it promotes hard couplings.

I’m saying if you type-hint a class dependency, you are coupled to that implementation (cont)

regardless of that package’s internal dependencies

While some of Taylor’s rant is correct for as far as it goes, much of it glosses over important distinctions in subtle misdirection, and the remainder displays some misunderstandings. He is also flat wrong in his assertions of other peoples’ understanding of “basic programming terminology.” As such, I think his words demand a careful response for future reference.

First, I’m glad to see Taylor paying attention to the proper use of terminology in a software context. This is something he’s not always been great at in the past, and I encourage him here.

But I can’t quite tell if Taylor thinks the developers who use Aura believe their code is decoupled by virtue of using Aura. Or maybe it’s that the Aura marketing phrase “fully decoupled libraries” is the target of his ire. I infer allusions to both from his tweets, so I’ll attempt to address both possibilities. (Perhaps there is some other interpretation I have missed.)

It should be so obvious as to not require stating, but for the sake of explicitness: If your code has a dependency on classes in a particular thrid-party package, your code is tightly coupled to the code in that package. This is true for any classes in any library, framework, or other package code. So, if you believe that depending on an Aura library in your code makes your code “decoupled” then you are mistaken. As far as I know, I have never attempted to state or imply otherwise. I don’t think any Aura users have this misperception, but if so, consider this a corrective.

The fact that your code could be tightly coupled to another package does not mean that the other package is coupled to anything else. That is to say, the other package might have no couplings of any sort to any other code outside itself. The other package in that case is de-coupled.

The Aura library packages are designed with that kind of decoupling in mind. That is, no Aura library package depends on anything at all in any other Aura package. Each of the Aura libraries is thus fully decoupled from the others, and incidentally from any framework that is composed of them. (Note that the *_Kernel and *_Project packages are coupled to other packages; the decoupling principle applies only to the Aura library packages.)

But why would you care if a particular library package is itself decoupled from other packages? I assert that one reason (of many) you want libraries that are themselves decoupled is so that, if you have to swap one out in your own code, you only have to worry about the one library, not about all the dependent libraries that it is coupled to (and all the dependent libraries they are coupled to). Swapping out is still tedious: you will need to work through your code, change all the typehints from that library’s classes to those in another, and change all the injections that specify classes from the library. But at least it’s only the one library; the fact that the library is itself decoupled reduces the swapping-out work.

Taylor points out another level of coupling called “loose” coupling. This means that, instead of your code depending on a particular class, you instead depend on an interface. This couples you to the interface, but not to any particular implementation. If your code depends on interfaces, your code is loosely coupled to the implementations of those interfaces (although I don’t think this means you are de-coupled – there’s still some knowledge necessary for interactions).

Being loosely coupled is a good situation to be in compared to being tightly coupled. If you need to swap out an implementation of an interface, you won’t need to change your typehints (unless you swap to another set of interfaces). However, you will still need to change all your injections to the new implementation. Overall, being loosely coupled makes for less work when swapping out libraries.

How can you tell if a package is coupled to another package? Provided that composer.json is not lying, it’s easy enough to examine the “require” element to see if there are other packages listed there. If there are, then it seems likely that the package is coupled to whatever is required. You need to exercise a little judgment, though. If the required package contains only interfaces, then the coupling is “loose”. Otherwise, it is “tight”. If there are no other required packages at all, then the package has no coupling of any sort; it is fully decoupled from anything outside of it.

However, that’s only if you assume composer.json is not lying. To really discover the coupling of a particular package, you would need to examine its code. Any uses of interfaces defined outside the package indicates loose coupling, uses of classes defined outside the package indicates tight coupling, and no uses of interfaces or classes outside the package indicates full decoupling.

(Note that this discussion is of inter-package coupling. Even if the classes inside a package may still be coupled to each other, the package as a whole may still be decoupled from any other package.)

Having said all this, Taylor is trying out a “contracts” package that exposes the Laravel interfaces independently of the implementations. I think this is a neat idea. It’s the only truly new thing I’ve seen introduced to the PHP community by the Laravel codebase, and I think it is worthy of emulation.

Even so, if the “contracts” include anything besides interfaces, I think coupling to them might be defined as “tight”. I am thinking specifically of the Exception classes included in the “contracts” package. Although it may be fair to think that Exceptions are exempt from coupling rules, perhaps they would be better provided as interfaces to Exceptions, instead of classes proper. I will reserve my judgment on that for a later time.

First Aura 2.0 Stable Project Releases!

Exciting news! After a little over a year in the making, the Aura web and CLI project packages saw their first stable 2.0 releases this weekend. This is a major milestone for Aura, as it means not just the core libraries but also the frameworks built from them are now complete.

Because Aura takes a “libraries first, framework second” approach, the project packages had to wait for the following 2.0 stable releases of these core libraries yesterday:

  • Aura.Di (a dependency injection container)
  • Aura.Web (web request/response objects, and a response sender)

Once those were stable, it was not much trouble to promote the various kernels and project skeletons to stable as well:

(Unlike Aura library packages, which have no dependencies because they are completely decoupled from each other, the *_Kernel and *_Project packages do have dependencies, as they are compositions of library and other packages.)

Read more on the Aura blog, including other library releases: First 2.0 Stable Project Releases!.

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.)

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.

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.

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.