Crafting beautiful software

Source: fideloper.com/hexagonal-
architecture

Let’s prevent an exponential
growth in technical debt

Problems with the PHP
industry standard

industry standard
Lack of intention

industry standard
Lack of intention
Heavy coupling

industry standard
Lack of intention
Heavy coupling
Anemic domain models

$ whoami
Jorn Oomen
Freelance PHP Web developer
Good weather cyclist
linkedin.com/in/jornoomen
@jornoomen

Let’s craft beautiful software

Requirement
A user needs to be registered

class User
{
private $id;
private $name;
private $email;
// Getters and setters
}
Model

public function registerAction(Request $request) : Response
{
$form = $this->formFactory->create(UserType::class);
$form->handleRequest($request);
if ($form->isValid()) {
/** @var User $user */
$user = $form->getData();
$this->em->persist($user);
$this->em->flush();
}
return new Response(/**/);
}
Controller

Requirement
A user has to have a name and an email

public function __construct(string $name, string $email)
{
$this->setName($name);
$this->setEmail($email);
}
private function setName(string $name)
{
if ('' === $name) {
throw new InvalidArgumentException('Name is required');
}
$this->name = $name;
}
private function setEmail(string $email)
{
if ('' === $email) {
throw new InvalidArgumentException('E-mail is required');
}
$this->email = $email;
}
Model

Requirement
A user needs a valid email

private function setEmail(string $email)
{
if ('' === $email) {
}
if (!filter_var($email, FILTER_VALIDATE_EMAIL)) {
throw new InvalidArgumentException('E-mail is invalid');
}
}
Model

It’s becoming messy already
A case for the value object

final class EmailAddress
{
}
Value object

{
public function __construct(string $email)
{
}
}
Value object

{
{
if ('' === $email) {
}
}
}
Value object

{
{
if ('' === $email) {
}
}
}
}
Value object

{
{
if ('' === $email) {
}
}
}
public function toString() : string;
}
Value object

{
{
if ('' === $email) {
}
}
}
public function equals(EmailAddress $email) : bool;
}
Value object

class User
{
public function __construct(EmailAddress $email, string $name)
{
$this->setEmail($email);
$this->setName($name);
}
//[..]
}
Model

// Before
Controller

// Before
//After
$data = $form->getData();
$user = new User(new EmailAddress($data['email']), $data['name'])
Controller

Recap
Email validation is handled by the value object

Recap
Name and email are required constructor arguments

Recap
Name and email are required constructor arguments
The User model is always in a valid state

if (!empty($user->getEmail())) {
if (filter_var($user->getEmail(), FILTER_VALIDATE_EMAIL)) {
//Send an email
}
}
Before

“A small simple object, like money or a date range, whose
equality isn't based on identity.”
Martin Fowler

Value objects
Small logical concepts
Contain no identity
Are immutable
Equality is based on value

$fiveEur = MoneyMoney::EUR(500);
$tenEur = $fiveEur->add($fiveEur);
echo $fiveEur->getAmount(); // outputs 500
echo $tenEur->getAmount(); // outputs 1000
Immutability example

We have now enforced our
business rules

Some observation
We are now directly using doctrine for persistence

Some observation
We are now directly using doctrine for persistence
A change of persistence would mean changing
every class where we save or retrieve the user

{
// [..]
$user = new User(new EmailAddress($data['email']), $data['name']);
$this->em>flush();
}
Controller

Let’s move the persistence
out of the controller

class DoctrineUserRepository
{
//[..]
public function save(User $user)
{
$this->em->flush();
}
}
Repository

{
// [..]
$user = new User(new EmailAddress($data['email']), $data['name']);
$this->userRepository->save($user);
}
Controller

Doctrine is great but we
don’t want to marry it
A switch of persistence can be done by changing a
single class

Requirement
A user needs to receive a registration confirmation

public function registerAction(Request $request)
{
// [..]
$content = $this->renderTemplate();
$message = $this->createMailMessage($content, $user);
$this->mailer->send($message);
}
}
Controller

The controller is getting too
FAT

Let’s move the notifying
out of the controller

class UserRegisteredNotifier
{
//[..]
public function notify(string $email, string $name)
{
$content = $this->renderTemplate();
$message = $this->createMailMessage($content, $email, $name);
$this->mailer->send($message);
}
}
Notifier

public function registerAction(Request $request)
{
// [..]
$this->userRegisteredNotifier->notify($data['email'], $data['name']);
}
}
Controller

Requirement
User registration has to be available through an API

public function registerAction(Request $request) : JsonResponse
{
}
Controller

{
$data = $this->getRequestData($request);
}
Controller

