Aura for PHP

First Aura 3.x Stable Releases

2015-12-01T00:00:00UTC

Today we released the first round of stable Aura 3.x packages:

Aura.Payload_Interface, an interface for domain payload implementations.
Aura.Payload, a domain payload implementation.
Aura.Router, a powerful, flexible web routing implemention for PSR-7 requests.

Since the announcement of the plans for Aura 3.x, we have made one small concession: the minimum PHP version is 5.5, instead of 5.6 as originally announced. Even so, all the 3.x packages are tested and operational on PHP 5.6, PHP 7, and HHVM.

A Web Router for PSR-7, with Bookdown Documentation

2015-04-21T00:00:00UTC

Last month I wrote about our plans for Aura 3.x. Those plans are coming to fruition a bit earlier than I anticipated. 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.

This is the first Aura library to use an external dependency. In fact, is uses two: one on the PSR-3 logger interface, and one on the proposed PSR-7 HTTP message interface. Please note that these are interface dependencies, and not implementation dependencies. Any package that implements those interfaces will fulfill the dependency requirement.

Unfortunately, because of the PSR-7 interface dependency, the Aura.Router package cannot go “stable” until PSR-7 itself does. I expect this will be in the next 30 days or so. In the mean time we may tag preliminary “Google Beta” releases.

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.

Aura 3 Plans

2015-03-27T00:00:00UTC

This is a really long post. Here’s a tl;dr:

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 on for details!

The Past: Aura 1.x

Aura 1.x is 4 years old at this point. Exploratory development began in late 2010, with the first commits under the Aura namespace in Jan 2011. The initial extraction of independent packages from Solar was a great success.

Aura 1.x Framework

The creation of a framework from those packages also worked well, for its time, but was imperfect. Among other things, Composer had not arrived on the scene when Aura 1.x started, so the 1.x framework only used Composer as an afterthought, and needed a special installer for the Aura 1.x library packages.

I recently released verson 1.0.1 of the 1.x framework, to incorporate some outstanding fixes, which gave me an excuse to do a review of the system. It is my assessment that the 1.x framework represents a necessary, but now obsolete, architectural step in Aura’s evolution. As such, the 1.x framework will not see new releases after 1.0.1.

New projects should use the 2.x systems: Aura.Web_Project, Aura.Cli_Project, or Aura.Framework_Project.

I have not yet decided what to do with the 1.x framework Github repositories; these include the Aura.Framework, Aura.Framework_Demo, and system packages. I may go so far as to archive (zip/tgz) those repositories and provide them as downloads. That will retain their Git histories, leave them publicly available, and simultaneously obscure them from casual discovery. (I am open to other suggestions here.)

Aura 1.x Libraries

Active development on Aura 1.x library packages has dwindled as the 2.x packages have become stable. Thus, new feature development on 1.x is no longer a priority for me personally, and I do not expect to give them significant attention in the future.

I am aware that there are still users of 1.x packages that have not transitioned to 2.x. To keep those packages from being orphaned and effectively “end-of-lifed”, I hereby invite anyone interested in maintaining them to contact me. The recipient will get full ownership and authority over the adopted package, with little to no further oversight from me.

I am also aware that there are outstanding issues for Aura.Input and Aura.Marshal. I may be able to resolve some of them in the near future, and release new 1.x versions, but I make no promises there. However, unresolved issues will become the responsibility of the new owners, should anyone choose to receive them.

Finally, an administrative note. Aura 1.x libraries had a develop and master branch. The master branch always represented the latest 1.x release tag for that library. To reduce confusion and standardize naming across all packages and version, I would like to remove the master branch, and rename the develop branch to develop-1, on all Aura packages. I am not sure yet what effect that will have on Composer, so that decision will need a little experimentation first.

The Present: Aura 2.x

Aura 2.x packages will continue to be the center of development attention. They will see some changes to their internal support file structures, but otherwise their guiding principles will remain the same.

Aura 2.x Testing Structure

Currently, library packages have a tests/unit/ directory and related PHPUnit files. Libraries that have a config/Common.php dependency injection config file also have a tests/container/ directory and a second second set of PHPUnit files; these are to test the DI wiring. In the near future, this will change so that:

PHPUnit files reside in the package root directory; and,
The unit and container tests will be combined within the tests/ diretory itself, not segregated into their own subdirectories.

That will address an issue noted by @Beanow in https://github.com/auraphp/Aura.Router/issues/66.

To support this, I need to modify the Composer files so that a new "require-dev": {"aura/di" : "~2.0"} element is present in those libraries that have config/Common.php DI config files. Additionally, they will need a new "autoload-dev" element pointing to the tests/ directory.

Those new additions, in turn, mean that for library packages with DI config files, you will need to have Composer installed to run the full test suite. 2-3 years ago that may have been too great an imposition, but I think Composer is so well-established now that it is not an unreasonable expectation. The tradeoff is that the DI configuration tests will automatically run for you, and incidentally on Travis-CI.

I expect to make similar changes in Bundle, Kernel, and Project packages, but since these already assume the presence of Composer, the difference will not be as dramatic.

Aura 2.x PHP Versions

The 2.x packages will continue to target the earliest possible PHP version for their operation. In most cases this remains PHP 5.3, and in some cases is PHP 5.4. We also test against all later versions of PHP, including 5.5 and 5.6, and against HHVM when we can.

In addition to these, I will add PHP 7 to the testing mix on all 2.x packages. Early reports from Ian Littman indicate that all 2.x packages are already PHP 7 compatible, so this is a adoption of his work.

Aura 2.x Release Commitments

2.x packages with existing stable releases will continue to be the center of development activity for the foreseeable future, including fixes and features.

However, 2.x packages with only beta releases will not see stable releases as 2.x packages. Instead, they will get a new develop-3 branch, and further development will continue on them as 3.x candidates. Their existing 2.x branches will remain in place but deprecated. (This affects only Aura.Auth.)

Further, packages with 2.x branches, but no releases, will also not see 2.x releases. They will likewise get develop-3 branches, and have their 2.x branches deprecated. Development will continue on them as 3.x candidates. (This affects Aura.Filter, Aura.Http, and Aura.SqlMapper_Bundle.)

The Future: Aura 3.x and Beyond

At last, the part you’re really interested in: future plans for Aura 3.x. This is where the next big set of changes will happen in Aura development.

Minimum PHP Version Bumped Up

PHP 5.6 will be the minimum version requirement for Aura 3.x packages. The packages will also be required to run on PHP 7 and HHVM to future-proof them as much as possible. I got this idea from Matthew Weier O’Phinney in his ZF3 presentation (or is it ZF 2.5? ;-).

Thus, Aura 3.x will not use PHP 7 features. Consider this a lesson-learned from Aura 1.x about getting on the latest-release bandwagon when we made 5.4 the minimum version too early. PHP 7 adoption will happen in 4.x and later releases.

The PHP 5.5 and 5.6 feature list, though, is not too shabby: yield generators, finally, foreach ($items as list(...)), ::class, constant expressions, variadic ...$args as function arguments, unpacking of ...$args arrays as arguments to functions, use function, use const, phpdbg, and the __debugInfo() magic method.

Dependency Restrictions Very Slightly Relaxed

In Aura 1.x, one design goal was complete independence and full decoupling of library packages, not only from a framework but also from each other. This meant that no library package had any dependencies at all. We continued that approach with library packages in Aura 2.x, while introducing Bundle, Kernel, and Project packages that did allow for dependencies.

In Aura 3.x, we are going relax the library dependency restriction in exactly one aspect. Library packages in Aura 3.x will be allowed to depend on interface packages only. This decision is motivated almost exclusively by the new PSR-7 “HTTP Messages” recommendation. PSR-7 presents a significant change in the PHP ecosystem, and Aura needs to be in a position to typehint against it; we can’t do that without a dependency on the PSR-7 interface.

This decision is not without drawbacks. For example, any change in an interface package means a break for the package that depends on it. It also means the package that depends on an interface package can never have a stability greater than that interface package. However, with care and attention, I think this will be a positive change.

Provision Of Interface Packages

With the allowance of interface package dependencies, Aura can then start splitting up its own offerings into interface and implementation packages. Not all packages will necessarily have an interface component, but where it makes sense, it can be now be afforded under the relaxed dependency restrictions.

I first saw the idea of separate implementation and interface packages in the Laravel world, although the Aura variation will be on a package-by-package basis (as vs collecting all interfaces into a single package). The interface packages will be named with a *_Interfaces suffix, similar to the way 2.x Bundles are named *_Bundle.

Ecosystem Dependency on Composer

In Aura 1.x and 2.x, each package provided some means of including the library source and test files independent of external autoloaders. Now that Composer is near ubiquitous, I think it’s no longer necessary to provide independent autoloading. Thus, 3.x packages will have an ecosystem dependency on Composer for autoloading of source and test classes. (This is similar to their ecosystem dependency on PHPUnit for testing.)

Change License From BSD to MIT

Aura 2.x and 1.x (and Solar before that) have used the various BSD licenses (New, 2-Clause, etc). Whereas it seems that the MIT license has become far more popular in the PHP world, Aura 3.x will move to the MIT license as well, to maximize license compatibility and minimize license-mixing confusion.

No More Framework Under The Aura Name

Aura 3.x will not provide a user-interface framework, whether for the web or for the command line, under the Aura name. I expect that 3.x packages will be able to work inside 2.x projects, provided that the PHP versions are recent enough.

This was a hard decision for me. It is motivated by my impression that user-interface frameworks are becoming less important, mostly because they are becoming easier to implement with mix-and-match component packages. It takes very little to string together a DI container or Service Locator, a Router, a Dispatcher, and an HTTP sender these days. Indeed, with the advent of a single-action controllers (a la Action-Domain-Responder and microframeworks), UI-independent Domain frameworks, and middleware-style approaches, a “framework” does not seem to be that big a deal any more.

While a user-interface framework is still necessary, it’s not going to be a focus of Aura 3.x development per se. I fully expect to build web and command-line frameworks using Aura 3.x packages, just not under the Aura banner. It is additionally my hope that by not claiming an “official” Aura framework, others will feel more inclined to build their own frameworks using Aura packages, in their own way and concentrating on their own preferences.

Removal of Library Config Files

As a result of not providing a framework with Aura 3.x, the config/ files in library packages intended to ease DI configuration at the Aura framework level will disappear. These were present only with libraries that had particularly involved object-creation steps.

In Aura 3.x, complex object creation and configuration will be handled by Factories, Builders, or perhaps even library-specific Containers. These objects will themselves be configurable, so that they can be manipulated by any DI container or Service Locator. (I expect that “provider” packages will spring up to ease integration into different framework ecosystems.)

Beyond 3.x; or, A Version Is Just A Number

With Aura 1.x and 2.x, I tried to keep the packages all under the same major version number. The version number did additional duty by indicating an expected package structure. With Aura 3.x, we are going to try to adhere more closely to the spirit of Semantic Versioning, where a major version number indicates only a backward compatibility break, and nothing else.

This means that there may be 4.x or 5.x releases in one package, while others stays at 3.x. The implication for PHP 7 adoption is that 4.x in one package may use PHP 7 features, while another package may not get them until 5.x.

This continues the Aura history of decoupling as much as possible from other packages. With this approach, the packages will not even be coupled in their major release cycles.

Conclusion

That is all for now. I am of course interested to hear comments, concerns, criticism, and feedback – leave them below!

