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

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

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

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

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

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

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

How To Modernize Your Legacy PHP Application

It is accomplished: “Modernizing Legacy Applications in PHP”, the book that will help you modernize your legacy PHP codebase, is complete. You can get it now it at

Is your legacy PHP application composed of page scripts placed directly in the document root of the web server? Do your page scripts, along with any other classes and functions, combine the concerns of model, view, and controller into the same scope? Is the majority of the logical flow incorporated as include files and global functions rather than class methods?

If so, you already know that the wide use of global variables means that making a change in one place leads to unexpected consequences somewhere else. These and other factors make it overly difficult and expensive for you to add features and fix bugs. Working with your legacy application feels like dragging your feet through mud.

But it doesn’t have to be that way! Modernizing Legacy Applications in PHP will show you how to modernize your application by extracting and replacing its legacy artifacts. We will use a step-by-step approach, moving slowly and methodically, to improve your application from the ground up.

Moreover, we will keep your application running the whole time. Each completed step in the process will keep your codebase fully operational with higher quality. When we are done, you will be able to breeze through your code like the wind. Your code will be autoloaded, dependency-injected, unit-tested, layer-separated, and front-controlled.

From the Foreword by Adam Culp:

Developing with PHP has really matured in recent years, but it’s no secret that PHP’s low level of entry for beginners helped create some nasty codebases. Companies who built applications in the dark times simply can’t afford to put things on hold and rebuild a legacy application, especially with today’s fast paced economy and higher developer salaries. To stay competitive, companies must continually push developers for new features and to increase application stability. This creates a hostile environment for developers working with a poorly written legacy application. Modernizing a legacy application is a necessity, and must happen. Yet knowing how to create clean code and comprehending how to modernize a legacy application are two entirely different things.

But understanding how to use these refactoring processes on a legacy codebase is not straight forward, and sometimes impossible. The book you’re about to read bridges the gap, allowing developers to modernize a codebase so refactoring can be applied for continued enhancement.

Early reviews and testimonials from the feedback page:

  • “This is one of those books that PHP developers from all skill levels will be able to glean value from, and I know after just a single read-through that it will be an oft-referenced resource when I need to convert my old legacy-based procedural code into something cleaner, object-oriented, and testable.” (J. Michael Ward)

  • “As I followed the exercises in the book, my questions almost seemed to be anticipated and answered before the chapter was over. Structurally the book is very well paced. Chapters that I breezed over tended to be more useful than I thought they would be. I’ve been testing for years and I still picked up some useful tidbits about structuring my tests. Just having the step-by-step advice of an expert really made a difference.” (James Fuller)

  • “Reading through the book, it feels like you’re pair programming with the author. I’m at the keyboard, driving, and the author is navigating, telling me where to go and what to do next. Each step is practical, self-contained and moves you closer to the end goal you seek: maintainable code.” (Joel Clermont)

  • “This book helped me slay a 300k line of code giant and has allowed me to break out my shell. The refactored code has 15% code coverage for unit testing which grows every day.” (Chris Smith)

If you feel overwhelmed by a legacy application, “Modernizing Legacy Applications in PHP” is the book for you. Purchase it today and get started making your own life easier!

Composer-Assisted Two-Stage Configuration in Aura

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

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

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

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

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

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

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

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

“Modernizing Legacy Applications in PHP” Update: Schedule, and Reviews

Today was my scheduled date for publishing the final edited copy of Modernizing Legacy Applications in PHP. Although the writing itself is complete, it has yet to finish its final editing pass. As such, the final version of the book is going to be delayed by at least a week. My apologies for the delay.

Even so, we have new reviews of the completed book! Here is one from J. Michael Ward:

Superb. This is one of those books that PHP developers from all skill levels will be able to glean value from, and I know after just a single read-through that it will be an oft-referenced resource when I need to convert my old legacy-based procedural code into something cleaner, object-oriented, and testable.

This is a very thorough guide to understanding how to write object-oriented programming in PHP in 2014 and getting developers stuck with legacy codebases up to speed with the tools that are available to them. I will recommend this to anyone who will listen.

And another from James Fuller:

The book is full of opinions on how to structure an application, but it thankfully avoids the trap of coming off as over-zealous and judgemental. The people who need this book know that legacy code is not a black-and-white problem and the tone of the book is both sympathetic and prescriptive.

The book is by no means overly-verbose, as you can read through it in a few well-spaced hours. I think that’s a good thing and you will probably find yourself going back to the book for reference time-and-time again, as I have already done in the period since I bought the book in beta. Occasionally you will have the annoying task of flipping to an appendix to read a large block of code but that is really a problem with any book that discusses code in detail.

