Onion Architecture And The Blog

Making a blog (and having fun while doing it)

Who am IProduct Developer - Systems Architect - Freelancer - Development Manager

Past experienceSenior Developer for CleverbugLecturer at the Digital Skills AcademyDirector of Tercet, software development consultancy

Current positionSoftware Development Manager for OliveMedia

Barry O Sullivan

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

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

The featuresSo 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.

The architectureWe 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

The DomainThe heart of the application.Contains anything that’s business rule relatedKeep 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

The APIEntry 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

The InfrastructureContains 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. . .)

How layers interactA 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.

Building the BlogThe implementation is split into 3 sections

● The domain● The API● The Infrastructure

○ Services○ Storage○ Controllers

The Blog DomainA 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 rulesPost, ID, Title, Author, PublishDate, Content

We don’t have any other business rules for now, so we left it at that

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 methodsstore(Post $post)fetch(UUID $id)all()

The Blog APINext 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 queriesCommands

CreatePostQueries

PostPostList

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.

Infrastructure - ServicesWhy 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 enginesCommonMark -Convert markdown into HTML, extensibleUUID - UUIDs, because they’re actually really handyCarbon -Improved version of PHPs DateTime classes

Infrastructure - StorageWe 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 filesblog/

e09135f2-ade1-4c25-9527-7ecbdc0d7c15/details.json (title, author, date)markdown.md (Actual content)

When we create a post, this structure is createdWhen we fetch a post, it reads from the file system and parses this data, turning it into a post object.

Infrastructure - ControllersControllers are our access point to the application from an external sourcesIn 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.

The CodeLet’s have a look at some code

Just a quick look so you can seewhat we’re talking about

Creating a post We made this really easy.Open up a terminal and go to the root folder

Run the followingphp 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

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

Next StepsWhat 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!

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!

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