PHP World Releases!

2014-11-11T00:00:00UTC

This release is to remind about the phpworld conference happening at Washington DC. If you are there Paul M Jones, the creator and lead on Aura, is giving talks on It Was Like That When I Got Here: Steps Toward Modernizing a Legacy Codebase and Action-Domain-Responder: A Web-Specific Refinement of MVC. Check out the schedule.

Releases

Many of the Aura libraries got quick releases. It was busy days that we couldn’t blog each one seprately. So here is a quick update on what is happening.

Aura.Accept

Aura.Accept as extracted from Aura.Web got stable release.

An example how you could make use of content-negotiation is shown below.

<?php
// assume the request indicates these Accept values (XML is best, then CSV,
// then anything else)
$_SERVER['HTTP_ACCEPT'] = 'application/xml;q=1.0,text/csv;q=0.5,*;q=0.1';

// create the accept factory
$accept_factory = new AcceptFactory($_SERVER);

// create the accept object
$accept = $accept_factory->newInstance();

// assume our application has `application/json` and `text/csv` available
// as media types, in order of highest-to-lowest preference for delivery
$available = array(
    'application/json',
    'text/csv',
);

// get the best match between what the request finds acceptable and what we
// have available; the result in this case is 'text/csv'
$media = $accept->negotiateMedia($available);
echo $media->getValue(); // text/csv

Consider looking into the docs for more information

Aura.Di

Aura.Di released 2.1.0 which incorporates functionality to optionally disable auto-resolution. By default it remains enabled, but this default may change in a future version. This is regarding the issue 68

Add Container::setAutoResolve(), Factory::setAutoResolve(), etc. to allow disabling of auto-resolution
When auto-resolution is disabled, Factory::newInstance() now throws Exception\MissingParam when a constructor param has not been defined
ContainerBuilder::newInstance() now takes a third param to enable/disable auto-resolution
AbstractContainerTest now allows you to enable/disable auto-resolve for the tests via a new getAutoResolve() method

Consider looking into the docs for more information

Aura.Auth

Aura.Auth released beta-2.

The PdoAdapter::buildSelectWhere() now honors the custom column name provided by the user.

<?php
$auth_factory = new \Aura\Auth\AuthFactory($_COOKIE);
$pdo = new \PDO(...);
$hash = new PasswordVerifier(PASSWORD_BCRYPT);
$cols = array('username', 'md5password');
$from = 'accounts';
$pdo_adapter = $auth_factory->newPdoAdapter($pdo, $hash, $cols, $from);

How to make use of OAuth Adapters is documented. Thanks to Frost

Before it is too late please give your feedback on remember me functionality.

Aura.Router

Aura.Router getting more awesome!

2.1.0 : Added Router::generateRaw() to generate routes with raw data.
2.1.1 : Fixed allow simplest possible match of a single Accept header type without a Q value.
2.2.0 : Allow easier specification of $values[‘action’] directly from RouteCollection::add*() by passing a third param as the action value.

<?php
$router->add(
    'say_hello',
    '/hello/{name}',
    function ($params) {
        // Do the needful escaping
        echo "Hello " . $params['name'];
    });

Aura.Project_Kernel

Aura.Project_Kernel now have Factory::newKernel() and Factory::newContainer() have an added param, $auto_resolve, to allow you enable/disable auto-resolution in the container.

Other Releases

Other libraries that got doc update, turn off auto-resolution in tests and other minor issues fixed are:

Framework documentation

Added Quick start tutorial without database connectivity for Version 2. The framework documentation has been updated. If you find something missing open an issue or send pull requests

First 2.0 Stable Project Releases!

2014-10-05T00:00:00UTC

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:

Aura.Project_Kernel (the kernel files for every Aura project type)
Aura.Cli_Kernel (the kernel files for CLI projects)
Aura.Web_Kernel (the kernel files for web projects)
Aura.Cli_Project (a skeleton CLI project)
Aura.Web_Project (a skeleton web project)
Aura.Framework_Project (a skeleton cli+web project)

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

These project releases means that you can now start a new, stable Aura project using Composer. For example, the following will create a myproject/ folder with an Aura installation ready-to-go for you:

composer create-project aura/web-project myproject

Other Releases

In related news, we released stable 2.0 versions of Aura.Autoload and Aura.Includer, since they have had no changes in several months. (These were initially thought to be core components for the project packages, but it turns out they were not needed.)

The Aura.Accept package saw its first beta release today as well. Aura.Accept was extracted from Aura.Web so that content-negotiation behavior could be used separately from the Aura.Web Request and Response objects, such as in a Responder or other presentation mechanism. As the behaviors have not changed much in the extraction, we expect this package to see a stable release relatively soon.

The Aura.Auth package also got its first beta release. There’s still some work to be done here, notably regarding a “remember me” feature, and perhaps some additional LDAP behaviors.

The Aura.Router package got bumped to 2.1.0 as it has a new method, generateRaw(), to generate routes with raw data.

Finally, we updated Aura.Html to 2.1.0 to reflect a change in the service names it presents through an Aura project DI container. If you’re using Aura.Html independent of an Aura.Di container builder, these changes should not affect you at all.

Conclusion

Thanks to the many contributors in the Aura community who made these releases possible!

A Round Of New Releases

2014-09-03T00:00:00UTC

Over the past 10 days or so, we’ve been working on getting out new releases of the v2 and v1 packages. Here’s the story.

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.

We have our first release of Aura.Session v2 as 2.0.0-beta1. You can see it at https://github.com/auraphp/Aura.Session.

Also, we have updated stable releases of these packages with some feature additions:

Finally, some of the v1 packages needed to have v2 config classes either added or fixed. As a result, we now have these new v1 package releases:

Aura.Filter 1.0.2
Aura.Input 1.1.2
Aura.Intl 1.1.1
Aura.Marshal 1.2.2
Aura.Signal 1.0.4

That’s all for now!

An Updated Preview Of Aura.Auth

2014-06-26T00:00:00UTC

A couple of weeks ago I started porting Solar_Auth to an Aura v2 package, 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:

a state-tracking object
services for login, logout, and resuming sessions
adapters for htpasswd and PDO backends
service integration idioms (including HTTP Authorization: Basic login integration)
native session management

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

Note that the library is purposely limited in scope. It does not do roles, groups, access control, or account management. You give it some credentials, it tells you if the credentials are valid or not, and starts/stops sessions.

As with all Aura libraries, the measurable code quality is very high. It has 100% test coverage, is fully decoupled from all other libraries, and scores very well on Scrutinizer-CI. It is PHP 5.3 compatible, although if you want to use the new and more-secure password_hash() functionality, you will need PHP 5.5 (or a userland implementation such as ircmaxell/password-compat.)

If you are interested in the project, try it out and get in your suggestions on what’s needed. We already have a TODO list, but there may be things we haven’t thought of. Now is the time to make your voice heard – and, of course, pull requests are always welcome for review.

Aura.SqlQuery v2 Stable Release

2014-06-09T00:00:00UTC

We released a stable version of Aura.Sql v2 a couple of months ago, and as of today its sister package Aura.SqlQuery is at 2.0.0 stable as well!

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.

For more information and examples, be sure to take a look at the Aura.SqlQuery README. Download the package and try it today!

A Round Of 1.x Releases

2014-06-02T00:00:00UTC

Even though we have begun a series of Aura v2 packages, the 1.x versions do not languish. 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.

We at Aura adhere to Semantic Versioning; none of these releases have any backwards-compatibility breaks, so you should be able to update-in-place without any problems. Note also that each of these packages is completely independent and fully decoupled, so you can download and use one library without adding any further dependencies.

Aura.View 2.0.0-beta2 Released!

2014-05-29T00:00:00UTC

We have added a new feature “sections” to Aura.View v2 and released it as 2.0.0-beta2.

This feature is due to the patient lobbying of Hari KT. He saw variations of it in Plates and Symfony, and figured it would be a nice bit of feature parity to add. He was right.

It also involves a small BC-breaking change. Instead of assigning the inner view content to a template variable, we now store that content internally and expose it via a getContent() method. So instead of echo $this->content_var_name to place the content in the layout, we now use echo $this->getContent().

Enjoy!

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

2014-05-15T00:00:00UTC

We have new v2 beta releases!

Aura.View

Aura.View 2.0.0-beta1 is a reduced implementation of the v1 View package. It is notably different from v1 in several ways:

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. (We bind closures to the View instance so you can use $this from inside the closure to reference data, helpers, and so on.)
The library no longer searches through directory stacks/hierarchies for templates. Those kinds of file-system scan turned out to be fine in most cases, but in high-performance situations it becomes a drag on performance. The search stacks have been replaced with a TemplateRegistry where you explicitly register templates by name. This involves more setup work but makes it easier to determine where the templates are coming from.
The library does not auto-escape data for output any more. Auto-escaping seemed like a good idea for v1 but it turned out to be more trouble than it was worth. In fact, there are no escapers included at all any more (see below for more about that).
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.

What? No escapers or helpers? Have no fear; they have not disappeared, they have only been moved into the Aura.Html package.

Aura.Html

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. As an example of the standalone nature of the Aura.Html helpers, Hari has shown how to integrate it with Plates from Jonathan Reinink.

And what a set of helpers, especially the form helpers! 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. (Incidentally, Aura.Input generates the recognized structure.)

In addition, the package 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. Place a use Aura\Html\Escaper as e statement at the top of your PHP-based template file, and you can issue …

e::h() to escape HTML;
e::a() to escape attributes, including arrays of attribute key-value pairs;
e::c() to escape CSS; and
e::j() to escape JavaScript.

(Normally in Aura we avoid static methods, but the verbosity tradeoff here was too good to ignore.)

Conclusion

If you already have an project and all you need is a PHP-based template system, or if you already have a view system and all you need is some form helpers, then Aura is for you! Each package is completely decoupled from the others, meaning you can download just what you need and not worry about inter-library dependencies. Try Aura.View and Aura.Html today!

First v2 Beta Releases of Web_Project, Cli_Project, and Framework_Project

2014-04-17T00:00:00UTC

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!

Projects

We have spoken before of Aura.Web_Project as a “micro/macro” framework. The idea is that it 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. Installation is as easy as issuing composer create-project -s beta aura/web-project.

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. Getting started is as just as easy: composer create-project -s beta aura/cli-project.

Finally, we have Aura.Framework_Project; it is a combination of both Web_Project and Cli_Project. That one installs just like the others: composer create-project -s beta aura/framework-project. The goal on the Framework_Project more extensive than with the other two; while they are more micro to begin with, the Framework_Project will eventually become more of a full-stack system.

N.b.: Unlike Aura library packages, which are fully decoupled and independent from all other packages, the *_Kernel and *_Project packages do have dependencies. This is because their purpose is to combine other packages together.

Kernels

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. The separation between kernel and project also makes it possible to combine or stack the kernel packages. For example, the web and CLI kernel packages depend on a the same underlying Project_Kernel to handle the common task of configuration and setup. Similarly, the Framework_Project uses both the web and CLI kernel packages together.

Conclusion

If you are the kind of developer who wants to keep dependencies to a minimum, but still wants a little bit of architecture to start with, then Aura fits the bill. Download individual library packages with no dependencies, or install a minimal project package and add only what you need. Try it out today!

Aura.Sql 2.0 Stable Released

2014-04-10T00:00:00UTC

