Slides from a presentation given at PHPDublin. Outlines how we used an Onion Architecture to build our blog using Laravel 5.1.

1. Onion Architecture
And The Blog
Making a blog (and having fun while doing it)

2. Who am I
Product Developer - Systems Architect - Freelancer - Development Manager
Past experience
Senior Developer for Cleverbug
Lecturer at the Digital Skills Academy
Director of Tercet, software development consultancy
Current position
Software Development Manager for OliveMedia
Barry O Sullivan

3. This talk
We’re going to …
● Talk about the blog and it’s features
● look at the architecture
● look at the services we used
● look at some Laravel 5.1 code
● Show you how to publish a blog post

4. The Blog
What do we want it to do?
What’s is its purpose?
Our goals were to
● Host content from the community
● Make it easy for the community to contribute content
● Keep it simple and clean
● Use existing tools and libraries as much as possible
● Showcase some design best practice (as we see it anyway)
● Have some fun making it

5. The features
So to we decided on some simple features
● Articles are displayed as a list in the blog section
● Articles can be clicked and viewed individually
● Articles have unique urls (for SEO)
● Articles are written in markdown
● Articles are part of the repo
● People can send us articles via pull request
We had a lot more features, but these were dropped, as they increased the
scope and didn’t actually add a lot of value.

6. The architecture
We decided to use an Onion architecture
(Also known as Ports and Adapters or *Hexagonal Architecture)
Why we choose it:
● Clean separation of concerns
● Easy to maintain
● Encourages CQRS
● Industry best practice
● It’s just really nice
* A very misleading name, programmers are the worst at naming things

7. The Domain
The heart of the application.
Contains anything that’s business rule related
Keep your business logic completely separated
from your storage/service/controller logic.
Doesn’t care about the technical details, contains
only what’s necessary to validate business rules.
Made up off
● ValueObjects
● Entities
● RepositoryInterfaces

8. The API
Entry point for the domain.
Uses the domain to perform business operations.
Acts as the interface between the “Application”
and the business logic.
Ensures that implementation details don’t bleed
out into your controllers,
eg. database logic, presentation logic
Made up off
● Commands
● Queries

9. The Infrastructure
Contains the technical details about specific
technologies. Eg, how data is accessed and
where data is stored
(The framework is technically infrastructure)
Three types of infrastructure
● Controllers
● Data Storage (Database/FileSystem)
● External Services (Package, API, etc. . .)

10. How layers interact
A key part of an onion architecture is that outer
layers can use inner layers, but inner layers
have no knowledge of outer layers.
This means that the infrastructure can see
ValueObjects, but ValueObjects have no
knowledge of the Database.
Forces you to keep things simple and to put logic
where it belongs, no bleeding of details that will
make future changes difficult.

11. Building the Blog
The implementation is split into 3 sections
● The domain
● The API
● The Infrastructure
○ Services
○ Storage
○ Controllers

12. The Blog Domain
A blog post has the following business rules
● A blog must have a title, an author, an ID and content
● Title, author and content cannot be blank
● Publish date cannot be in the future
That leaves us with the following value objects that enforce business rules
Post, ID, Title, Author, PublishDate, Content
We don’t have any other business rules for now, so we left it at that

13. The Blog Domain (2)
The next step is the definition of the repo, for storing and retrieving posts.
The repo is an interface, and it defines how we expect our repository to behave,
regardless of what implementation we decide to go for.
We do this because it forces us to keep it generic, clean and easy to test. It
also gives us the option of switching to another repo type (Which we will)
The interface has three methods
store(Post $post)
fetch(UUID $id)
all()

14. The Blog API
Next we have the API, this is the entry point for our app, and it offers all the functionality we want to
expose. It’s CQRS, which just means we have two types of operations
We offer the following command and queries
Commands
CreatePost
Queries
Post
PostList
We’re using Laravel 5.1s commands and command bus for this, as it has the IOC built in. This means
we only ever use interfaces at this level and we let laravel handle the injection of our concrete
implementations of our repository.

15. Infrastructure - Services
Why reinvent the wheel when someone is giving you a jet pack for free?
We used the following packages to make our job easier
Laravel 5.1 - It’s so hot right now (and it’s really powerful)
FlySystem -Generic API for multiple storage engines
CommonMark -Convert markdown into HTML, extensible
UUID - UUIDs, because they’re actually really handy
Carbon -Improved version of PHPs DateTime classes

16. Infrastructure - Storage
We create a concrete class that implements the PostRepo interface.
Since they’re part of the repo, they’re part of the file system.
They’re stored by ID, and are represented by two files
blog/
e09135f2-ade1-4c25-9527-7ecbdc0d7c15/
details.json (title, author, date)
markdown.md (Actual content)
When we create a post, this structure is created
When we fetch a post, it reads from the file system and parses this data,
turning it into a post object.

17. Infrastructure - Controllers
Controllers are our access point to the application from an external sources
In our case, HTTP controllers and Artisan commands
HTTP to access content (It’s a website)
Artisan to create posts (We are developers after all)
In the HTTP controllers, we load CommonMark and convert the content into
HTML.
This is an important, we made the decision that rendering a post and it’s format
had nothing to do with the domain.

18. The Code
Let’s have a look at some code
Just a quick look so you can see
what we’re talking about

19. Creating a post
We made this really easy.
Open up a terminal and go to the root folder
Run the following
php artisan post:make “Post title” barryosull
This will output the ID of the post, so you can go the files and edit them. Visit
the blog on your local machine and you’ll see the post.
*barryosull is my github handle, use your own

20. Quick additions
At the beginning we decided to use GitHub usernames in the author field.
We then saw that best practice was to have the author’s avatar beside the post.
How hard would it be to add?
Well, not hard, with a little bit of JS in the front-end, we
connected to the public Github API and fetched their avatar.
15mins work, a better experience for visitor and our contributors

21. Next Steps
What will we do next?
● Cache the posts in Redis (faster)
● Unit tests
● Tags for blog posts
● View posts by tag
● View posts by author
● Turn the blog into a laravel package
● Spruce up the design
● Events for broadcasting domain changes
● Projections for handling views of data
● Write more content!

22. We need your content
Guess what? We need you!
Want to become an active member in the community?
Want to be part of an active github project?
Want to build up your profile?
Want to mess around with Laravel 5.1?
Want to write about your experiences?
Then write a post and send it on!

23. Thanks for listening
Now for questions.
Ask me any question you like!
. . . except for my pin number
. . . or my password
. . . ok, please just stick to questions about the talk
Barry O Sullivan - barry@tercet.io - http://barryosullivan.me