Commands, events, queries - three types of messages that travel through your application. Some originate from the web, some from the command-line. Your application sends some of them to a database, or a message queue. What is the ideal infrastructure for an application to support this on-going stream of messages? What kind of architectural design fits best? This talk provides answers to these questions: we take the *hexagonal* approach to software architecture. We look at messages, how they cross boundaries and how you can make steady communication lines between your application and other systems, like web browsers, terminals, databases and message queues. You will learn how to separate the technical aspects of these connections from the core behavior of your application by implementing design patterns like the *command bus*, and design principles like *dependency inversion*.

2. HEXAGONAL ARCHITECTURE
Message oriented software design
By Matthias Noback

3. ARCHITECTURE
What's the problem?

4. Nice app

5. Sad app

6. Your brain can't handle it
M V C ?

7. Coupling to frameworks
and libraries

8. How do you start a new
project?
Pick a framework
Install a skeleton project
Remove demo stuff
Auto-generate entities
Auto-generate CRUD controllers
Done
"It's a Symfony project!"

9. That's actually outside in
The boring stuff
The interesting stuff
Symfony
Doctrine
RabbitMQ
Redis
Angular

10. Slow tests
DB
Browser
Message
queue
Key-
value
Filesystem

11. Why do frameworks not solve this for us?
Because they can't ;)

12. Frameworks are about
encapsulation

13. Low-level API
$requestContent = file_get_contents('php://input');
$contentType = $_SERVER['CONTENT_TYPE'];
if ($contentType === 'application/json') {
$data = json_decode($requestContent, true);
} elseif ($contentType === 'application/xml') {
$xml = simplexml_load_string($requestContent);
...
}

14. Nicely hides the details
$data = $serializer->deserialize(
$request->getContent(),
$request->getContentType()
);

15. Low-level API
$stmt = $db->prepare(
'SELECT * FROM Patient p WHERE p.anonymous = ?'
);
$stmt->bindValue(1, true);
$stmt->execute();
$result = $stmt->fetch(PDO::FETCH_ASSOC);
$patient = Patient::reconstituteFromArray($result);

16. Hides a lot of details
$patient = $repository->createQueryBuilder('p')
->where('p.anonymous = true')
->getQuery()
->getResult();

17. What about abstraction?

18. $patient = $repository->createQueryBuilder('p')
->where('p.anonymous = true')
->getQuery()
->getResult();
Concrete
Concrete
Concrete

19. $patients = $repository->anonymousPatients();
Abstract
Nice
DIY

20. Coupling to the delivery
mechanism

21. public function registerPatientAction(Request $request)
{
$patient = new Patient();
$form = $this->createForm(new RegisterPatientForm(), $patient);
$form->handleRequest($request);
if ($form->isValid()) {
$em = $this->getDoctrine()->getManager();
$em->persist($patient);
$em->flush();
return $this->redirect($this->generateUrl('patient_list'));
}
return array(
'form' => $form->createView()
);
}
Request and Form are web-specific
EntityManager is ORM, i.e.
relational DB-specific

22. Reusability: impossible

23. Some
functionality
The web
The CLI

24. Some
functionality
Run
it

25. Lack of intention-revealing code

26. data
data
data

27. public function updateAction(Request $request)
{
$patient = new Patient();
$form = $this->createForm(new PatientType(), $patient);
$form->handleRequest($request);
if ($form->isValid()) {
$em = $this->getDoctrine()->getManager();
$em->persist($patient);
$em->flush();
return $this->redirect($this->generateUrl('patient_list'));
}
return array(
'form' => $form->createView()
);
}
from the HTTP request
copied into an entity
then stored in the database
What exactly
changed?!
And... why?

28. R.A.D.
Rapid Application Development
B.A.D.
B.A.D. Application Development

29. In summary
Coupling to a framework
Coupling to a delivery mechanism (e.g. the web)
Slow tests
Lack of intention in the code

30. THE ESSENCE
of your application

31. The essence
Other things

32. The "heart"?

33. "The heart of software is its ability to solve domain-
related problems for its users.
–Eric Evans, Domain Driven Design
All other features, vital though they may be,
support this basic purpose."

34. What's essential?
Domain model
Interaction with it
Use cases

35. What's not essential?

36. “The database is an implementation detail”
–Cool software architect