Last week, we released Aura.Sql v2 stable. Install it via Composer using {"require": {"aura/sql": "2.*"}}, or download a package and read change notes on the releases page.

If you’re not already familiar with it, the Aura.Sql package primarily provides an ExtendedPdo object with convenience functions extended from PDO. This means your existing PDO-typehinted code can take an ExtendedPdo object directly. As with all other Aura libraries, it has 100% unit test coverage, and is completely decoupled from all other packages, having no additional dependencies.

Unfortunately, this stable release has a few BC breaks from the “Google beta” release before it:

Previously, the ExtendedPdo object itself would retain values to bind against the next query. After discussion with interested parties, notably Rasmus Schultz, I was convinced that it was too much of a departure from normal PDO semantics.

Thus, the collection of values for binding has been removed. The methods query(), exec(), and prepare() no longer take bound values directly. Instead,we have a new method perform() that acts like query() but takes an array of values to bind at query time. We also have a new method prepareWithValues() that prepares a statement and binds values at that time. Finally, the new method fetchAffected() acts like exec(), but with bind values passed at the time of calling (just like with the other fetch*() methods).

But we have a new feature as well thanks to Stan Lemon. If you have an existing PDO instance, you can pass it to the ExtendedPdo constructor to decorate the existing instance with the extended behaviors. This can help in in transitional situations.

Enjoy!

Composer-Assisted Two-Stage Configuration

2014-04-07T00:00:00UTC

One of the design choices for configuration in Solar, and later in the Aura v1 framework, was that all values were inteded to be passed at construction time. If you wanted to set up a router, for example, you would create an array structure to define all the routes, and then the DI container would pass that structure as a constructor param when creating the router object.

In a most situations, config via constructor param is perfectly reasonable. Unfortunately, there are some times where it’s not as practical as I would like. It can feel clumsy setting up these kinds of huge data structures, such as for a router system. We wanted to find a solution to these less frequent but still necessary setup situations, perhaps using a programmatic approach.

The problem is that programmatic setup of foundational components can itself be a little clunky. The solution I see most often for this is to use static methods on the target object; for example, Router::add() to map a new route. In Aura, static methods are a design approach that we consciously avoid. We want to keep good scope separation at all times, and make all dependencies explicit. Statics are not congruent with those goals.

Two-Stage Config

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.

Classes, Not Includes

We originally tried do this define-and-modify process with include files, as is usually the case with configuration approaches. With this approach, we needed two config files (define.php and modify.php) for each configuration mode. We also needed an Aura.Includer to scan the file system in predefined locations for the config file pairs for each installed package.

However, that include-oriented approach never felt quite right. A couple of weeks ago it occurred to me that we could use classes for the two-stage config operations. This would allow for autoloading, independent testing, a smaller number of files, and a host of other subtle quality improvements. This led to the creation of the Config class, which is now part of the Aura.Di v2 package.

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.

Composer Assistance

None of this is any good if the application cannot find and load the configuraiton logic. 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. As this example from Aura.Cli shows, we accomplish this in two parts:

Create a PSR-4 entry for the Aura\Cli\_Config namespace that maps to the package config/ directory, and
Create an entry for the config mode that maps to the Config class for that mode.

This is where the “extra” entry provided by Composer really shines. We can place critical project-level information in the composer.json for each package under the “extra” entry, namespaced for “aura”. This information can be structured any way we like.

We then inject the decoded JSON data from the project-level composer.json along with the decoded JSON data from vendor/composer/installed.json into our Project service. Note that the Project object does not read the Composer data itself; that data is injected at construction time.

Finally, we use getConfigClasses() to get back that project-level information from the object, and use them to load our ContainerBuilder.

Conclusion

With this two-stage configuration mechanism, using classes instead of includes, and using Composer to map the config modes the to the config classes, we have the benefits of both a define-only config system and a programmatic modification system. This gives us the best of both worlds, and helps us avoid resorting to static methods for configuration.

Aura.Marshal, A Database-less non-ORM

2014-02-17T00:00:00UTC

Today’s post is about Aura.Marshal, a database-independent tool that receives results from your data sources and marshals those result sets into domain model objects of your own design, preserving data relationships along the way.

It’s probably not correct to call Aura.Marshal an object-relational manager. With ORMs proper like Doctrine and Propel, the ORM issues queries for you using an embedded or preferred database library.

With Aura.Marshal, you use the data retrieval tools of your choice and write your own queries to retrieve data from a data source. You then load the result data into an entity type object, and the marshal automatically wires up entity and collection objects for you based on a relationship scheme you define for it.

The great benefit of this approach is that it completely decouples the in-memory object wiring from the act of doing the queries in the first place. The Marshal knows how to build and interrelate the objects, but it has no idea how to get the data for those objects in the first place. Without the query-building stuff, the Marshal package turns out to be pretty light, comparatively speaking (only about 900 non-comment lines of source code, plus about 1300 lines of tests).

Among other things, this means you can use any database abstraction layer of your choice (or no abstraction layer at all). Indeed, your data source can be anything at all, not just an SQL database. It could be CSV, XML, JSON, the results of an API call, a set of no-SQL documents, or any other format. As long as the results can be represented as an array, Aura.Marshal can receive them and wire them up into objects for you.

Because the Marshal does not issue queries on its own, it means a DBA can tune the data retrieval layer of your application to its most efficient use in plain old SQL if needed. Of course, one of the drawbacks here is that someone on the team actually needs to know how to use SQL (or another data retrieval system of choice). But for fine control over queries, as well as keeping good separation of concerns and minimizing the size of your dependency packages, Aura.Marshal is hard to beat.

If you like clean code, fully decoupled libraries, and truly independent packages, then the Aura project is for you. Download a single package and start using it in your project today, with no added dependencies. Also be sure to join the mailing list and check out the #auraphp IRC channel on Freenode!

Aura.Cli 2.0.0-beta1 Released

2014-01-11T00:00:00UTC

Starting this week’s “one release a day” series is the 2.0.0-beta1 release of Aura.Cli. You can download it directly or install via Composer and Packagist.

The Aura.Cli package provides the command-line equivalents of web request and response objects. The Context (request-equivalent) object allows insight into the $_ENV, $_SERVER, and $argv values, along with a Getopt object that lets you build and then parse flags and options passed at the command line. The Stdio (response-equivalent) object provides access to to the standard input/output/error streams.

As with other Aura libraries, the Aura.Cli has a very narrow focus. Its purpose is not to provide a base object for commands or a console for exeucting commands, but instead to provide tools for you to use in your own command objects and scripts. (Writing a standalone command script with Aura.Cli is pretty straightforward.)

If you like clean code, fully decoupled libraries, and truly independent packages, then the Aura project is for you. You can download a single package and start using it in your project today, with no added dependencies.

Be sure to join the mailing list and check out the #auraphp IRC channel on Freenode!

Aura.Sql_Schema 2.0.0-beta1 Released

2014-01-10T00:00:00UTC

Wrapping up this week’s “one release a day” series is the 2.0.0-beta1 release of Aura.Sql_Schema. You can download it directly or install via Composer and Packagist.

The Aura.Sql_Schema package contains PDO-based tools to read table and column information from a database. If you already use PDO, or if your database abstraction layer of choice uses PDO under the hood, you can feed that PDO object to the Schema object and start reading your table and column information. (Because it is typehinted to PDO, this means the Schema can use an Aura.Sql v2 ExtendedPdo object as well.) The package supports MySQL, PostgreSQL, SQLite, and Microsoft SQL Server.

Be sure to join the mailing list and check out the #auraphp IRC channel on Freenode!

Aura.Web 2.0.0-beta1 Released

2014-01-09T00:00:00UTC

Our “one release a day” series continues with the 2.0.0-beta1 release of Aura.Web. You can download it directly or install via Composer and Packagist.

Whereas the v1 package included controllers, renderers, and other functionality, the v2 package provides only Request and Response objects. These objects are independent of any particular controller system, and independent of any specific HTTP delivery mechanism, which means they can be used in any new or existing codebase without introducing other dependencies. You can read more about the distillation of these concerns into separate packages here.

As a side note, you can see from the timing of these recent releases that Aura libraries are completely independent from each other. There’s no subtree-split or extract-and-build-for-release processing; each library is completely contained in its own repository, making individual releases through our admin script a trivial matter.

Be sure to join the mailing list and check out the #auraphp IRC channel on Freenode!

Aura.Router 2.0.0-beta1 Released

2014-01-08T00:00:00UTC

Continuing our string of library package releases, today we have the 2.0.0-beta1 release of Aura.Router. Given a URL path and a copy of $_SERVER, it will extract path-info and $_SERVER values for a specific route. You can download it directly or install via Composer and Packagist.

The Aura.Router package does not provide a dispatching mechanism. Your application is expected to take the information provided by the matching route and dispatch to a controller on its own. You might do this with Aura.Dispatcher or with some other system of your own devising.

In addition to all the standard stuff like adding routes and generating links, Aura.Router has some added conveniences:

Nice-looking “optional” params. To specify optional params, use a notation like {/year,month,day} in the path. Optional params are sequentially optional. This means that, in the example, you cannot have a “day” without a “month”, and you cannot have a “month” without a “year”. If you generate a link with optional params, the params will be filled in if they are present in the data for the link.
Attaching route groups. You can add a series of routes all at once under a single “mount point” in your application via a closure.
Attaching REST resource routes. The router can attach a series of REST resource routes for you with the attachResource() method. One call to that method with a resource name and base path will add named browse, read, edit, add, delete, create, update, and replace routes for you under that base path. Don’t like the defaults on those? Set your own resource attachment callback with setResourceCallback().

Be sure to join the mailing list and check out the #auraphp IRC channel on Freenode!

Aura.Sql_Query 2.0.0-beta1 Released

2014-01-07T00:00:00UTC

We’re happy to announce the 2.0.0-beta1 release of Aura.Sql_Query, a database-connection-independent query builder. You can download it directly or install via Composer and Packagist.

This is one of the packages that was extracted from the prior Aura.Sql v1 package. There was some demand for keeping the database connection portions separate from the query builder (and other) portions, thus the splitting-up of the original v1 package.

What’s interesting (to me anyway) is that originally, I didn’t think it would be possible to separate the two. A query builder seemed inextricable from a query connection. But it turned out to be possible, and the separation is pretty clean. Check out the README for examples.

Be sure to join the mailing list and check out the #auraphp IRC channel on Freenode!

Version 2 Beta Releases | Includer, Autoload, Sql, Dispatcher

2014-01-06T00:00:00UTC

In addition to the Aura.Autoload v2 “Google Beta” release from last week, we have been releasing v2 beta versions of other packages as well:

Aura.Includer v2 on Wed, 01 Jan 2014
Aura.Autoload v2 on Thu, 02 Jan 2014
Aura.Sql v2 on Fri, 03 Jan 2014
Aura.Dispatcher v2 on Mon, 06 Jan 2014

Hey, that looks like a pattern: one release per weekday of the new year. Who knows what tomorrow will bring? Regardless, you can see continuing updates on our v2 packages page.

The new Github releases API has been a real blessing here. Our release2 admin script uses it to make the release directly from whatever branch we happen to be on at the time of release. Because each Aura library package is completely self-contained, the release tool can run the tests, check composer.json, etc. very easily before it makes the release. (Non-library packages, which do have dependencies, have an additional composer install step before the tests run.)