And yet another from Joel Clermont:

Reading through the book, it feels like you’re pair programming with the author. I’m at the keyboard, driving, and the author is navigating, telling me where to go and what to do next. Each step is practical, self-contained and moves you closer to the end goal you seek: maintainable code.

I highly recommend this book. Even if you’re a seasoned developer like me (I’ve been writing code professionally more than 20 years), you will benefit from Paul’s approach and detailed documentation of the process.

If you feel overwhelmed by a legacy codebase, go out and buy Modernizing Legacy Applications in PHP today. (Updates are free for life.) The sooner you get started modernizing, the sooner you can start going home on time!

How To Convert Include Files To Classes

When working with legacy applications, there are two major problems tied for first place in causing frustration, pain, and overtime: globals, and includes. I talk about how to remove globals in “It Was Like That When I Got Here”. But removing includes can be a much bigger challenge in many ways.

My new book, “Modernizing Legacy Applications in PHP”, has an entire chapter on how to convert includes to independently testable classes. The chapter describes how to do this in a way that does not break the existing legacy code.

As a gift to PHP developers suffering under legacy applications, I have made that chapter part of the sample text for the book. You can read it here.


Are you overwhelmed by a legacy PHP application? Have you inherited a spaghetti mess of code? Does it use globals everywhere, so that a fix in one place causes a bug somewhere else? Does every feature addition feel like slogging through a swamp of includes?

It doesn’t have to be that way. “Modernizing Legacy Applications in PHP” gives you step-by-step instructions on how to get your legacy code under control by eliminating globals and separating concerns. Each chapter shows you exactly one task and how to accomplish it, along with common questions related to that task.

When you are done, you will come and go through your code like the wind. Your application will have become autoloaded, dependency injected, unit tested, layer separated, and front controlled. And you will have kept it running the whole time.

Buy the book today, or sign up for notifications on the mailing list below!

Sign up for Modernizing Legacy Applications in PHP:

First Name Email

Laravel Keeps Using That Word — I Do Not Think It Means What They Think It Means

One of the things that we do by defining design patterns is we create a common language that we can use to explain and express ourselves. When I say to you “I used an Adapter” or “I implemented the Factory pattern”, that should conjure up a specific image in your mind of object relationships and behaviors, even if you don’t know my specific use case or problem domain.

When we use these terms incorrectly, we not only devalue them, we confuse developers. For one of the most up-and-coming frameworks to use a technical term so incorrectly is disturbing. It breaks down the vocabulary that technical people use to communicate with each other, because there are now two very different definitions floating around with the same name.

Of course, Laravel’s Facades are in fact well-designed proxies implementing the Proxy Pattern. There’s nothing wrong with that: as a developer, it’s up to you to decide how and what patterns you’re willing to accept in your framework, and to write your application however you wish. All I ask is that we stop calling them Facades.

Hear hear. Via Let’s Talk About Facades |

Modernizing Legacy APIs

My friend Keith Casey is working on a book about practical API design. However, if you have a legacy application, adding (or updating) an API can be troublesome. It would be a lot easier to deal with an API if you could modernize your legacy application first. As Keith says:

If you read the tech press, everyone knows they need an API but most aren’t really sure what it is. They treat it as another checkbox like “Web 2.0″ was a few years ago or a mobile app was most recently. In fact, there’s an entire “API-first” movement in development circles that most people don’t understand or even realize why. …

Of course, how do you get your application ready for an API?

In response to that scenario, we are happy to announce a Leanpub book bundle: “Modernizing Legacy PHP Apps with APIs.” When you buy both books together and you get a discount from their separate prices. The Leanpub 100% happiness guarantee applies: if you don’t like your purchase, you can get your money back up to 45 days later.

Do you have a legacy application that you want to modernize? Do you want to add an API, or redesign the existing one? Buy “Modernizing Legacy PHP Applications with APIs” today and get started on making your own life easier!

Leanpub Sample Files With Symfony and Aura

One of the things that bothers me about some cli/console packages is how the commands you write with them end up being tightly coupled to the “framework” the package provides. You extend a command controller, which itself may use service location, and it has to be dispatched to via a specific console mechanism. Your actual command (the business logic) ends up tightly coupled not just to a tool for a specific task but to the package as a whole.

Most of the time I don’t need a “full console application” — I just need to read some input for the command, run my actual command logic, and send some output from the command. The Leanpub Sampler from Matthias Noback is an example of the kind of thing I usually end up doing in small or one-off projects.