{
$user = new User(new EmailAddress($data['email'], $data['name']);
}
Controller

{
}
Controller

{
return new JsonResponse(['id' => $user->getId()]);
}
Controller

Controller

Introducing the command
pattern

class RegisterUser // A command always has a clear intention
{
public function __construct(string $email, string $name)
{
$this->name = $name;
}
// Getters
}
Command

class RegisterUserHandler
{
//[..]
public function handle(RegisterUser $registerUser)
{
}
}
Command handler

{
//[..]
{
$user = new User(new EmailAddress($registerUser->getEmail()), $registerUser->getName());
}
}
Command handler

{
//[..]
{
}
}
Command handler

{
//[..]
{
$this->userRegisteredNotifier->notify($registerUser->getEmail()), $registerUser->getName());
}
}
Command handler

{
// [..]
$data = $form->getData();
$this->registerUserHandler->handle(
new RegisterUser($data['email'], $data['name'])
);
}
}
Controller

{
// [..]
);
return new JsonResponse([]);
}
Controller

Commands
Only contain a message

Commands
Have a clear intention (explicit)

Commands
Are immutable

Commands
Are immutable
Command handlers never return a value

A command bus is a generic command handler
Commands and the
command bus

Commands and the
command bus
It receives a command and routes it to the handler

Commands and the
command bus
It receives a command and routes it to the handler
It provides the ability to add middleware

A great command bus
implementation
github.com/SimpleBus/MessageBus