Happy belated New Year to all, and many thanks to the Aura contributors who have made these releases possible!

First PSR-4 Autoloader Released | Aura.Autoload 2.0.0-beta1

2014-01-03T00:00:00UTC

I suppose it makes sense that since the the main author behind the PSR-4 Autoloader recommendation is also the lead on the Aura project, that Aura would have the first PSR-4 implementation. You can download it here …

https://github.com/auraphp/Aura.Autoload/releases/tag/2.0.0-beta1

and you can find the README here (or in the download, of course):

https://github.com/auraphp/Aura.Autoload/tree/2.x

I expect Composer will have support for PSR-4 soon as well.

UPDATE: Well that didn’t take long: PSR-4 autoloading support in Composer

Which is Lighter, Silex or Aura.Web_Project?

2013-12-23T00:00:00UTC

At least one commenter at Reddit pointed to this Silex article and used it as their basis for evaluating my claim that Aura.Web_Project is lighter than Silex. Others had similar sentiments.

Too many people, including the Silex article author, use absolute terms like “light” and “heavy” and “bloated”, instead of relative terms like “lighter” and “heavier” and “more bloated” and “less bloated”, to describe software. Any time someone uses an absolute term like that, you need to ask: “Compared to what?” Always remember that there is no such thing as “bloated” or “heavy” or “light”; there is only “heavier” or “lighter” or “more bloated” or “less bloated” in comparison to something else.

I don’t know if the measurements in that article are valid or useful for defining “what makes a microframework” but they do provide a basis for comparison. I understand that some people think “measuring (size

lines-of-code

number-of-classes) is stupid and it doesn’t matter!” Maybe it is, maybe it’s not. The author of the article seemed to think it was worthwhile to mention those numbers in relation to Silex, whether or not he thought they “mattered.”

So, let’s go with that article and use its approach to make a comparison between Silex and Aura.Web_Project to see if my earlier claim, using the terms and measurements outlined by the Silex post author, is accurate.

Methodology

The Silex article does not define its measurement methodology as well as I would like. There are no steps listed so his results can be replicated, or so the process can be applied to other systems. This means I had to do a little guessing to figure out the author’s process. I came up with the following:

Install the system in question and remove its tests.
Modify the index.php bootstrap script to show the classes actually used in a dynamic dispatch.
Run du to check disk usage.
Run cloc to count the non-comment non-blank lines of code (NCLOC) in the entire system.
Invoke the index.php bootstrap script to see a list of the classes actually used in a “standard request”.
Given that list of classes, run cloc to count the non-comment non-blank lines of code (NCLOC) in the class files that are actually used in a “standard request”.

The term “standard request” is from the Silex post. I don’t know what the author means by that, so in this article it’s a bare-bones invocation of the framework, a “Hello World” call that tells you the dynamic dispatch has been completed.

In order for you to see exactly what I did and what the the results were, here are links to the script and the output. You can run the script yourself and see the results on your own system. If you notice anything wrong with the script or its output, please let me know so I can fix it and correct this article and its conclusions.

Measurements and Comparisons

As you can see from the above script, we are comparing the bare-bones Silex 1.1.2 installation without any providers to a bare-bones Aura.Web_Project as installed via composer create-project.

I list the following measurements only because the original Silex article uses them. There are some measurement differences from the original article; I am willing to ascribe the differences to changes in the Silex codebase since that time.

Total Package Dependencies

Silex: 7 output, not including itself
Aura.Web_Project: 9 output

Aura has two more package dependencies than Silex. Aura is minus an event handling system, but adds an Includer for reading config files, a Project_Kernel as the foundation for the Web_Kernel, and Monolog.

Total Disk Usage

Silex: 2.6M output, althought original article states 3.5M
Aura.Web_Project: 1.2M output

In terms of bytes-on-disk, even with two more package dependencies, Aura.Web_Project is less than half the size of Silex.

Total Non-Comment Lines Of PHP Code

Silex: 23327 output
Aura.Web_Project: 7465 output

Even with two more package dependencies, Aura.Web_Project has 1/3 the NCLOC than Silex.

Total Class Count

The class-counting command is here: https://gist.github.com/pmjones/8074310#file-gistfile1-sh-L97 and includes only classes and abstract classes, not interfaces or traits.

Silex: 311 output
Aura.Web_Project: 148 output

Even with two more dependencies, Aura.Web_Project has 1/2 the total class count of Silex.

“Actual Usage” Class Count

This is determined by doing an array_diff() between get_declared_classes() before and after the framework is invoked via a web server. It includes only classes and abstract classes, not interfaces or traits.

Silex: 45 output; the original article claimed a “standard request” in Silex uses 50 classes, but the author did not state what a “standard request” was.
Aura.Web_Project: 53 output

In a bare-bones “hello world” that invokes only the dynamic dispatch cycle, Aura.Web_Project uses eight more classes (i.e., almost 1/5 more) than Silex.

Take a look at the actual class lists linked above. Note that Aura splits the request object into 21 (!) classes, and the response object into 7, for a total of 28 classes related to request and response handling. In Silex 1.1.2, I see only 8 request/response classes from Symfony HttpFoundation. This means that similar functionality has been split across more classes in Aura.Web_Project.

“Actual Usage” Non-Comment Lines Of PHP Code

Silex: 4388 output; The original article stated a total of 4018
Aura.Web_Project: 3555 output

Even though Aura.Web_Project uses eight more classes, its NCLOC count is only 81% that of Silex (i.e., almost 1/5 smaller).

Minimal Interface

At the end of the original article, the author states …

For the most part you will only ever deal with the following types:

Silex\Application

Silex\Controller

Silex\Route

Symfony\Component\HttFoundation\Request

Symfony\Component\HttFoundation\Response

Pimple

…

Minimal interface > minimal lines of code.

Silex is quite lightweight.

The entire public API consists of 5 classes.

(The article summary says 5 classes, but there are 6 classes in that list. Because Silex\Application extends Pimple I think it’s fair for the author not to count Pimple separately there.)

For Aura.Web_Project, “for the most part” there are only 4:

Aura\Di
Aura\Router
Aura\Web\Request
Aura\Web\Response

Conclusion

Does all this mean it is true that Aura.Web_Project is lighter than Silex? It depends on how you measure:

If you measure by the number of package dependencies, disregarding how similar functionality is split up between packages, then Silex is lighter.
If you measure by the total disk usage, Aura.Web_Project is lighter.
If you measure by the total NCLOC, Aura.Web_Project is lighter.
If you measure by the total class count, Aura.Web_Project is lighter.
If you measure by the acutual-usage class count, disregarding how similar functionality is split up among classes, then Silex is lighter.
If you measure by the actual-usage NCLOC, Aura.Web_Project is lighter.
If you measure by how many classes “for the most part” are in the public API, Aura.Web_Project is lighter.

In 5 of the 7 measures put forth by the original Silex article, Aura.Web_Project is the lighter of the two. The original author’s claim that “Silex is quite lightweight” might be true in some other way, but is it not as “lightweight” as Aura.Web_Project according to the measures he puts forth.

A Peek At Aura v2 -- Aura.Web_Project, The Micro/Macro Web Framework

2013-12-12T00:00:00UTC

UPDATE (2014-07-17): The configuration mechanism described in this post has been superseded by later development; see Composer-Assisted Two-Stage Configuration for more.

(In this series, we have been discussing the improvements over Aura v1 that are being incorporated into v2.)

Lighter than Silex, and slimmer than Slim, the Aura.Web_Project package is a minimalist web-specific project framework that starts out small and grows only as you need it.

By “minimal” we mean very minimal. The project package provides only a dependency injection container, a configuration system, a router, a dispatcher, a pair of request and response objects, and a Monolog instance for logging.

This minimal implementation should not be taken as “restrictive”:

The DI container, coupled with the project kernel’s two-stage configuration, allows a wide range of programmatic service definitions. This means no more static calls to configure services; edit the modify stage config files, pull a service out of the container, and operate on it directly.
You can add any library you want into the project, not just Aura libraries, through Composer and the DI container. This means the bundle/plugin universe is made up of anything written in PHP, not just Aura-specific plugins.
As noted in earlier articles in this series, the router and dispatcher are completely separated from each other, and are built with iterative refactoring in mind. This means you can start with micro-framework-like closure controllers, and work your way into more complex controller objects of your own design.

Projects? Kernels? Dependencies?

It had to happen at some point. Unlike Aura library packages, the project and associated kernel packages have dependencies. This is something we can’t get around; the idea behind Aura has always been to build its framework out of the independent library packages, but of course that means the framework itself is not independent of the libraries.

(The Aura.*_Project packages are system skeletons, providing a directory structure for the proejct. The Aura.*_Kernel packages bring together the libraries necessary for the project skeleton.)

Getting Started

You can start a new Aura.Web_Project via Composer in a {$PROJECT_PATH} of your choosing:

composer create-project --stability=dev aura/web-project {$PROJECT_PATH}

This will create the project skeleton and install all of the necessary library packages.

Once you have installed the project, start the built-in PHP server inside the new project web directory:

cd {$PROJECT_PATH}
php -S localhost:8000 -t web/

When you browse to http://localhost:8000 you should see “Hello World!” as the output.

Controllers: Micro/Macro?

When we say “micro/macro”, we mean that the system starts out as a the most micro of micro-frameworks, but is built with the idea that eventually you may want to refactor your architecture to a full-stack type of system.

Micro Controller

For example, you can start by embedding your controller logic directly in the router system …

<?php
/**
 * {$PROJECT_PATH}/config/default/modify/router.php
 */
$request  = $di->get('web_request');
$response = $di->get('web_response');
$router->add('blog.read', '/blog/read/{id}')
    ->addValues(array(
        'controller' => function ($id) use ($request, $response) {
            $content = "Reading blog post $id";
            $response->content->set(htmlspecialchars(
                $content, ENT_QUOTES|ENT_SUBSTITUTE, 'UTF-8'
            ));
        }
    ));
?>

Macro Controller

You can then migrate that to a more full-stack system (or you can start with a full stack style in the first place). This is more complex but is much more powerful, maintainable, and testable in the long run.

First, define a controller class and place it in the project src/ directory.

<?php
/**
 * {$PROJECT_PATH}/src/App/Controllers/BlogController.php
 */
namespace App\Controllers;

use Aura\Web\Request;
use Aura\Web\Response;

class BlogController
{
    public function __construct(Request $request, Response $response)
    {
        $this->request = $request;
        $this->response = $response;
    }

    public function read($id)
    {
        $content = "Reading blog post $id";
        $this->response->content->set(htmlspecialchars(
            $content, ENT_QUOTES|ENT_SUBSTITUTE, 'UTF-8'
        ));
    }
}
?>

(Note that you don’t need to extend a base controller here. The Aura.Web_Project package does not force any specific controller methodology on you. Of course, if you want to, you can create your own base controllers and extend them.)

Next, tell the project how to build the BlogController through the DI system. Edit the project config/default/define.php config file to tell the DI system to pass Request and Response objects to the constructor.

<?php
/**
 * {$PROJECT_PATH}/config/default/define.php
 */
$di->params['App\Controllers\BlogController'] = array(
    'request' => $di->lazyGet('web_request'),
    'response' => $di->lazyGet('web_response'),
);
?>

After that, put the App\Controllers\BlogController object in the dispatcher under the name blog as a lazy-loaded instantiation …

