Hexagonal architecture: an example of implementation

What is the hexagonal architecture?

The hexagonal architecture is a case of application of DDD (Domain Driven Design).
It allows to isolate the core business of an application and automatically test its behavior independently of everything else.
According to Alistair Cockburn (@TotherAlistair), the hexagonal architecture allows an application to equally be driven by users, programs, automated test or batch scripts, and to be developed and tested in isolation from its eventual run-time devices and databases.
This architecture is also called PORTS & ADAPTERS.

Concretely it permits to separate the application in three parts : the application, the domain and the infrastructure.
The application is the side by witch the user or the external programs will interact with the application. There is the code that allows these interactions. The application drive the domain.
The domain is at the center of this architecture. It contains all the code that concerns and implements the business logic. The domain drive the infrastructure.
The infrastructure is the part where we find the dependencies that the application needs to work.

The advantages of this architecture are numerous:

  • Its separates the problems.
  • Allows developers to focus on business logic.
  • Facilitates automated testing.

Example of implementation

For example consider an application that solicits an external API to display images on a web page. Look at my repository : https://github.com/oumarkonate/hexagonal-architecture


The application is the side by witch users will interact with the web site. it will contain the code of graphical interface (assets, templates), the routes, the controllers, the request, the response, the config, …

Everything that is not part of domain and infrastructure is part of the application.

The application is isolated from domain and infrastructure and must be able to be started by a user, a program, or a bash script.


The domain contains business logic:

  • A class GalleryManager.php that manages data from infrastructure and implements the interface GalleryManagerInterface.php
  • A class GalleryDataFinderInterface.php that is implemented by the infrastructure. It is this interface that permits the domain no to depend on the infrastructure.

The domain is totally isolated and can be tested independently of the application and the infrastructure.


This is where we find all files what our application (website) needs, what it (web site) drives to work. There are essential infrastructure details like the code that interacts with the API.

The infrastructure is completely isolated and can be tested independently of the domain and application.

We find in the infrastructure the classes that handle the interaction with the external API.
The advantage is that the domain has no knowledge of how the data are retrieved.
We can change these methods and retrieve data from a database or from a file system without the domain being impacted.

The hexagonal architecture scheme

The interfaces on the domain side are called PORTS : GalleryManagerInterface and GalleryDataFinderInterface

The external classes that communicate with the ports are called ADAPTERS : GalleryController and GalleryRepository

Interaction Application – Domain

To connect the application and the domain, we inject into the application the interface that constitutes the entry point of the domain.

Concretely we inject GalleryManagerInterface.php into GalleryController.php:

// src/Controller/GalleryController.php

public function showGallery(): Response
    try {
        $imagesLists = $this->galleryManager->getImagesGalleryContents([
            'page'  => $this->request->get('page') ?? 1,
            'limit' => $this->request->get('size') ?? 10,
    } catch (\Exception $exception) {


Interaction Domain – Infrastructure

To connect the domain and the infrastructure, the infrastructure-side communication must implement the domain-side communication interface.

// src/Infrastructure/GalleryRepository.php


namespace App\Infrastructure;

use App\Domain\GalleryDataFinderInterface;

class GalleryRepository implements GalleryDataFinderInterface

Leave a Reply

Your email address will not be published. Required fields are marked *