public function handle($command, callable $next)
{
$this->logger->log($this->level, 'Start, [command => $command]);
$next($command);
$this->logger->log($this->level, 'Finished', [command' => $command]);
}
Logging middleware example

public function handle($command, callable $next)
{
if ($this->canBeDelayed($command)) {
$this->commandQueue->add($command);
} else {
$next($command);
}
}
Queueing middleware example

//Before
);
//After
$this->commandBus->handle(
);
Controller

The command bus
Provides the ability to add middleware

The command bus
Now logs every command for us

The command bus
Now logs every command for us
Allows queueing of (slow) commands

The handler is still dealing
with secondary concerns

class UserIsRegistered // An event tells us what has happened
{
public function __construct(int $userId, string $emailAddress, string $name)
{}
// Getters
}
Event

class User implements ContainsRecordedMessages
{
//[..]
}
Model

{
use PrivateMessageRecorderCapabilities;
//[..]
}
Model

{
public static function register(EmailAddress $email, string $name) : self
{
}
//[..]
}
Model

{
{
$user = new self($email, $name);
}
//[..]
}
Model

{
{
$user->record(new UserIsRegistered($user->id, (string) $email, $name));
}
//[..]
}
Model

{
{
$user->record(new UserIsRegistered($user->id, (string) $email, $name));
return $user;
}
//[..]
}
Model

{
//[..]
{
// save user
foreach ($user->recordedMessages() as $event) {
$this->eventBus->handle($event);
}
}
}
Command handler

class NotifyUserWhenUserIsRegistered
{
//[..]
public function handle(UserIsRegistered $userIsRegistered)
{
$this->userRegisteredNotifier->notify($userIsRegistered->getEmail(), $userIsRegistered->getName());
}
}
Event listener

Domain events
Are in past tense

Domain events
Are in past tense
Are always immutable

Domain events
Are in past tense
Are always immutable
Can have zero or more listeners

So we are pretty happy now
Controller creates simple command
Mailing doesn’t clutter our code

We now have a rich user model
It contains data

It contains data
It contains validation

It contains data
It contains validation
It contains behaviour

“Objects hide their data behind abstractions and expose
functions that operate on that data. Data structure expose
their data and have no meaningful functions.”
Robert C. Martin (uncle Bob)

We are still coupled to
doctrine for our persistence

class DoctrineUserRepository
{
//[..]
public function save(User $user)
{
$this->em->flush();
}
public function find(int $userId) : User
{
return $this->em->find(User::class, $userId);
}
}
Repository

We shouldn’t depend on
any persistence
implementation

We shouldn’t depend on
any persistence
implementation
A case for the dependency inversion principle

interface UserRepository
{
public function save(User $user);
public function find(int $userId) : User;
}
Repository

class DoctrineUserRepository implements UserRepositoryInterface
{
//[..]
}
Repository

{
public function __construct(UserRepositoryInterface $userRepository, MessageBus $eventBus)
{
//[..]
}
}
Command handler

DI: Dependency injection
Our situation

IoC: Inversion of control
Our situation

IoC: Inversion of control
DIP: Dependency inversion principle
Our situation

Tests - InMemoryUserRepository
Decoupling provides options

Development - MysqlUserRepository

Development - MysqlUserRepository
Production - WebserviceUserRepository

Be clear about your exceptions
Some note

interface UserRepository
{
/**
* @throws UserNotFoundException
* @throws ServiceUnavailableException
*/
//[..]
}
Repository

{
/**
* @throws DoctrineDBALExceptionConnectionException
*/
}
class InMemoryUserRepository implements UserRepository
{
/**
* @throws RedisException
*/
}
Repository

Don’t do this
{
/**
* @throws DoctrineDBALExceptionConnectionException
*/
}
class InMemoryUserRepository implements UserRepository
{
/**
* @throws RedisException
*/
}
Repository

{
public function find(UserId $userId) : User
{
try {
if ($user = $this->findById($userId)) {
return $user;
}
} catch (ConnectionException $e) {
throw ServiceUnavailableException::withOriginalException($e);
}
throw UserNotFoundException::withId($userId);
}
}
Normalize your exceptions
Repository

{
public function find(UserId $userId) : User
{
try {
if ($user = $this->findById($userId)) {
return $user;
}
} catch (ConnectionException $e) {
throw ServiceUnavailableException::withOriginalException($e);
}
throw UserNotFoundException::withId($userId);
}
}
Normalize your exceptions
The implementor now only has to worry about the exceptions
defined in the interface
Repository

The promise of a repository interface is now clear, simple and
implementation independent

src/UserBundle/
├── Command
├── Controller
├── Entity
├── Event
├── Form
├── Notifier
├── Repository
└── ValueObject
Let’s look at the structure

src/UserBundle/
├── Command
├── Entity
├── Event
├── Form
├── Notifier
Let’s look at the structure
The domain, infrastructure and application are all
mixed in the bundle

src/UserBundle/
├── Command
│ ├── RegisterUser.php
│ └── RegisterUserHandler.php
│ ├── RegisterUserApiController.php
│ └── RegisterUserController.php
├── Entity
│ ├── User.php
│ └── UserRepository.php
├── Event
│ └── UserIsRegistered.php
├── Form
│ └── UserType.php
├── Notifier
│ ├── NotifyUserWhenUserIsRegistered.php
│ └── UserRegisteredNotifier.php
│ └── DoctrineUserRepository.php
├── Resources/config/doctrine
│ └── User.orm.yml
└── EmailAddress.php

src/UserBundle/
├── Command
├── Entity
├── Event
├── Form
├── Notifier
Domain

src/UserBundle/
├── Command
├── Entity
├── Event
├── Form
├── Notifier
Domain
Infrastructure

src/UserBundle/
├── Command
├── Entity
├── Event
├── Form
├── Notifier
Domain
Infrastructure
Application

src/UserBundle/
├── Command
├── Entity
├── Event
├── Form
├── Notifier
src/User/
└── DomainModel
└── User
├── EmailAddress.php
├── User.php
├── UserIsRegistered.php
└── UserRepository.php

src/UserBundle/
├── Command
├── Entity
├── Event
├── Form
├── Notifier
src/User/
├── DomainModel
│ └── User
│ ├── EmailAddress.php
│ ├── UserIsRegistered.php
└── Infrastructure
├── Messaging/UserRegisteredNotifier.php
└── Persistence
├── User
└── config/doctrine
└── User.User.orm.yml

src/UserBundle/
├── Command
├── Entity
├── Event
├── Form
├── Notifier
src/User/
├── DomainModel
│ └── User
│ ├── EmailAddress.php
│ ├── UserIsRegistered.php
├── Infrastructure
│ ├── Messaging/UserRegisteredNotifier.php
│ └── Persistence
│ ├── User
│ │ └── DoctrineUserRepository.php
│ └── config/doctrine
│ └── User.User.orm.yml
└── Application
├── Command
├── Form/UserType.php
└── Messaging/NotifyUserWhenUserIsRegistered.php

We are looking pretty good
Application, domain and infrastructural concerns are
separated.

Let’s test this awesome
software

public function can_register_user()
{
}

{
$this->registerUserHandler->handle(new RegisterUser('aart.staartjes@hotmail.com', 'Aart Staartjes'));
}

{
$user = $this->inMemoryUserRepository->find(1);
}

{
$user = $this->inMemoryUserRepository->find(1);
$this->assertInstanceOf(User::class, $user);
$this->assertEquals(new EmailAddress('aart.staartjes@hotmail.com'), $user->getEmail());
$this->assertSame('Aart Staartjes', $user->getName());
$this->assertInstanceOf(UserIsRegistered::class, $this->eventBusMock->getRaisedEvents()[0]);
}

There was 1 error:
1) UserDomainModelUserRegisterUserTest::can_register_user
UserDomainModelExceptionUserNotFoundException: User with id 1 not found
FAILURES!
Tests: 1, Assertions: 0, Errors: 1.

We rely on the magic of the
persistence layer

User provides identity - The email
Unique identity options

Persistence mechanism generates identity - Auto increment

Persistence mechanism generates identity - Auto increment
Application generates identity - UUID

Let’s remove the magic
By implementing an up front id generation strategy

{
public static function register(UuidInterface $id, EmailAddress $email, string $name) : self
{
$user = new self($id, $email, $name);
$user->record(new UserIsRegistered((string) $id, (string) $email, $name));
return $user;
}
//[..]
}
Model

{
$id = Uuid::uuid4();
}

{
new RegisterUser((string) $id, 'aart.staartjes@hotmail.com', 'Aart Staartjes')
}

{
);
}