<?php
/**
 * {$PROJECT_PATH}/config/default/modify/dispatcher.php
 */
$dispatcher->setObject('blog', $di->lazyNew('App\Controllers\BlogController'));
?>

… and finally, point the router to the blog controller object and its its read action:

<?php
/**
 * {$PROJECT_PATH}/config/default/modify/dispatcher.php
 */
$router->add('blog.read', '/blog/read/{id}')
    ->addValues(array(
        'controller' => 'blog',
        'action' => 'read',
    ));
?>

Configuration?

As with the Aura v1, configuration files are located in {$PROJECT_PATH}/config directory. Previously, they were single files, labeled for the config mode. In Aura v2, config files are organized into subdirectories by config mode. (The config mode is still stored in the _mode file in the config directory.)

Whereas Aura v1 projects used a single-stage config system, loading up the individual config files to define params, setters, and services, Aura v2 projects use a two-stage configuration system:

First, all define.php files are included from the packages and the project; these define constructor parameters, setter methods, and shared services through the DI container.
After that, the DI container is locked, and all modify.php files are included; these are for retrieving services from the DI container for programmatic modification.

(The default mode directory is always loaded; if the mode is something other than default then the files in that directory will be loaded after default.)

This two-stage process provides a very powerful system for configuring any and all PHP libraries, especially those that have been registered as services in the DI container. However, this power comes with some level of complexity; the rules are simple, but they lead to complex combinations and effects. As such, will write about the configuration system in specific at a later time.

Adding Functionality

Adding new functionality is as easy as modifying the project composer.json file, doing composer update, and then changing your config files to build the new library objects properly. If you are adding an Aura library, the system knows enough to configure it automatically via the library package’s config/ directory, but any reasonably well-structured PHP library can be included and configured.

Conclusion

The point of Aura.Web_Project is to provide an absolute minimal framework for building web apps in a way that promotes separation of concerns along with a refactorable architecture. The DI container and two-stage configuration system are the key components here, with the fully-separated router and dispatcher layered on top of them.

A Peek At Aura v2 -- Aura.Router

2013-11-18T00:00:00UTC

Lately, we’ve been going over the migration of v2 packages from v1. Today, I’ll talk about the updated Aura.Router v2 package. While not an example of extracting a new package from an existing one, it has a couple of features that other routers don’t currently have, in addition to being truly independent and completely decoupled from any other package.

(This post describes only some of the features of the router; please visit the Aura.Router v2 package page for full information. Also, unlike v1, the v2 package is PHP 5.3 compatible!)

Only Routing, No Dispatching

Anyone using a framework system built in the past 5 years or so should already be familiar with routers. A router takes the incoming URL path, along with other optional data, and extracts a series of values that determine what controller and action should be executed, along with the parameters to send along to the controller and action.

Most routing systems combine the “routing” task with the “dispatch” task. That is, they both extract the parameters and pick the controller/action. Aura.Router v2, because of its truly independent nature, only does routing. It turns out that dispatching is something that can be independent of routing, and so we have a separate Aura.Dispatcher package to handle that (although you can use any dispatching system you like).

The Basics

Aura.Router v2 has the basic features one expects: map a path to a route, define token regexes, etc.

<?php
// add a basic route with name, path, token regexes, and default values
$router->add('blog.read', '/blog/read/{id}{format}')
    ->addTokens(array(
        'id' => '\d+',
        'format' => '(\.\w+)?'
    ))
    ->addValues(array(
        'controller' => 'Blog',
        'action' => 'read',
    ));

// use addGet(), addPost(), etc. to limit the matching HTTP method.
// use setSecure() to limit to secure connections.
?>

Because Aura.Router v2 is completely decoupled, you have to feed it the incoming URL path and server information when doing matching (it does not make assumptions about the execution environment):

<?php
// get the incoming request URL path
$path = parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH);

// get the route based on the path and server
$route = $router->match($path, $_SERVER);
?>

If there is a match, the $route variable will be a Route object (otherwise false). You can then dispatch to the controller and action of your choice by getting the $route->params; the following is naive but works just fine when autoloading is set up:

<?php
// get the route params
$params = $route->params;

// what class and method should we dispatch to?
$class = "App\Controllers\{$params['controller']}Controller";
$method = $params['action'] . 'Action';

// with the above 'blog.read' route, this will execute
// \App\Controllers\BlogController::readAction()
// and get back the result
$controller = new $class;
$result = $controller->$method($params);
?>

If you’re looking for an independent dispatching system with a little more power and flexibility, checkout Aura.Dispatcher.

Routing By Server Values

Aura.Router v2 allows you to examine the $_SERVER values and pick a route based on them using the addServer() method. For example, if you want to match routes based on the HTTP_ACCEPT value …

<?php
$router->addRoute('json_only', '/accept/json/{id}')
    ->addServer(array(
        // must be of quality *, 1.0, or 0.1-0.9
        'HTTP_ACCEPT' => 'application/json(;q=(\*|1\.0|[0\.[1-9]]))?'
    ));
?>

In that naive example, there must be a $_SERVER['HTTP_ACCEPT'] string that matches the given regex for the route to match. The matching HTTP_ACCEPT portion will be placed in the $route->params for you to use as you wish.

Sequentially Optional Params

Sometimes we need a params in the route path to be sequentially optional. The classic example is a blog archive organized by year, month, and day. We don’t want to have to write three routes, one for /{year}, /{year}/{month}, and /{year}/{month}/{day}, each with repeated information about the route.

In Aura.Router v2, there is a special notation similar to URI Templates that indicates sequentially optional params:

<?php
$router->add('blog.archive', '/blog/archive{/year,month,day}')
    ->addTokens(array(
        'year'  => '\d{4}',
        'month' => '\d{2}',
        'day'   => '\d{2}'
    ))
    ->addValues(array(
        'controller' => 'blog',
        'action' => 'archive',
        'year' => null,
        'month' => null,
        'day' => null,
    ));
?>

With that, the following routes will all match the ‘archive’ route, and will set the appropriate values:

/blog/archive
/blog/archive/1979
/blog/archive/1979/11
/blog/archive/1979/11/07

Incidentally, this means that the commonly used controller/action/id catchall route is easy to implement with defaults in place:

<?php
$router->add('catchall', '{/controller,action,id}')
    ->addValues(array(
        'controller' => 'default',
        'action' => 'index',
        'id' => null,
    ));
?>

That means / will have params indicating the default controller index action, /foo will indicate the foo controller index action, /foo/bar will indicate the foo controller bar action, and /foo/bar/42 will indicate the foo controller bar action with id of 42.

Attaching Route Groups

Aura.Router v2 is different from v1 in how it attaches what are variously called sub-routes or route groups. Previously, we used a descriptor array, but in practice that turned out to be a little unwieldly. The new version uses a callable to allow you attach route groups programmatically:

