Discovering Clean Architecture

Story about how I discovered Uncle Bob and Clean Architecture.

Several years ago I came across the following video. It was a keynote from a Ruby conference by some guy named Robert “Uncle Bob” Martin. It’s really worth your time to watch.

Watching this opened my eyes. The idea that the framework is a delivery mechanism and not your app was completely new to me. I had been working on an app that I built using Kohana which was getting really hard to maintain.

I had never worked at a company with senior developers who talked about best practices or strategies for architecting applications. The idea of writing your application separate from the framework and interacting with it through use cases was foreign to me.

I picked up Uncle Bob’s book Clean Code and bought some of his videos on Clean Coders.

I hope to talk more about what he covers in those resources, but today I want to talk more about Clean Architecture.

In August 2012 almost a year after he gave the talk at Ruby Midwest he wrote a post titled The Clean Architecture on his companies blog.

cleanarchitecture-8b00a9d7e2543fa9ca76b81b05066629

The concentric circles represent different areas of software. In general, the further in you go, the higher level the software becomes. The outer circles are mechanisms. The inner circles are policies.

The overriding rule that makes this architecture work is The Dependency Rule. This rule says that source code dependencies can only point inwards. Nothing in an inner circle can know anything at all about something in an outer circle. In particular, the name of something declared in an outer circle must not be mentioned by the code in an inner circle. That includes functions, classes, variables, or any other named software entity.

By the same token, data formats used in an outer circle should not be used by an inner circle, especially if those formats are generated by a framework in an outer circle. We don’t want anything in an outer circle to impact the inner circles.

This has been the number one influence on how I write software.

This is one of the key motivators for me creating this blog. I hope to help PHP developers discover tools and techniques that help them become better, more productive developers.

I’m also very interested in hearing from you. I will be creating new content over the coming weeks and I want to customize the content for YOU and help you overcome any obstacles you might be experiencing. Send me a message!

Radar Under the Hood

I explain what Radar and Action-Domain-Responder are and how they work.

Radar is a project that I really like.

Radar is a PSR-7 compliant Action-Domain-Responder (ADR) system. While it may look like a micro-framework, it is more like a wrapper around the real core of your application domain.

Have your eyes glossed over yet? Don’t worry. Radar is actually very simple to use, especially once you understand what’s happening under the hood.

Today, I’d like to give you a quick tour under the hood to explain the libraries that Radar glues together and what that whole Action-Domain-Responder thing is.

Action-Domain-Responder (ADR)

Action-Domain-Responder or ADR is a pattern defined by Paul M. Jones as a refinement of Model-View-Controller or MVC which you may have heard of.

Action

In MVC frameworks you’re typically calling “Actions” within a “Controller”. If you look at the examples on the Symfony page for Controller you’ll see that you have a method numberAction within LuckyController. In ADR the action is the minimal glue that holds your application requests together.

Domain

The domain is the core code in your application that actually does the work. The idea is that this code is specific to your application. If you’re familiar with Clean Architecture from Uncle Bob, the domain entails the Use Cases (Application Business Rules) and Entities (Enterprise Business Rules) in your application. The domain shouldn’t know or care how its response is being presented to the user. It could be an HTML web page, a REST API, a command line tool, or unit test.

Responder

The responder takes a response from your domain and formats the actual response to the user. This could be done via a template system like Twig or JSON encoder.

How Radar does ADR

When you first go through the Radar documentation (which is very nice). The first question I asked myself is “Where’s the Action?”

You direct routes to Domain objects, and per route, you can define Inputs and Responders. If this is Action-Domain-Responder shouldn’t I be creating Actions?

Radar (or more specifically Arbiter) actually creates the Action for you. Remember where I mentioned that Actions are minimal glue? Radar takes that seriously.

An Arbiter\Action is simply a data object that contains three callables the Input, Domain, and Responder.

Then there is an Arbiter\ActionHandler which does the work.

First, a PSR-7 Request is passed into the Input and it returns the parameters for the Domain.

Then, the parameters are passed into the Domain and a payload is returned.

Finally, the responder is passed the payload along with the PSR-7 Request and Response.

Here is the actual code:

So What Does Radar Do?

It bootstraps the application using Aura.Di, dependency injection container.

It exposes Aura.Router to actually map paths to Arbiter Actions.

The whole thing is delivered as Relay (a PSR-7 middleware dispatcher) middlewares that do a lot of the work.

RoutingHandler takes the Input, Domain, and Responder values from the route and creates the Action.

ActionHandler then takes the Action created by RoutingHandler and handles it with the Arbiter\ActionHandler.

What Next?

If you’re interested in watching me demo Radar, you can watch my video FutureProof Your Code where I talk about Clean Architecture and how to use Radar.

I’m also very interested in hearing from you. I will be creating new content over the coming weeks and I want to customize the content for YOU and help you overcome any obstacles you might be experiencing. Send me a message!

FutureProof Your Code

A presentation I have at Milwaukee PHP on how to architect your code so it will withstand the tests of time.

Frameworks, libraries, and components are great. They can greatly simplify the process of writing applications. There is no need to reinvent the wheel. However what happens when the landscape changes? Your favorite library is no longer supported. The framework you’ve built your application on is no longer receiving updates. How you react to this news greatly depends on how you’ve built your application.

In this talk, Andrew Shell will cover how to architect your applications to allow you to leverage all the power from these tools without exposing your application to unnecessary risk. He’ll also demo how you can use Radar, a library that can make it easier to build your application in a future-proof way.

Code available: github.com/andrewshell/radar-fig-demo

This talk was recorded at Milwaukee PHP on 3/8/2016.