37. The core doesn't need to
know about it

38. What about interaction?

39. The core doesn't need to
know about it

40. Infrastructure
The world outside
Web browser
Terminal
Database
Messaging
Filesystem
(E)mail

41. Mmm... layers Layers
allow you to
separate stuff
Layers
allow you to
allocate
things
Layers have
boundaries
Rules for
crossing them

42. Rules about
communication
Actually: rules about dependencies

43. The dependency rule
–Robert Martin, Screaming Architecture

44. What crosses layer
boundaries?
Message

45. Messages
someFunctionCall(
$arguments,
$prepared,
$for,
$the,
$receiver
);
$message = new TypeOfMessage(
$some,
$relevant,
$arguments
);
handle($message);

46. What about the application
boundary?
The app
Message
The world outside

47. How does an app allow
incoming messages at all?
By exposing input ports
Routes
Console commands
A WSDL file for a SOAP API

50. Ports use protocols for
communication
Each port has a language of its own

51. Web (HTTP)

52. Messaging (AMQP)

53. HTTP
Request
Form
Request
Controller
Entity
Value object
W
eb
port
Translate
the
request
Repository

54. Adapters
The translators are called: adapters

55. "Ports and adapters"
Ports: allow for communication to happen
Adapters: translate messages from the world outside
== Hexagonal architecture
Alistair Cockburn

56. An example
Plain HTTP
message
$_POST,
$_GET,
$_SERVER,
Request
POST /patients/ HTTP/1.1
Host: hospital.com
name=Matthias&email=matthiasn
oback@gmail.com
Command
$command = new RegisterPatient(
$request->get('name'),
$request->get('email')
);

57. Command
$command = new RegisterPatient(
$request->get('name'),
$request->get('email')
);
Expresses
intention
Implies changeIndependent
of delivery
mechanism
Only the
message

58. class RegisterPatientHandler
{
public function handle(RegisterPatient $command)
{
$patient = Patient::register(
$command->name(),
$command->email()
);
$this->patientRepository->add($patient);
}
}
Command
Command
handler

59. Command
Command
handler A
Command
bus
Command
handler B
Command
handler C

60. HTTP
Request
Form
Request
Controller
Patient
(entity)
W
eb
port
PatientRepository
RegisterPatient-
Handler
RegisterPatient
(command)
Infrastructure
Application
Dom
ain

61. Change
New entity
(Patient)
Entity-
Manager
UnitOf-
Work
$patient = Patient::register(
$command->name(),
$command->email()
);
$this->patientRepository
->add($patient);
Insert
query (SQL)
INSERT INTO patients SET
name='Matthias',
email='matthiasnoback@gmail
.com';

62. SQL query
EntityManager
UnitOfWork
QueryBuilder
Persistence
port
Prepare
for
persistence
PatientRepository
C
ore
Infrastructure

64. Messaging (AMQP)
Persistence
(MySQL)

65. What often goes wrong:
we violate boundary rules...

66. EntityManager
UnitOfWork
QueryBuilder
PatientRepository
C
ore
Infrastructure

67. RegisterPatient-
Handler
Domain
Infrastructure
Application
Domain
PatientRepository
(uses MySQL)
EntityManager
UnitOfWork
QueryBuilder

68. PatientRepository
(uses MySQL)
Domain
Infrastructure
Application
Domain
RegisterPatient-
Handler

69. Domain
PatientRepository
(interface)
Dependency
inversion
PatientRepository
(uses MySQL)
RegisterPatient-
Handler

70. Domain
InMemory-
PatientRepository
Speedy
alternative
RegisterPatient-
Handler
PatientRepository
(uses MySQL)
PatientRepository
(interface)

71. "A good software architecture allows decisions [...]
to be deferred and delayed."
–Robert Martin, Screaming Architecture

72. IN CONCLUSION
what did we get from all of this?

73. Separation of concerns
Core
Infrastructure

74. Command
Command
Command
handler
Command
handler
Stand-alone use cases
Command
Command
handler
Intention-
revealing
Reusable

75. Infrastructure stand-ins
Regular
implementation
Interface
Stand-in, fast
implementation

76. This is all very much
supportive of...
See also: Modelling by Example
DDD
TDD
BDD
CQRS

77. QUESTIONS?
joind.in/15863
FEEDBACK?