Here's everything you need to know about Hexagonal Architecture:

The Hexagonal Architecture, defined by Alistair Cockburn, is an implementation of what we call a Clean Architecture. Its main motivation is to divide our application into different layers with their own responsibility. This separation by layers allows us to decouple our code from external dependencies, such as the framework or any other external library, or third party.

Ports and adapters

This architecture is also widely known as the ports and adapters architecture, or by its English name ports&adapters. And it is just because it makes intensive use of the “adapter” pattern (Adapter Pattern) together with the principle of reversal of dependencies to obtain the decoupling we were talking about before.

Why hexagonal?

In almost all texts or documents that talk about this architecture, we usually see it represented in the shape of a hexagon. And why a hexagon and not a pentagon, or a triangle or any other polygon? There is no official answer to this question, simply may be because the hexagon is the most versatile polygon.. Be that as it may, the number of sides is not relevant, it is only a merely cosmetic arrangement to differentiate it from the rest of the clean architectures.

The fact is that each side represents an input/output port of the application, and a polygonal shape expresses this principle better than a circle.

These ports are the entry point for any of the external agents or mechanisms that can interact with our application, whether they are mobile or web clients through the port for REST API, Web browsers through the HTTP port or a queuing system through the HTTP port for Message Brokers.

Each of these ports has, in turn, one or more adapters assigned to it, depending on the diversity we want to support. For example, the port for MessageBrokers could very well have adapters for RabbitMQ, Redis, Beanstalk or AmazonSQS, if what we want is to support all this variety of providers.

Points in common with Clean Architecture

In the future, we will talk about Clean Architectures and its characteristics and we will see that the hexagonal architecture is one of the purest implementations that we can find of the Clean Architecture.

Both the distribution of the layers and their content or dependency rules are literally the same, but we will still see their characteristics.

The dependency rule

Each of the concentric hexagons represents a layer, and this layer in turn is a barrier that can only be crossed by its upper layers. Thus:

• Infrastructure you can access Application and to Domain
• Application you can access Domain
• Domain can only access Domain

The further inward we penetrate into the layers, the deeper we get into the business logic, rules and policies. The further out we move, the closer we are to external agents or mechanisms (web or mobile clients, external services or APIs, infrastructure services such as databases, queuing systems, etc).

Directory structure and layer separation

We are going to see step by step the directory structure and how the code is distributed in the different layers. We will start with a basic example that we will iterate through.

First of all, the root of our project could be this:

• apps contains the applications, the installations of the different frameworks we use. This is where our controllers and routes will live.
• src will contain our code, the business logic of our application.

Here we can see the content of an application displayed. For reasons of space we have omitted all non-relevant folders, leaving in view only the entrypoint (index.php) and controllers.

We have opted for a distribution in contexts (API y Shared). In this case we have only one functional context (API) and another shared (Shared), but we could have more, for example, backoffice, which could contain all the code to manage a content management application.

As can be seen, each module contains a triplet of folders, each corresponding to one of the layers of the architecture.

Going into more detail, we can see the contents of each of the folders that make up the architecture:

• Application. Use cases. In our case we apply CQRs, so they are usually composed of one query (reading action) or a command (writing action), a handler or handler and, optionally, a service that executes the action. In some cases this service may be shared by other use cases, as for example in the case of GetUser, We therefore promote the service of application service a domain service, by placing it in the folder Domain and making it accessible to the rest of the use cases.
• Domain. This is where we host the domain objects, such as the entity User that represents a user, or the service contracts to be implemented in infrastructure, such as UserRepository. We also consider exceptions as domain objects, and some shared services such as the one mentioned above. GetUser.
• Infrastructure. Finally we have the implementations of the domain contracts. In this case we only have one implementation of the repository and it would be for the database engine. MySQL, We could very well support more by simply implementing the contract.

Earlier we talked about a shared environment, and this is where most of the contracts and implementations of elements that will be used throughout the application go, such as, for example, a EventDispatcher, or the buses of commands y queries. In this example, we have implemented a bus with two different suppliers: Symfony y Tactician. And, in addition, we have made two different implementations for each: the synchronous and the asynchronous version.

With this we intend to demonstrate the versatility that this architecture offers us and the ease of change that it brings to our code: we could change the way our code is handled. commands and our queries by simply altering some configuration parameters of the dependency container.

Hexagonal architecture and DDD

We will have seen a thousand and one times the term hexagonal architecture along with the term DDD, and they are undoubtedly a killer combo very useful.

DDD is a development methodology that advocates decoupling above all else, so the Hexagonal Architecture fits like a glove as the central core of its practice.