{
);
$user = $this->inMemoryUserRepository->find($id);
// Assertions
}

phpunit --bootstrap=vendor/autoload.php test/
PHPUnit 5.3.2 by Sebastian Bergmann and contributors.
. 1 / 1 (100%)
Time: 125 ms, Memory: 8.00Mb
OK (1 test, 4 assertions)

But a Uuid can still be any id
We can be more explicit

final class UserId // Simply wrapper of Uuid
{
public static function createNew() : self
/**
* @throws InvalidArgumentException
*/
public static function fromString(string $id) : self
}
Value object

Now we know exactly what
we are talking about

{
$id = UserId::createNew();
);
$user = $this->inMemoryUserRepository->find($id);
// Assertions
}

phpunit --bootstrap vendor/autoload.php src/JO/User/
.
OK (1 test, 4 assertions)

Let’s test our value objects

public function can_not_create_invalid_user_id()
{
$this->expectException(InvalidArgumentException::class);
UserId::fromString('invalid format');
}

public function can_not_create_invalid_email_address()
{
new EmailAddress('invalid format');
}

... 3 / 3 (100%)

{
}
{
}

$this->commandBus>handle(
new RegisterUser('invalid id', 'invalid email', $name = '’)
);

We still have limited control
over our exceptions
Useful domain exceptions can give us more control

namespace UserDomainModelException;
abstract class DomainException extends DomainException {}

namespace UserDomainModelException;
abstract class DomainException extends DomainException {}
class InvalidEmailAddressException extends DomainException {}
class InvalidUserIdException extends DomainException {}
class NoEmailAddressProvidedException extends DomainException {}

try {
);
} catch (DomainModelExceptionInvalidEmailAddressException $e) {
// Show invalid email error
}

try {
);
} catch (DomainModelExceptionInvalidEmailAddressException $e) {
// Show invalid email error
} catch (DomainModelExceptionDomainException $e) {
// Some domain exception occurred
}

{
$this->expectException(InvalidUserIdException::class);
}
{
$this->expectException(InvalidEmailAddressProvidedException::class);
}

... 3 / 3 (100%)
OK (3 tests, 6 assertions)

Intention revealing code
What did we learn?

Testable code
What did we learn?

Testable code
Preventing the big ball of mud
What did we learn?

Testable code
Anemic domain models (anti pattern)
What did we learn?

Testable code
Value objects
What did we learn?

Testable code
Value objects
Decoupling from the framework
What did we learn?

What did we learn?
Writing fast tests (mocked environment)

What did we learn?
Commands

What did we learn?
Commands
Domain Events

What did we learn?
Commands
Domain Events
Dependency inversion principle

What did we learn?
Commands
Domain Events
Up front id generation strategy

What did we learn?
Commands
Domain Events
Creating powerful domain exceptions

What did we learn?
Commands
Domain Events
Creating powerful domain exceptions
Liskov substitution principle

We wrote intention revealing code. Separated the

domain, infrastructure and application. Created

abstractions to improve testability and flexibility. We

used commands to communicate with a unified
voice. Created domain events to allow for extension

without cluttering the existing code. We end up with

clear, maintainable and beautiful software.

clear, maintainable and beautiful software.
That keeps us excited!

Used resources
http://www.slideshare.net/matthiasnoback/hexagonal-architecture-messageoriented-software-design
https://www.youtube.com/watch?v=Eg6m6mU0fH0
https://www.youtube.com/watch?v=mQsQ6QZ4dGg
https://kacper.gunia.me/blog/ddd-building-blocks-in-php-value-object
http://williamdurand.fr/2013/12/16/enforcing-data-encapsulation-with-symfony-forms/
http://simplebus.github.io/MessageBus/
http://php-and-symfony.matthiasnoback.nl/2014/06/don-t-use-annotations-in-your-controllers/
http://alistair.cockburn.us/Hexagonal+architecture
http://www.slideshare.net/cakper/2014-0407-php-spec-the-only-design-tool-you-need-4developers/117-
enablesRefactoring

Crafting beautiful software

Recommended

Recommended

More Related Content

What's hot

What's hot (20)

Similar to Crafting beautiful software

Similar to Crafting beautiful software (20)

Recently uploaded

Recently uploaded (20)

Crafting beautiful software

Editor's Notes