“A False Sense of Simplicity”

These year-old posts from Piotr Solnica are about Ruby On Rails …

… but the experiences related therein should be valuable to anyone using or building a full-stack PHP framework. (I can imagine it applying to CMSes as well.)

Does this story from Piotr remind you of any framework-based project you’ve worked on in PHP?

Once, I joined an existing project. It was a huuuuge app which was running an on-line shopping community website. Complicated sales model, complicated promotions, complicated product setups, coupons, user groups, messages – it had it all. I joined them to help ship a few new features. One of my early tasks was to … add a link to something on some page. It took me few days to add this stupid link. Why? The app was a big ball of complex domain logic scattered across multiple layers with view templates so complicated, it wasn’t even simple to find the right template where the link was supposed to be added. Since I needed some data in order to create that link, it wasn’t obvious how I should get it. There was a lack of internal application APIs and relying on ActiveRecord exclusively made it extremely difficult.

I’ve consulted on projects like that more than once. Indeed, the posts might well have been subtitled “The Perils of Convenience-Oriented Development”:

People are attracted by Rails because it gives you a false sense of simplicity, whereas what really happens is that complexity is being hidden by convenient interfaces.

Read both of the posts, and see if you can relate. They just reinforce to me that this is what to expect when you embed your domain logic in your user interface logic.

Remember: with server-side web-based applications, the user interface is the HTTP request and response. Any code that reads from the request, or that writes to the response, is part of the user interface. Putting your domain logic in the user interface is convenient to start with, but as soon as things become even a little bit complex, that “convenience” becomes a burden.

Atlas ORM 1.2.0 Released

The 1.2.0 release adds the ability to define WHERE conditions on relationships. (The 1.1.0 release added functionality to ignore foreign key string case when wiring up objects in memory, and 1.0.0 was released pretty quietly a couple of weeks ago.)

Try it out today, because you like keeping your persistence layer separate from your domain layer.

Now, read on for some history, if you care about that kind of thing.


Many years ago, we on the Solar project developed Solar_Sql_Model, an Active Record type of ORM. Overall I liked it well enough, though (as with anything) it had its strengths and weaknesses.

Since then, after extracting the Solar components to Aura libraries, I’ve mostly lived without ORMs. The majority of my legacy consulting work has not made use of them; where a legacy project did have an ORM of some sort, it was a custom in-house piece of work.

However, about three years ago, I hired on with a startup to build out their backend from scratch. At the time, I wanted to do “real” Domain-Driven Design, with entities and aggregates and value objects and everything else. That meant keeping the domain system separate from the persistence system, and that in turn meant Active Record was not an option. Doctrine, a domain model data mapper, was the next logical choice, but on review it was not to my liking. (The annotations, among other things about Doctrine, just rubbed me the wrong way.)

So instead of an Active Record implementation, or Doctrine, I figured that it would be enough to use a Table Data Gateway on top of Aura.Sql and Aura.SqlQuery to retrieve rows, then map the rows over to domain objects. This was fine, for as far as it went, but the problem was “relationships.” Oh dear Codd, the relationships.

Selecting one or many objects from a single table was no big deal, but doing multiple selections from multiple tables and building up the selection statements for those relationships was a tedious, tiresome, and time-consuming burden. (Wiring them up in memory once they’d been selected was not too bad, given Aura.Marshal, but it was still more effort than I’d’ve rather been expending.)

So it all “worked,” but it was just not satisfying at all. The DDD portions, for their part, worked out great, as did the separation of the domain layer from the persistence layer, so I was pretty sure I was on something like the right track.

Then I read this article from Mehdi Khalili. It’s fantastic and you should read the whole thing. In summary, Khalili points out that it is perfectly reasonable to use a persistence model in addition to a domain model. That is, you do not necessarily have to map directly from the database to domain objects; you can map from the database to persistence objects for the data, and then later compose or map the persistence model into the domain model for behaviors.

This was a revelation to me, something that I’d never considered, or even heard of before. It alleviates wide swaths of DDD-related burdens.

As a result of my relationship-related burdens at the startup, and after reading the Khalili article, I put together Atlas, a mapper for your persistence model. Like everything else I’ve been doing for the past several years, Atlas is built in discrete layers:

  • PDO at the very bottom;
  • Aura.Sql around that, to provide convenience methods for binding and fetching;
  • Aura.SqlQuery in parallel, to support query building;
  • all of those composed into a table data gateway system to emit Row objects from tables;
  • and finally a mapper system on top of that to emit Record objects composed of table Rows and their relationships

As such, each Record object is composed of a Row (from the “main” table) and its Related objects (themselves Records, each of which is composed of a Row and Relateds, and so on).

Atlas uses the term “Record” to indicate that the object is not a domain entity or aggregate. You can use Records directly for straightforward CRUD/BREAD operations, or you can map them over to your domain objects.

Fetching deep relationship structures is no big deal; see this article from Andrew Shell using 25 tables in different complex relationships. (Andrew’s project also shows how to keep the persistence and domain layers separate, and incorporates a debug bar implementation for Atlas.)

So, if you want a data mapper implementation that models your persistence layer, and the relationships therein, Atlas is just the thing for you. Try it out today!

Symfony 4: Directory Structure, and Common Practices

Fabien has published his plans for the new Symfony 4 directory structure. Not that it matters much to anyone in Symfony-land, where I have no status that I’m aware of, but I am happy to see the changes described.

Having said that, and recognizing that Fabien obviously has final say over his own projects …

The new etc/ directory is the equivalent of the current app/config/ directory.

Web files under web/

… it might be nice if Symfony 4 adopted more existing common practices, used by roughly 70% of Packagist packages. That is, to use config/ for the top-level config directory, and public/ for the top-level document-root directory.

More specifically:

  • config/ is used ~10x more than etc/ (ref)

  • public/ is used ~2x more than web/ (ref)

As a side note, that research resulted in the pds/skeleton publication.

(This blog post originated as a comment on Reddit.)

Command-Line Output: Consider Logging Over Streams

When writing command-line applications for PHP, consider using a logger for screen output. This is something I’ve done with great success in several projects. Producer, for example, uses a very light standard I/O logger class that writes output to STDOUT and STDERR resource/stream handles. Every command that generates output uses that standard I/O logger (cf. the issues command).

This has a couple of advantages:

  • Your command-line code gets stdout/stderr output separation practically for free, using a common PSR-3 interface.

  • If you incorporate that command-line tool into another class, you can easily inject a different PSR-3 logger so that output is captured elsewhere, instead of writing to stdout/stderr. Among other things, that makes it relatively easy to test the output of your command-line code without having to use output buffering.

I think this approach works best for non-interactive commands. If you have to read keyboard input from the user as part of the command, using a logger for output might not make a lot of sense. But if all of the command inputs are handled as options or flags, using a logger for output can be great.