Look at the invocation file for the command to generate Leanpub and see how Matthias gets this command running: load the autoloader, create Aura.Cli context and stdio objects, define the getopt flags, and then (this is the key) pass the option values to his real command object.

The command is completely separated from the environment, and fully decoupled from the “framework” that launched the command. The command itself uses the Symfony Finder component and a series of custom iterators. The work performed by the command could run as part of a web process if we wanted. This is a very nice piece of work.

Now, if you want a full console application to combine together a bunch of stuff, that’s cool. Aura has Aura.Cli_Project for that, and there are other things out there for that as well. But the central point remains this: we should strive to keep the actual work of the command separated from the framework of the project as a whole.


One of the troubles we have with legacy code is that there’s very little separation of concerns. Setup work, business logic, and presentation logic are all intertwined and difficult to work with separately. As one result of that they are difficult to test.

But it doesn’t have to be that way. My newest book, Modernizing Legacy Applications in PHP, gives you step-by-step instructions on how to get your legacy code under control by eliminating globals and separating concerns. Each chapter shows you exactly one task and how to accomplish it, along with common questions related to that task. When you complete that chapter, you will have improved the quality of your application, and it will keep running until you decide to start the next chapter.

Read more about the book or sign up for notifications on the mailing list below!

Sign up for Modernizing Legacy Applications in PHP:

First Name Email

Aura.Marshal, A Database-less non-ORM

Just a quick-hit today regarding Aura while I work on the Modernizing Legacy Applications in PHP book:

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.

Via Aura.Marshal, A Database-less non-ORM.

What Application Layer Does A DI Container Belong In?

James fuller asks:

any thoughts about which layer of the application we should be using a DI container like Aura.Di? Highest layer possible?

Twitter is too constrained and ephemeral for a good response, so I’ll answer that question here.

First, we need to remember that a Dependency Injection container and a Service Locator are indistinguishable from an implementation perspective. (This is a view I accepted only recently.) The difference is in their use: if a container is ever placed into an object so the object can retrieve its own dependencies, that container is being used as a Service Locator. Conversely, if the container stays entirely outside an object so that dependencies are pushed into the object, the container is being used for dependency injection.

If we accept that description, the proper layer for a DI container is outside every other layer in the application (with the possible exception of Factory classes). That means the DI container is part of the bootstrapping code that sets up the application, and not part of anything else.

As an example, we can imagine a web application bootstrap script that looks like this:

// set up the autoloader
include '/path/to/autoload.php';

// create and set up a Container
$container = new Container;

// retrieve a front controller service and run it
$front_controller = $container->get('front_controller');

The purpose of the bootstrap is to create and configure the container with all its services and settings, then pull one object out of the container and invoke it. None of the objects in the system has to know that the container even exists. All of the objects are being created via the container, so in a way the container “contains” the entire object graph.

The part I had the hardest time getting about real dependency injection was this: If you have a class 2 or 3 layers down in the application, and that class needs dependencies, how do they get injected? Don’t you have to pass the dependencies through the intervening layers, and then doesn’t that break a lot of rules, along with violating plain common sense? And what if that class needs access to several different but related objects, but doesn’t necessarily know what they are in advance?

The key for me was realizing that all object creation work happens in the container and not in the classes themselves. This is an alien way of looking at things for most PHP developers, who are more used to Singleton, Registry, and Service Locator, not to mention static calls to ActiveRecord objects. All of these patterns of usage mess with separation of dependencies, but are very common in PHP land, and form the basis of most PHP developers’ understanding of how to work with dependencies.

It took me a year to really “get” the concept of dependency injection, under tutelage from guys like Jeff Moore and Marcus Baker, along with the writings of Misko Hevery. Once I understood it, I wrote the Aura.Di readme file as an introductory document to step readers through the various stages of dependency allocation. Perhaps that document will be helpful to others, even if they don’t choose Aura.Di as a container.


If you work with a legacy application, you already know how hard it is to track dependencies throughout the code. Sometimes the dependencies are global, sometimes they are created inside that class that needs them, and sometimes there is a service locator implementation floating around inside the classes. This makes it frustrating to track down bugs and make wide-ranging changes, and terribly difficult to write tests because everything depends on everything else.

But it doesn’t have to stay that way. My new book, Modernizing Legacy Applications in PHP, gives detailed instructions that will lead you step-by-step from an include-oriented mess of page scripts to a modern architecture using dependency injection techniques.

You can buy the book in early-access mode today, or sign up on the mailing list below to get more information as it becomes available!

Sign up for Modernizing Legacy Applications in PHP:

First Name Email