---
title: 'Hexagonal Architecture: A Guide to Designing Your API (PHP)'
source: 'https://youtube.com/watch?v=X2afQt6LQMg'
video_id: 'X2afQt6LQMg'
date: 2026-06-21
duration_sec: 0
---

# Hexagonal Architecture: A Guide to Designing Your API (PHP)

> Source: [Hexagonal Architecture: A Guide to Designing Your API (PHP)](https://youtube.com/watch?v=X2afQt6LQMg)

## Summary

This video explains hexagonal architecture by applying it to a previously built book API. The host, Mark Bradley, draws a diagram to show how the architecture separates the application into layers: an HTTP controller, a business logic layer, and a data repository, all connected via interfaces. The goal is to demonstrate how this pattern makes the code loosely coupled, testable, and easy to modify without affecting the core business logic.

### Key Points

- **Introduction to Hexagonal Architecture** [0:00] — The video will look at hexagonal architecture, a way of designing applications to be loosely coupled, created by Alistair Cockburn.
- **The Hexagon and Business Logic** [1:25] — The hexagon shape is arbitrary; the center contains business logic. The diagram starts with the business logic layer.
- **HTTP Controller Layer** [2:15] — A circle on the left represents the HTTP controller implementation. It understands HTTP, REST, and JSON, and knows how to handle incoming requests and respond.
- **Interface Between Controller and Business Logic** [4:36] — An interface (e.g., 'IsbnBookRetriever') sits between the controller and business logic. The controller only needs to pass an ISBN to this interface to get a book.
- **Business Logic Layer (Book Manager)** [6:46] — The business logic layer (Book Manager) implements the interface. It also depends on a repository interface to obtain books.
- **Repository Interface and Implementation** [8:31] — A second interface (e.g., 'IsbnBookRepository') is created for the repository. The repository implementation (e.g., PostgresBookRepository) handles database communication.
- **Benefits of Hexagonal Architecture** [12:56] — This structure follows the Single Responsibility Principle, making each layer testable. It also allows swapping out external components (e.g., HTTP for gRPC, Postgres for MongoDB) without affecting business logic.

### Conclusion

Hexagonal architecture keeps business logic central and isolated, enabling easy swapping of external components and improving testability. The video encourages viewers to apply this pattern to their own APIs.

## Transcript

in this episode we are going to look at
hexagonal architecture
hi i'm mark bradley and welcome to
testing all the things
a screencast in which we use live coding
to demonstrate different types of
testing tools and techniques
in this video we're not going to write
any code we're going to look at the code
we wrote
over the previous episode to create our
book api
and we're going to draw out the
architecture that we used
hexagonal architecture this is a way of
designing applications to be loosely
coupled
the idea was created by alistair
cockburn
let's look at the code
in the videos where we created our book
api
i tried to avoid using the architectural
pattern we were going to use
i wanted to concentrate it on the test
we were creating
but now i think it's important we look
at the architectural decisions we made
you saw how useful they were in the aid
of testing each layer
now let's look at how they can improve
your
applications in other ways hexagonal
architecture is very simple to
understand
there are many diagrams on the internet
that show how to use it but i thought
it'd be very useful to apply it to the
code we've been writing
so the first thing we should look at is
this the hexagon of our diagram
the hexazon doesn't actually mean
anything in particular it was just a
shape that was picked
but in the center of the hexagon is
where our business
logic and our business codes it i'm
going to put that
in our diagram straight away this is
where
business logic sits
stretch out
we're going to start over here on the
left hand side of our diagram
i'm going to add a circle
that sits here
now this circle represents the
implementation of our http
handler
if we if we go and look at the code
we called that
the book by isbn
controller
click those two things together
okay so this is our controller and the
idea here
is this controller understands
http and rest and jason
that's all it understands about our
application
what comes in and out of here from the
real world
what comes in and out of this controller
is http
rest and json those are the things it
understands it knows how to
handle an incoming http request look at
the
uri and recognize the
isbn in within the pattern of the uri
and it knows how to respond with json
for different circumstances
that's all it understands not quite
there's one other thing it understands
it knows it has access to an interface
ships here sits
in between our http controller
and our business logic layer
like so we've got this interface here in
our code
we called this interface we can see if
we open up our isbn controller
an isbn book retriever and that's just
an interface
with one function retrievebook by isbn
if we go back to our diagram we label
the interface
if we link that
like so
so now we're starting to develop some
understanding that so this
isbn book retriever is the interface to
our business logic layer
our controller layer doesn't need to
understand
anything that happens within here it
just needs them to know
that once it's got its isbn from the
request that came in the http request
once it's done its thing it then needs
to pass an isbn
over into this interface and this
interface
retrieve a book for it to render into
json
and return so that's what we have here
it's very simple interface in fact i'm
just going to put
i here so we know that it's an interface
and then this jumps into our business
logic so our business logic is the thing
that implements
the function within this interface
which is retrieve book by isbn
which we called the book manager so if
we go and
label our business logic area
this is our book manager
it's there okay so our business manage
logic layer here is our book manager
and it knows it has to implement the
interface here that sits
between it and something that gives it
an isbn
so it knows it needs to return a book it
also knows it then
is responsible for obtaining a book from
somewhere
and this is where we start looking at
the left-hand side of our screen at the
right hand side sorry of our screen
and this is where we start looking at
the right hand side of our screen
our implementation our business logic
layer takes a book
repository as a dependency
and again this is another oh okay
it should have been an interface so
let's
go back and maybe we we could have had a
refactor here added that
interface which would have been better
um
and maybe we should do that so let's go
back and implement the interface
stuff set up in the code so we want to
create another interface
that sits here
okay whatever interface that sits here
and we will give this a name now
so i will quit i
sbn book repository
and that's gonna be another interval
interface
i'll go and create the interface in the
code after this and just push it i won't
make you watch me create an interface
and make those
code changes but we'll create that
interface and we'll call it that
and we know that that interface is
implemented
by a book repository so let's
create the implementation on this side
yeah okay
okay i'm going to give that a label and
that was the book repository
our book manager businesslogic layer
now implements interface it knows that
it has to
respect and it also makes use of an
interface
that it can use to obtain books a
repository
a storage solution for books because of
the interface
we should have created it doesn't have
any knowledge
of how those books are stored how
they're retrieved
it just knows that if it gives a isbn
book repository
an isbn then a book will be returned
and it can then fulfill its interface
with
over here and return that book to the
thing that's been asking for it
we could have done some better naming
here this could have been a refactor
that we
we could do as well so our book
repository again it doesn't really give
us much information
by the class name so we could have
called this book repository
instead of just book repository we could
have called it
postgres book repository or psql book
repository
to give the user of the book repository
not the user of the interface but the
user of the repository the understanding
that
this book repository uses postgres
we know now that this book repository
needs to talk to something
in the outside world so let's represent
that
okay and this is i'll stick a label on
it
the sql doesn't fit with it now
there we go
okay so the book repository here
is completely responsible for the
communication in and out of
psql
there we go so this is responsible for
implementing the interface
at least one of the interfaces we know
about the isbn book repository
and interacting with the outside world
so this shows you kind of how these
hexagonal architecture diagrams relate
to the code
we've created so i know we've got a bit
of
stuff that sits around over here which
is our application which probably
actually
imagine sits around all of the code
we've got here we'll ignore that we're
just looking at the
the details of application not the the
bootstrapping provided
by the slim framework so hopefully you
can see
why this way of structuring your code
and following this
architectural pattern makes your code
very testable
one thing that can make your code very
testable is following the
s of the solid principles the single
responsibility
and this is a really good way of
separating out your code so each layer
has a single responsibility
if you imagine here but it's nice over
here the controller is responsible
for handling http understanding http
rest and json so not
masses of stuff really sitting over here
just got one responsibility and it has
knowledge if one thing passes
it's once it's done its thing it can
pass an isbn
into our business logic layer now
business logic layer
okay it's at this point it's very simple
its responsibility is very low
it is to it knows it has access to
something that
holds a number of books and it can
access those books by the isbn it's been
given
but if this is if we had this business
logic layer
it was responsible for the saving of
books or the creation of books
then the business object layer might
also do some validation
of the data that comes into it
and reject books for saving if they
don't have an offer or they
have too many numbers of pages or
something like that and then
we would have another interface sitting
on this hand side would be would be
book store interface our book repository
would then implement two interfaces
and interface with our database
and again small amount of responsibility
over here sitting here
our repository is just responsible for
taking data and throwing it to its data
store
in this case a postgres database that
shows
that's what that covers why this
way of writing code and separating code
out
makes testing very easy the other thing
it's really
useful for is it means that because
you've got your business object that
sits
in the center and business object would
be
reasonably stable okay then you know my
feature changes
might slightly tweak the business logic
layer
and yes that would have um
cascading changes potentially on the
controller side over here on the left
and possibly on the repository side over
there on the right
it might be more data need to be stored
and more data be returned or something
like that
but if we want to make more sweeping
external architectural changes to our
application
it means we don't have we can do that
very simply without having to affect our
business logic
so for instance if we wanted to make
some changes to the
the front interface the access to our
application
we can easily make these by creating
something else
that can obtain an isbn
and pass it through our interface into
our business logic layer
so for instance we could change the fact
that it is http
rest to be a grpc
implementation or it could be
not grpc we could make it a graphql
service
or we could have the fact that
somehow the communication is not http at
all but it goes over
a queue or kafka topics or something
like that so
this part here
is completely interchangeable without
affecting our business logic layer
and the same can also happen on
the back end of our syst application our
data store
so because of the interface here we
could have all sorts of different
options if we decided we didn't want to
use postgres anymore
we want to switch out completely we can
switch out to
mysql a different sql database
or we could go and say actually we don't
want an sql database at all we want a
nosql database
or a document store we want to go to
using mongodb
or elasticsearch we could quite easily
again swap out our data store our
repository of books
into a completely different technology
and our business logic would not be the
wiser
all it knows is begin it's being given
something that implements the interface
that it needs to obtain books
obviously the example we implemented was
very simple it was just about retrieving
books
but we might want if we look think about
now the creation of books
and we keep with our http rest
implementation so
a book is given to us via json
and we can take that json and the http
request
and construct the data that needs to be
passed over whatever interface we create
here
isbn book creator maybe interface and it
goes into our business logic layer
now business only player would know they
could store
the book that is given into an a
bookstore
interface and that's implemented by a
book repository
now as we remember we could say that our
our validation of the incoming book
would sit within the business logic
layer
and that's quite simple um but
what might happen when we're creating
books we might want to do
more than just store our book
over here on the right hand side we
might want to
notify something of our
book being created so what we might have
is another interface that sits over here
so book creation notifier maybe
and that could be implemented by again a
number of different things we could have
it sending an email to all the managers
that a book has been created
or we could have an implementation that
sends an sms
message or sends a slack notification
to people that a book has been created
okay so that's kind of power the
hexagonal architecture
it's nice it gives you the ability to be
able to swap things out
very simply without having to affect
your business logic
it keeps your business like central to
everything
i hope you enjoyed this walk through the
architectural design
of our api i'll make the changes and add
the interface
we talked about and add this diagram to
the repository
see you again soon
thank you for watching this episode of
testing all the things i hope you
enjoyed it
if you did please rate and review the
video and subscribe
to the channel if you did not and you
have any feedback
please leave a comment in the comment
section of the video
or contact me on twitter at bradley