<?php
// attach routes to the '/blog' path prefix, and prefix all names with 'blog.'
$router->attach('blog', '/blog', function ($router) {
    // blog.browse at /blog
    $router->add('browse', '');
    // blog.read at /blog/read/{id}{format}
    $router->add('read', '/{id}{format}', array(
        ->addTokens(array(
            'id' => '\d+',
            'format' => '(\.\w+)?'
        ));
?>

See a longer example here.

As a side note, the router will automatically add default controller and action values for you here. The controller value is the route name prefix, and the action value is the sub-route name. Of course, these can be overridden by path params or your own default values.

Attaching REST Routes

As a consequence of using a closure to add route groups, we can now add REST resource routes in a single call to attachResource():

<?php
$router->attachResource('blog', '/blog');
?>

This will add seven REST routes with appropriate names, paths, HTTP methods, and token regexes; you can see the list here.

If you decide those routes are not to your liking, you can override the default behavior by using setResourceCallable() to pass callable of your own to create resource routes:

<?php
$router->setResourceCallable(function ($router) {
    $router->addPost('create', '/{id}');
    $router->addGet('read', '/{id}');
    $router->addPatch('update', '/{id}');
    $router->addDelete('delete', '/{id}');
});
?>

That example will cause four CRUD routes to be added when you call attachResource().

Conclusion

The Aura.Router v2 library retains the strengths of the v1 offering while adding convenience and power, all in a completely decoupled package with no other dependencies. It keeps a separation between routing and dispatching, allowing you to drop it into any system you like and use any dispatching mechanism of your own choice.

A Peek At Aura v2 -- Aura.Web

2013-11-11T00:00:00UTC

In the lessons learned post a few weeks ago, I wrote about how Aura was born of the idea that we could extract independent decoupled packages from Solar, and how in doing so, we discovered that some of those extracted packages themsleves could be further split into independent pieces.

The last example of this was how we extracted Aura.Dispatcher from three separate packages. Today, I’m going to talk about how the Aura.Web v2 package has been slimmed down as a result of Aura.Dispatcher being created. (Incidentally, Aura.Web v2 is also PHP 5.3 compatible!)

Aura.Web, version 1

Aura.Web v1 took the parts of Solar related to web controllers and combined them into a single independent package. The v1 package contains …

a ControllerInterface along with an AbstractPage controller object to provide a base controller for web actions;
a Context object to represent the web request for the controller;
a Response data-transfer object to represent the web response from the controller;
an Accept object to deal with content-type, language, charset, and encoding negotiation;
a RendererInterface along with an AbstractRenderer to allow controller implementation authors to use any rendering system they liked, such as Mustache or Aura.View; and,
a segregated SignalInterface and a bare-bones Signal implementation to handle controller hooks like pre-action, post-action, etc.

As I said in the peek at Aura.Sql v2 post, when you are used to certain things always being bundled together, it can be hard to see how they could be separated. In the Aura.Sql case, we moved some of the functionality around so that connections, schema discovery, and query building could become independent of each other; the no longer needed to be provided simultaneously.

In the Aura.Web case, it turns out extracting Aura.Dispatcher was the key to reducing the Aura.Web package contents. With Aura.Dispatcher, any object can be a controller, since it can dispatch to any method on any object (as well as dispatching to closures). In turn, there is no more need for the Aura.Web package to provide a base controller with interfaces for various implementations. Instead, you can dispatch to any object you like, with the dependencies you prefer, as your controller. That controller object can be implemented at the framework level, or in a separate package or bundle.

As a result, this means that web-specific request and response objects can be in their own package independent of any particular controller implementation. The Aura.Web v2 package contains only those request and response objects.

Request

First, the Aura.Web v2 Request object is not an HTTP request representation. It contains copies of $_ENV, $_SERVER, etc., that are clearly not part of an HTTP request proper. More strictly speaking, the Request object represents the web request execution environment of PHP.

The Request object has various sub-objects representing all of the PHP superglobals, along with objects for …

the client making the request,
the raw body of the request,
the request headers,
the request method,
content negotiation,
arbitrary path-info parameters, such as those generated by a router, and
the request URL.

The Request object can be used in any controller (or any other object, really).

Response

As with the Request object, the Response object only describes the web response, and is not an HTTP response proper. It has sub-objects for …

status headers,
cache headers
cookie headers,
redirection headers,
all other headers, and
the response content, along with convenience methods related to content type, charset, disposition, and filename.

Once you have built a Response object with any controller of your preference, you can send it with any HTTP mechanism you like, including plain PHP.

Conclusion

Whereas the v1 package included controllers, renderers, and other functionality, the Aura.Web v2 package provides only Request and Response objects. These objects are independent of any particular controller system, and independent of any specific HTTP delivery mechanism, which means they can be used in any new or existing codebase without introducing other dependencies.

By extracting functionality to independent packages, Aura v2 continues to make good on its core promises. If you like clean code, fully decoupled libraries, and truly independent packages, then the Aura project is for you. Download a single package and start using it in your project today, with no added dependencies.

A Peek At Aura v2 -- Aura.Dispatcher

2013-11-04T00:00:00UTC

In the lessons learned post, I talked about how Aura was born of the idea that we could extract independent decoupled packages from Solar, and how in doing so, we discovered that some of those extracted packages themsleves could be further split into independent pieces.

Previously, I wrote about Aura.Sql-v2, Aura.Sql_Query, and Aura.Sql_Schema as extractions from a single Aura.Sql package.

Today, I’m going to talk about Aura.Dispatcher as a combined extraction from three separate packages.

Dispatchers

At its core, a dispatcher uses a set of parameters to determine what logic should be invoked. That set of parameters is generally the result of parsing a URL with a router, but it could come from anywhere.

In Aura v1, we actually have two layers of dispatchers. First, there is a front controller at the Aura.Framework level to determine what page controller class should be instantiated. Then, at the Aura.Web page controller level, there is an internal dispatcher that picks what method will be invoked. (Some dispatchers work in only one pass to pick both the class and the method; others, such as micro-framework dispatchers, pick only a closure to execute.)

In addition to the web dispatching, the Aura v1 framework also has a CLI equivalent of a front controller. It picks the right command class based on the CLI input, but the method is always the same.

Finally, it’s not enough to know what object should get instantiated; something has to actually instantiate it. As such, the web and CLI front controllers need factories to create the objects they are dispatching to.

Extraction and Behavior

It turns out that dispatching at the framework level, and at the web and CLI levels, is all remarkably similar. After realizing that, we extracted the dispatching logic to its own independent package, without any dependendcies on any other packages.

The Aura.Dispatcher package lets you define named objects that will get instantiated only as they are dispatched to (i.e., lazy loading). It picks which named object to instantiate, and optionally which method to invoke, based on an array of router values (or any other array you wish to pass). It also works as a micro-framework dispatcher; instead of using an object factory proper, you can add a named closure and that will be invoked.

Additionally, if you want a two-stage invocation where the dispatcher picks an object, and the object picks its own method, Aura.Dispatcher comes with a trait that lets you pass named parameters to any method you like. You can use that trait in any object to pick a method and invoke it with the router (or other) parameters.

Refactoring From Micro- to Full-Stack Frameworks

Aura.Dispatcher is built with the idea that some developers may begin with a micro-framework architecture, and evolve over time toward a full-stack architecture. Here’s an outline of the full description; note that the logic used to invoke the dispatcher never changes; the only thing that changes are the params being passed and the object being dispatched to.

At first, the developer uses closures embedded in the routers parameters passed to the dispatcher; this is a typical micro-framework approach.
After adding several closure-based controllers to a router, the developer is likely to want to keep the routing configurations separate from the controller actions. At this point the developer may start putting the controller actions into the dispatcher as named closures.
As the number and complexity of controllers continues to grow, the developer may wish to convert the controller closures into separately invokable classes, lazy-loading along the way.
Finally, the developer may collect several action methods into a single controller, keeping related functionality in the same class.

With that, we have a clear path from closures in a router, to closures in the dispatcher, to invokable classes factoried by the dispatcher, and finally to classes of multiple methods factoried by the dispatcher. This means you can modify your application architecture and not have to worry about swapping dispatcher systems.

Next Steps

Because we have extracted the dispatcher behaviors from both the Aura.Web and Aura.Cli packages, it means that those packages can become further reduced in size and more focused. More on the Aura.Web v2 package next time!

A Peek At Aura v2 -- Aura.Sql and ExtendedPdo

2013-10-21T00:00:00UTC

In the lessons learned post, I talked about how Aura was born of the idea that we could extract independent decoupled packages from Solar, and how in doing so, we discovered that some of those extracted packages themselves could be further split into independent pieces.

For example, take Aura.Sql. From Solar_Sql, we pulled out the database connection abstraction layers, the query objects, and the schema discovery tools, then added on a connection manager and a mapper/gateway implementation. It was very natural to think of all these things as belonging together; they all need an SQL connection, so of course they should be bundled with an SQL connection implementation, right?

Even More Decoupling

Well, it turns out that merely extracting the SQL parts was not good enough for some of our audience. They asked, “Can we download just the SQL connection classes, without the query objects or the mapper?” As with Solar, we had to answer, “No; although the Aura.Sql package is independent from every other Aura package, the various SQL tools all have be taken together as a whole.”

As a result, we have done even more decoupling with the Aura.Sql-v2 packages. We have managed to make these packages independent from each other:

Aura.Sql-v2 is composed primarily of an extended PDO implementation, along with a connection manager and a bare-bones profiler. Its only dependency is the native PDO; there are no userland dependencies. As an added bonus, we have taken pains to make it PHP 5.3 compatible.
Aura.Sql_Query is a package of SELECT, INSERT, UPDATE, and DELETE query objects for MySQL, PostgreSQL, SQLite, and Microsoft SQL Server. It has no dependencies at all, not even on PDO. You build your query with the object, then pass it along to the database abstraction layer of your choice. Because it uses traits, it is for PHP 5.4 and up.
Aura.Sql_Schema comprises “list tables” and “list columns” functionality for MySQL, PostgreSQL, SQLite, and Microsoft. As with Aura.Sql-v2, its only dependency is the native PDO (note, not the Aura.Sql-v2 ExtendedPdo). Also as with Aura.Sql-v2, it is PHP 5.3 compatible.

With this dedicated effort at decoupling and true independence, you can now use just the extended PDO connection object, or the query objects, or the schema discovery tools, without having to download the others. Of course, you can use them all in concert if you like.

Let’s talk a little more about just the new Aura.Sql-v2 package.

Aura.Sql-v2: The ExtendedPdo Class

Instead of wrapping PDO, the ExtendedPdo class extends PDO directly. Among other things, this means you can drop it into any code already using PDO, including methods and functions typhinted against PDO, with no changes.

(N.b.: The only caveat here is that persistent connections may be an issue with extensions of PDO. If you simply cannot do without persistent connections, ExtendedPdo may not be for you.)

Once you have replaced PDO with ExtendedPdo, you can begin to use the added functionality in Aura.Sql-v2 piece by piece.

Lazy connection. ExtendedPdo connects to the database only on method calls that require a connection. This means you can create an instance and not incur the cost of a connection if you never make a query.
Bind values. You may provide values for binding to the next query using bindValues(). Multiple calls to bindValues() will merge, not reset, the values. The values will be reset after calling query(), exec(), prepare(), or any of the fetch*() methods. In addition, binding values that do not have any corresponding placeholders will not cause an error.
Array quoting. The quote() method will accept an array as input, and return a string of comma-separated quoted values. In addition, named placeholders in prepared statements that are bound to array values will be replaced with comma-separated quoted values. This means you can bind an array of values to a placeholder used with an IN (...) condition.
Fetch methods. ExtendedPdo provides several fetch*() methods for commonly-used fetch styles. For example, you can call fetchAll() directly on the instance instead of having to prepare a statement, bind values, execute, and then fetch from the prepared statement. All of the fetch*() methods take an array of values to bind to to the query statement.
Exceptions by default. ExtendedPdo starts in the ERRMODE_EXCEPTION mode for error reporting instead of the ERRMODE_SILENT mode.
Profiler. An optional query profiler is provided, along with an interface for other implementations.
Connection locator. A optional lazy-loading service locator is provided for picking different database connections (default, read, and write).

All this functionality is the result of extracting three classes, plus interfaces and exceptions, into their own independent package.

Conclusion

If you are the kind of developer who likes clean code, fully decoupled libraries, and truly independent packages, then you can see from the above examples that the Aura project is for you. Download a single library package and start using it in your project today, with no added dependencies.

Lessons Learned From The Aura Project

2013-09-30T00:00:00UTC

tl;dr

“Libraries first” is the way to go; it imposes good discipline
Extracting is detailed work, but you get testable units
DependencyInjection is awesome …
… but in-library ServiceLocators can be useful
There are still lots of PHP 5.3 users
If you have server or session vars in your HTTP request object, it’s not an HTTP request object
Some packages are still too broad in scope
From PEAR to Composer
People love ORMs
New packages: Aura.Dispatcher, Aura.Includer, Aura.Sql_Query, and others
PHP 5.3 support in some new packages

Introduction

As you may know, Aura is essentially the second version of the Solar framework. (The name change was to differentiate from the later-arriving but more well-known Solr.)

Whereas Solar was monolithic, Aura is primarily a series of completely independent libraries extracted from Solar. Each library in Aura is completely independent of the others. It also provides a system package that composes the various libararies into a full-stack framework.

I present this article to give insight into some (but not all) of the lessons learned from the process of creating the Aura project packages. (To list “all” would take way too long, and this article long enough already.)

Looking Back

“Libraries First” Is The Way To Go

Extracting libraries first, and only then going on to find a way to tie them together in a framework, was exactly the right approach. Having the discipline to say that no one library could depend on any other changed the way we looked at how a framework should operate, and how the libraries should interact in a framework. It gave us libraries that can be used in any system, not just an Aura system.

Having said that, it was our practice to have a proof-of-concept framework system running along the way, so that we could test the tying-together process as we went. As we realized what worked and what didn’t at the framework level, we were able to go back and revise the library so that it was more friendly in a shared system.

Extracting Is Detailed Work, But You Get Testable Units

Just because the code to be extracted already exists, does not mean it’s easy to extract it. Since the original system was monolithic, tracing the dependencies and either extracting them or copying them was a time-consuming process. Because the original system did not have 100% test coverage, we needed to write unit tests for the newly extracted units. However, by extacting the units, it was actually possible to write unit tests.

DependencyInjection Is Awesome …

Solar used a variation of ServiceLocator for inversion of control. When you have control of the whole system, ServiceLocator is reasonable, but in a suite of completely independent libraries, using a ServiceLocator to coordinate them means introducing a dependency. That in turn means the packages are no longer independent of each other. This is why we setted on using DependencyInjection early in the project (and even then only after trying lots of different ServiceLocator variations).

Using DependencyInjection for the libraries has been a complete and total win. Aside from having to change how you think about dependencies, the technique provides an unmitigated positive outcome. The added bonus of having the Aura.Di DependencyInjection container to manage injections has likewise been of immense benefit.

… But In-Library ServiceLocators Can Be Useful

However, using a ServiceLocator inside a library only for the purposes of that library has turned out to be a reasonable approach. For example, the helpers in Aura.View are collected into a locator, and the locator is injected into the template object. That particular locator is not reused outside the Aura.View package.

Each package that ends up needing a locator gets its own, sometimes more than one depending on the service that needs to be located. Obviously this is not DRY behavior. The tradeoff is that you completely avoid the temptation to use a shared ServiceLocator across multiple packages, thereby introducing dependencies and reducing testability.

(Incidentally, writing a ServiceLocator is dead simple in PHP 5.3 and later; perhaps that deserves a post of its own.)

There Are Still Lots Of PHP 5.3 Users

The first major work on the Aura project started in Feb 2011. At that time, we targeted PHP 5.3, which had been out for quite a while. When PHP 5.4 came out in Mar 2012, it was too hard to resist the new short array syntax and callable typehint, so we changed the minimum PHP requirement to 5.4. Adoption of PHP 5.4 has not been as quick as we thought it might be; we still get lots of requests for 5.3 versions of the packages. Some folks have actually backported some of the packages to 5.3.

You Keep Saying “HTTP” – I Do Not Think It Means What You Think It Means

If you have representations of $_ENV, $_SERVER, or $_SESSION in your HTTP request object, it’s not an HTTP request object. The same goes for a wide range of other functionality. An HTTP request is composed of headers and content, not server variables. Your request object may be a web request, or it may be a representation of the PHP execution context, but it’s not an HTTP request object.

For us, providing an Aura.Web request object completely independent of an HTTP (proper) request object was a big win. The web (not HTTP) response object, as a data-transfer object, being able to be translated to any other HTTP response, was also a big win for testability and separation of concerns.

Some Packages Still Too Broad In Scope

We successfully made the split between bootstrapping (at the framework level), routing, front-controller dispatching, the actual controllers, and the HTTP request/response cycle; between command-line dispatching and the actual commands; between input modeling, input filtering, and form output generation; between session handling and everything else; and so on.

However, it turns out that some packages can be split apart even more. For example, the Aura.Web package could easily have the web “request” and “response” objects (not to be confused with HTTP request/response) removed to their own package for reuse; likewise, the internal dispatching mechanism can be pulled out for reuse as well. Aura.Sql, Aura.Cli, Aura.View, and even parts of the framework itself have candidates for further extraction.

The drive to put more functionality in a library can be unnoticeable, even when your explicit goal is to separate concerns, because you’re used to thinking about a problem in a certain way. That can make it hard to see which pieces may be delivered separately and which must go togther.

From PEAR to Composer

When we started the project, PEAR was still the package manager of record in PHP land. We centered our release process around writing PEAR package.xml files, based on the previous Solar release process. When Composer came along, we tried for a while to target both packaging systems. I will admit to dismissing Composer at first and trying very hard to make PEAR do what we wanted (I am as susceptible to inertia as anyone else ;-) but in the end Composer was much more suited to our needs. (I say this as someone who has a long PEAR history and background.)

People Love ORMs

Aura provides a DataMapper as part of Aura.Sql, and a marshalling tool in Aura.Marshal, so you can build your own model layer any way you like. But people (reasonably) want something to do all the work for them. We had Solar_Sql_Model previously, and there’s been an expectation that we’ll provide something similar in Aura.

Writing a good ORM is exceptionally difficult, time-consuming, and detail-oriented. It is a huge time-sink and takes over your life. It also turns out that an ORM is, by its nature, not something that is easy to decouple. Finally, using an ORM seems like heaven at first, until you reach the edges of its usability, and then like a Twilight Zone episode you realize you are actually in hell.

So, not providing an ORM has been a mixed bag. We have been able to concentrate on other useful components without getting dragged down by writing an ORM. On the other hand, there’s clearly a desire for them in the PHP world. The lack of an ORM package for Aura has been perceived as a negative by some people, even as they also note they want to do things their own way.

Looking Ahead

As we improve on Aura v1 and begin work on Aura v2 libraries, here’s some of what we expect to do.

Further Extraction

As noted above, some packages have functionality candidates for extraction.

We can derive an Aura.Dispatcher package from combined functionality of the Aura.Cli, Aura.Web, and Aura.Framework packages. This makes full-stack and micro-framework dispatch styles available in a single package.

The Aura.Web package can have its request/response objects extracted as well. At that point, because dispatching has been extracted, there’s no need for a base controller object in Aura.Web. Your own controllers become trivial to implement in any way you like. The same goes for Aura.Cli, in that the Context and Stdio objects can live in a package of their own, leaving commands for independent implementation.

The framework package has a technique for including configuration files from the various packages. This can be pulled out into a general-purpose Aura.Includer package.

The Aura.View package currently has the helpers bound to it, but it turns out the helpers are easily extractable to their own Aura.Html package.

The Aura.Sql package is particularly interesting. It seems like the database connection functions, query objects, and schema discovery functions all have to be bound together. But, by moving some of the functionality around, it turns out they can be split up into their own independent packages. Take a look at Aura.Sql-2.x, Aura.Sql_Query, and Aura.Sql_Schema to see how we’re doing it.

Package Organization

As you can see from the new packages, we expect to use PSR-4 instead of PSR-0. This makes the src/ and tests/ directories somewhat more shallow and easier to navigate. We will be getting rid of the meta/ directory, since it was an artifact of attempting to maintain both PEAR and Composer packages.

PHP 5.3

Where reasonable, we will consider re-implementing functionality for PHP 5.3, but this is likely to be the case only for v2 libraries.

This is something we’ve gone back-and-forth on, and it’s been a hard call. Basically, if a library must have traits, it will be PHP 5.4 only; otherwise, we might try to use the old array syntax and avoid the callable typehint for the sake of broader usability.

That’s All For Now

There’s a lot of other stuff in the works, but that’s all we can discuss for now! Join the mailing list and watch us on Twitter for more updates.

Aura.Di And Testable Controllers

2013-09-23T00:00:00UTC

Brandon Savage mentions his use of Aura.Di in his blog post The Myth of the Untestable Controller.

Back when I was working on Zend Framework, controllers were untestable. They had lots of dependencies, many of which were difficult if not impossible to mock. Testing a controller, at least in isolation, was nearly impossible.

…

But the controller, being just an object, is as testable as you want it to be.

In a small framework that I’ve written, the controller is entirely testable. Dependencies are injected through use of a dependency inversion container (Aura.Di in fact). These dependencies can be effectively mocked. The controller is responsible for returning a response object that is decoupled from an HTTP response which can be inspected and evaluated for correctness.

Sounds like there’s some use of Aura.Web in there too.

Aura Framework -- Stable 1.0.0 System Release

2013-09-18T00:00:00UTC

The Aura “system” package, which combines a system skeleton and the Aura libraries into a full-stack framework, was released today at 1.0.0 stable. This makes it formally ready for production use (although it has been in production use informally for the past year or so).

You can now start an Aura project with a single Composer command:

composer create-project aura/system /path/to/your/project

Take a look at the installation instructions for more information.

It feels great to have both stable, decoupled, truly independent package libraries and a system that integrates them into a framework. Many, many thanks to everyone involved who helped get us to this point.

New Releases -- Input, Sql, View

2013-09-17T00:00:00UTC

On the heels of last week’s slew of releases, we have three followups!

The Aura.Input package got a feature-level bump to 1.1.0, with a new FormFactory. Thanks to Hari KT for championing that one.

Aura.Sql is now at 1.3.0, due to lots of work from MAXakaWIZARD to provide SQLite- and PostgreSQL-specific query objects.

Finally, the Aura.View package got a bugfix and is now at 1.2.1; it handles content-type negotiation better for those times when there is no Accept header.

Take a look at all of the Aura packages here – each of them completely decoupled from the others, ready for you to use with no additional dependencies.

Thanks to everyone who helped on these releases!

All Aura Libraries Now Stable

2013-09-11T00:00:00UTC

As of yesterday, the three remaining “Google Beta” libraries were marked as stable and released:

Aura.Filter provides validation and sanitizing for data objects and arrays.
Aura.Input has tools to describe and filter user inputs from an HTML form, including sub-forms/sub-fieldsets, fieldset collections, an interface for injecting custom filter systems, and CSRF protection.
Aura.Intl provides internationalization (I18N) tools, specifically package-oriented per-locale message translation.

This means all the Aura library packages are now stable, and formally ready for production use.

Maintenance and Feature Releases

In addition, we have issued releases of all the other Aura libraries. The substantial changes were to these packages:

Aura.Http: (CHG) Transport now adds a ‘Close’ header when sending a request.
Aura.Router: (CHG) Route::attach() now works with an empty path.
Aura.Session: (CHG) Manager::destroy() now checks whether the session is started; if not, starts it, and then destroys. (This is because sessions are lazy-loading in Aura.)
Aura.Sql:
- (ADD) Profiler::getLastQuery() to get the last profiled query.
- (CHG) AbstractConnection::fetchAll(), fetchAssoc(), fetchCol(), and fetchPairs() all now take a third param: a callable to apply to each row in the results.
- (NEW) Query\Mysql classes to support MySQL-specific functionality:
  - (NEW) Query\Mysql\Select with SQL_CALC_FOUND_ROWS and other mysql-specific flags.
  - (NEW) Query\Mysql\Insert with IGNORE and other mysql-specific flags.
  - (NEW) Query\Mysql\Update with IGNORE and other mysql-specific flags, as well as LIMIT functionality.
  - (NEW) Query\Mysql\Delete with LOW_PRIORITY and other mysql-specific flags, as well as LIMIT functionality.
Aura.View:
- (CHG) Escaper\Object now recursively escapes arrays instead of converting to ArrayObject and wrapping in an escaper
- (ADD) TwoStepView::getTemplate() to get the template out of the view
- (NEW) Helper\Form\Checkboxes

Package Documentation and New Manual

We have reorganized the package documentation somewhat; instead of keeping API docs in the gh-pages branch of each library repository, we are now pushing them to the main site repo. It turns out this is easier for site maintenance in many ways, not least of which is keeping a consistent look and feel for the site.

In addition, we have incorporated a new manual. Many thanks to Hari KT for putting that together.

The Future!

The next step is to make a stable Framework and system release. After that, we can review our initial goals to check our progress. Finally, in addition to maintaining the v1 libraries, we can begin thinking about how to move toward Aura v2 to take advantage of the current state of PHP.

New Site, New Logo, and New Releases

2013-05-09T00:00:00UTC

Last week we updated the project site layout with a variation on Bootstrap called Spacelab, and incorporated our new logo. Along with that, over the past few weeks, we have been quietly releasing updated versions of all our library packages. Many thanks to everyone who contributed; you should try one out today!

New System Release, Including Aura.Framework and Aura.Demo

2012-12-18T00:00:00UTC

Late last night we released version 1.0.0-beta4 of the full-stack system, which composes all the independent Aura packages into a coherent framework using the Aura.Framework package in a project skeleton. We have extracted the “hello world” portions into their own Aura.Demo package so that it can be removed or disabled when you begin your project. Download it and take it for a spin!

Aura.Micro -- Experimental Replacement for Silex

2012-12-14T00:00:00UTC

Micro-frameworks have gotten a lot of attention in the PHP community over the last year. Many people are familiar with Silex, the extremely popular micro-framework built on top of Symfony Components. There’s something really elegant about the way you can write a quick little application with a micro-framework.

I was recently working on a small project that used Silex. As I browsed my vendor folder, I realized how much extra “stuff” I had inherited with Silex. There were a bunch of other components required when all I wanted was some quick and easy routing, micro-framework style.

When I think about going lean I always find myself coming back to Aura. Micro-frameworks are not a new to idea to Aura, so I wondered if I could take the elegance and ease of Silex by wrapping up Aura.Router and exposing it through a similar API. The result is Aura.Micro, a light wrapper for Aura.Router to get a Silex-style API.

A couple of things are worth noting:

First, this is just an experiment and I had no intention of 100% parity with Silex. Silex is built onto Pimple, mixing the ideas of a micro-framework and a service locator. Aura.Micro is just a micro-framework for quick and easy web application routing.
Second, I very intentionally decided to make Aura.Router the only dependency for Aura.Micro. This means that rather than leverage Aura.Signal or Aura.Di (both really awesome libraries!), or even some other Event and Dependency Injection libraries, I added a super-light callback system to provide methods like $app->before() and $app->after() and $app->finish() and $app->error(). I completely ignored pieces like the Silex service providers.

So what does Aura.Micro look like in practice?

<?php
$app = new Aura\Micro\Micro();

$app->before(function(){
    print "Running before" . PHP_EOL;
});

$app->after(function(){
    print "Running after" . PHP_EOL;;
});

$app->finish(function(){
    print "Running finish" . PHP_EOL;
});

$app->error(function(){
    print "Error" . PHP_EOL;
});

$app->get("/test", function(){
    print "Testing" . PHP_EOL;
});

$app->get("/hello/{:world}", function($world) use($app){
    print "Hello {$world}" . PHP_EOL;
});

$app->run();

You can clone Aura.Micro from GitHub or drop the following into your composer.json file:

{
    "repositories": [
        {
            "type": "vcs",
            "url": "http://github.com/stanlemon/aura-micro"
        }
    ],
    "require": {
        "stanlemon/aura-micro": "*"
    }
}

Have ideas on how to improve this little wrapper? Add an issue or send over a pull request!

Aura Is More Decoupled Than ZF2 and Symfony2

2012-12-11T00:00:00UTC

PHP Magazin published a followup interview with Paul M. Jones about Aura, regarding decoupled components in Zend Framework 2 and Symfony 2.

Being able to use Symfony2 components or ZF2 modules is not quite the distinction I am making. The distinction is that all Aura packages (with the exception of the Framework package) are completely independent, and have no cross-package dependencies, whereas at least some of the components from Symfony2 and ZF2 have dependency requirements.

By way of comparison, let’s examine something that ought to be relatively straightforward: input validation and filtering. We’ll start with ZF2, then move on to Symfony2, and end with Aura. In each case, we will try to download the package and run its tests; this should be a good indicator of whether or not the package can be used independently. We will discover that you can’t do it at all with ZF2, you can kind of do it with Symfony2, and that it’s trivially easy with Aura.

Read the full English translation of the interview here: http://paul-m-jones.com/archives/4176

How Is Aura Better Than (er, Different From ;-) Symfony and Zend?

2012-12-06T00:00:00UTC

PHP Magazin published an interview with Paul M. Jones about the Aura project. Read about it here: http://paul-m-jones.com/archives/4152

First Stable 1.0.0 Library Releases

2012-11-12T00:00:00UTC

The Aura Project for PHP 5.4 is happy to announce its first release of 1.0.0 stable library packages. The packages include:

In addition, we have initial beta releases of three new library packages:

Each library package is independent of all the others, so you can pick and choose which ones you want to use. With few exceptions, each class in each package has 100% PHPUnit test coverage. Each package has a full README for getting started. They all have a composer.json file and are registered at Packagist.

While the above packages are completely independent of each other, Aura also has a Framework package that binds them all together. Releasing the next version of that Framework and system skeleton is the next thing for us to do.

You can learn more about the Aura Project at http://auraphp.github.com, and please be sure to join our mailing list at http://groups.google.com/group/auraphp.

Contributing to Aura Project

2012-07-13T00:00:00UTC

Sometimes you may have noticed a bug, or need a feature implemented, and need to contribute back to the aura community. These are some of the steps to help / contribute to aura project.

#Set Up Git First you need git and a github account. If you are new to git and github the guide set up git will help you.

#Fork A Repo

Now you need to fork the repo you want to contribute. Here is a detailed guide on how to fork a repo

In this example we will be using Aura.Web as the repo you need to fork and make the necessary changes(bug/features) and give a PR (Pull Request).

Point your browser to https://github.com/auraphp/Aura.Web and click fork. Now the repo will be in your github account.

Eg : https://github.com/your-username/Aura.Web

Now you need to clone to your local system.

git clone git@github.com:username/Aura.Web.git

cd Aura.Web

All Aura.Package has master and develop branch. The master points to the current or latest release. All the development activities goes in develop branch. There will be different tags for each release. So if you want to give a PR for a bug/feature then you create a branch from develop.

Lets see in which branch you are in ( $ represents the terminal )

$ git branch

Will list the local branches. For eg something like

*master
develop

Now you can checkout to develop branch like

$ git checkout develop

Lets check on which branch we are

$ git branch

* develop
master

Lets add the remote repo as upstream (https://github.com/auraphp/Aura.Web)

$ git remote add upstream https://github.com/auraphp/Aura.Web.git
# Pulls in changes not present in your local repository, without modifying your files

Never commit directly to master, develop branches. Always create a new branch and give a PR. Lets see how we can do. Lets create another branch and do our experiments.

$ git checkout -b experimental

Switched to a new branch 'experimental'

This has created a branch from your current branch(in this case develop)

Now you can do your experiments and commit the changes. In the mean time the develop branch of auraphp would have received many commits. So you may want to merge the changes.

$ git fetch upstream
# Pulls in changes not present in your local repository, without modifying your files

If you want to merge the commits from the upstream/branch , to your current branch you can do like

$ git merge upstream/develop

Sometimes there can be conflicts and you may want to resolve and commit manually.

Before you push your branch to your github account remember to run phpunit and check the PSR-1, PSR-2 by running PHP_CodeSniffer.

$ git push -u origin experimental

Once you have pushed give a PR to the develop branch if its a feature/changes.

#Running PHPUnit I assume you have already installed phpunit . If not, have a look into installing phpunit . From the tests folder run phpunit

$ cd tests
$ phpunit

#Running PHP_CodeSniffer

$ git clone git://github.com/squizlabs/PHP_CodeSniffer.git
$ cd PHP_CodeSniffer
$ php scripts/phpcs -h
$ php scripts/phpcs --standard=PSR1 path-to-Aura.Web/src
$ php scripts/phpcs --standard=PSR2 path-to-Aura.Web/src

You can also install via pear. For more information look into https://github.com/squizlabs/PHP_CodeSniffer

The core team has direct push/pull access but still its a good idea that Paul M Jones do the merge. We will discuss about the PR, why the changes needed etc.

Thanks for being with Aura and we love to see your contributions. If you have any queries feel free to comment below or create an issue or talk in #auraphp irc freenode or in https://groups.google.com/group/auraphp or tweet to @auraphp.

If you are new to irc, you can use pidgin or x-chat.

Aura Team

Aura.Router can also be used as a micro-framework dispatcher!

2012-06-20T00:00:00UTC

Sometimes you may wish to use Aura as a micro-framework. It’s also possible to assigning anonymous function to controller:

<?php
$map->add("read", "/blog/read/{:id}{:format}", [
    "params" => [
        "id" => "(\d+)",
        "format" => "(\..+)?",
    ],
    "values" => [
        "controller" => function ($args) {
            $id = (int) $args["id"];
            return "Reading blog ID {$id}";
        },
        "format" => ".html",
    ],
));

When you are using Aura.Router as a micro-framework, the dispatcher will look something similar to the one below:

<?php
$params = $route->values;
$controller = $params["controller"];
unset($params["controller"]);
echo $controller($params);

Via Web Routing in PHP with Aura.Router. The Aura project for PHP 5.4 codebase is https://github.com/auraphp.

Slides from Decoupled Library Packages for PHP 5.4 at PHP | Tek 12

2012-05-25T00:00:00UTC

Below are the slides from the talk given by Paul M Jones at PHP Tek 12. If you were there, please give feedback on the talk: http://joind.in/talk/view/6495.

Writing / Sharing your experience with Aura

2012-05-18T00:00:00UTC

When you play with aura components, sometimes you may have faced some technical difficulties which people may have never faced. Its always hard to remember what all things we did to resolve it. In such cases we write small snippets of code either in blog or as pastie for future reference. Its a good habit to share stuffs that we learn. There can be better way to do other than that also.

If you like to share something on aura components, you can share here.

#How can you write posts on aura blog?

Fork https://github.com/auraphp/auraphp.github.com

Add your post to the _posts directory with naming convention as

yyyy-mm-dd-url-of-post

Open it on your favourite editor and post

---
layout: post
category : category-name
tags : [tags]
---
    
Contents. If you want to highlight some code snippets add 4 spaces in front of it.

You can see the examples over https://github.com/auraphp/auraphp.github.com/tree/master/_posts

Now commit and push to your repository and and initiate a Pull Request.

We will verify it and publish …. Easy right ?

Then why are you waiting ? Start writing :-) .

Finally blog is here

2012-05-17T00:00:00UTC

So finally we have a blog for aura project. We are happy to set the blog before Beta-3. We have some shiny new feature coming for Aura.Http, Aura.View components. Stay tuned for the upcoming Beta-3 release in coming days.

In the mean time if you are new to aura, we welcome you to join irc of #auraphp channel in freenode. You can also join google groups.

Hari K T

Aura for PHP

First Aura 3.x Stable Releases

A Web Router for PSR-7, with Bookdown Documentation

Aura 3 Plans

The Past: Aura 1.x

Aura 1.x Framework

Aura 1.x Libraries

The Present: Aura 2.x

Aura 2.x Testing Structure

Aura 2.x PHP Versions

Aura 2.x Release Commitments

The Future: Aura 3.x and Beyond

Minimum PHP Version Bumped Up

Dependency Restrictions Very Slightly Relaxed

Provision Of Interface Packages

Ecosystem Dependency on Composer

Change License From BSD to MIT

No More Framework Under The Aura Name

Removal of Library Config Files

Beyond 3.x; or, A Version Is Just A Number

Conclusion

PHP World Releases!

Releases

Aura.Accept

Aura.Di

Aura.Auth

Aura.Router

Aura.Project_Kernel

Other Releases

Framework documentation

Other tutorials

Conclusion

First 2.0 Stable Project Releases!

Other Releases

Conclusion

A Round Of New Releases

An Updated Preview Of Aura.Auth

Aura.SqlQuery v2 Stable Release

A Round Of 1.x Releases

Aura.View 2.0.0-beta2 Released!

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

Aura.View

Aura.Html

Conclusion

First v2 Beta Releases of Web_Project, Cli_Project, and Framework_Project

Projects

Kernels

Conclusion

Aura.Sql 2.0 Stable Released

Composer-Assisted Two-Stage Configuration

Two-Stage Config

Classes, Not Includes

Composer Assistance

Conclusion

Aura.Marshal, A Database-less non-ORM

Aura.Cli 2.0.0-beta1 Released

Aura.Sql_Schema 2.0.0-beta1 Released

Aura.Web 2.0.0-beta1 Released

Aura.Router 2.0.0-beta1 Released

Aura.Sql_Query 2.0.0-beta1 Released

Version 2 Beta Releases | Includer, Autoload, Sql, Dispatcher

First PSR-4 Autoloader Released | Aura.Autoload 2.0.0-beta1

Which is Lighter, Silex or Aura.Web_Project?

Methodology

Measurements and Comparisons

Total Package Dependencies

Total Disk Usage

Total Non-Comment Lines Of PHP Code

Total Class Count

“Actual Usage” Class Count

“Actual Usage” Non-Comment Lines Of PHP Code

Minimal Interface

Conclusion

A Peek At Aura v2 -- Aura.Web_Project, The Micro/Macro Web Framework

Projects? Kernels? Dependencies?

Getting Started

Controllers: Micro/Macro?

Micro Controller

Macro Controller

Configuration?