- Introduction
- Project Setup and first test
- Follow the test
- Booking a lesson using events - an overview
- Extracting CQRS components and refactoring the write model
- Persisting events to an event store
- Listing to events and updating read models
- Improving the read model with relationships
- Loading lessons
- Protecting against invariants
- Generating UUIDs
- "Enforcing" Read Model immutability
This post runs through the basics of creating an event sourced/CQRS system with PHP and Laravel. It assumes familiarity with the command bus design pattern and events (publishing events to an array of listeners). Laracasts have you covered if you need to brush up! It also assumes you have some familiarity with the concept of CQRS. If not, I highly recommend two talks: Practical Event Sourcing by Mathias Verraes and CQRS and Event sourcing by Greg Young.
Please don't use this code for your projects! It's a learning platform to uncover the ideas behind CQRS. It's not robust, it's poorly tested and I'm rarely coding to interfaces which will make it harder to swap parts out. A much better example of a CQRS package you can use is Qandidate Lab's Broadway. It's decoupled, clean code but some of the abstractions make it hard to follow if you've never seen an event sourced system.
Finally, this code is coupled to Laravel's Events and Command Bus. I wanted to see what the code would look like with Laravel (it's my framework of choice for smaller agency projects), but looking back I should have created my own implementations. I hope people will be able to follow along, even if they don't use a framework.
The code is on github: https://github.com/scazz/cqrs-tutorial.git, and the tutorial takes you through the code, commit by commit. Hopefully this will make it easy to follow along!
We will be building the start of a booking system for a surf school. It will allow clients to book onto lessons. Our domain rules for this process are:
- A lesson must have at least one client
- No more than 3 clients per lesson
One of the exciting things about CQRS and Event Sourced systems is creating read models specific to each metric you require from the system. You can find examples projecting read models into ElasticSearch and Greg Young has a DSL for Complex Event Processing built into his event store. But, in an effort to reduce the learning curve, our read projection will be a standard SQL database you would use with Eloquent. We will end up with one table for lessons, and one for clients.
Event Sourcing also gives you the ability to process the events off-line. This post will keep as close to "traditional" development models as possible (again to reduce complexity) and our read projections will be updated in real time, as soon as events are persisted into the event store.
Following along?
$> git checkout c60aa7b
Start a new laravel 5 project
$> laravel new cqrs-tutorial
And the first thing we need is a test. We're just going to stick with an integration test to assert that booking a lesson for a client results in that lesson being created in our Eloquent model.
tests/CQRSTest.php
```
use Illuminate\Foundation\Bus\DispatchesCommands;
class CQRSTest extends TestCase {
use DispatchesCommands;
/**
* Assert the BookLesson Command creates a lesson in our read projection
* @return void
*/
public function testFiringEventUpdatesReadModel() { $testLessonId = '123e4567-e89b-12d3-a456-426655440000'; $clientName = "George"; $lessonId = new LessonId($testLessonId);
$command = new BookLesson($lessonId, $clientName);
$this->dispatch($command);
$this->assertNotNull(Lesson::find($testLessonId));
$this->assertEquals( Lesson::find($testLessonId)->clientName, $clientName );
}
}
We provide the ID for our new lesson up front, create a command to book a new lesson and tell Laravel to dispatch the command. We want a new entry to be created in the lessons table, which we can read with an Eloquent model. We will be needing a database, so fill in your .env file as required.
Each event logged to our event store is attached to an Aggregate Root (which we will just call an Entity - the abstraction for learning purposes just adds to the confusion). This ID is a universally unique ID. The event store doesn't care if the event is to be applied to a Lesson or a Client, it just knows it's attached to an ID.
<a name="missing-classes"></a>
### Follow the test ###
<blockquote><code class="hljs">Following along?
$> git checkout 284da0f9
</code></blockquote>
Being driven by our test errors, we can create our missing classes. First we create a LessonId class, followed by the BookLesson command (don't worry about the handle method yet, just keep following the test). The Lesson class is a read model outside of the Lesson namespace - it will only ever be a read model - no domain logic will reside in here. Finally, we have to create a migration for the lessons table.
I'm using an assertion library to keep the code clean. You can grab it with:
<blockquote><code class="hljs">$> composer require beberlei/assert
</code></blockquote>
<div class="code-snippit-filename">app/School/Lesson/LessonId.php</div>
app/School/Lesson/Commands/BookLesson.php
```
lessonId = $lessonId;
}
/**
* @return LessonId
*/
public function getLessonId()
{
return $this->lessonId;
}
public function handle()
{
//TODO: handle dispatched command
}
}
```
app/School/ReadModels/Lesson.php
```
database/migrations/createlessontable.php
```
string('id'); // uuid
});
}
/**
* Reverse the migrations.
*
* @return void
*/
public function down()
{
Schema::drop('lesson');
}
}
```
### Booking a lesson using events - an overview ###
Following along?
$> git checkout bd4e01a4
app/School/Lesson/Lesson.php
```
openLesson( $lessonId );
$lesson->bookClient( $clientName );
return $lesson;
}
private function openLesson( LessonId $lessonId ) {
/* here we would check any invarients - but we don't have any to protect, so we can just generate the events */
$event = new LessonWasOpened( $lessonId);
$this->applyLessonWasOpened($event);
$this->uncommittedEvents[] = DomainEventMessage::recordNow( $this->lessonId, $event );
}
private function applyLessonWasOpened( $event ) {
$this->lessonId = $event->lessonId;
$this->numberOfClients = 0;
}
public function bookClient( $clientName ) {
if ($this->numberOfClients >= 3) {
throw new Exception("Too many clients");
}
$event = new ClientBookedOntoLesson( $this->lessonId, $clientName);
$this->applyClientBookedOntoLesson( $event );
$this->uncommittedEvents[] = DomainEventMessage::recordNow( $this->lessonId, $event );
}
/*
* Here, we only keep track of the number of clients -
* this is the only thing the write model cares about
*
* If a domain rules was "no clients can have the same name",
* we would need to keep a track of client names.
*/
private function applyClientBookedOntoLesson( $event ) {
$this->numberOfClients++;
}
}
```
### Extracting CQRS components and refactoring the write model ###
Following along?
$> git checkout 9c148fe
app/CQRS/EventSourcedEntity.php
```
handle( $event );
$this->uncommittedEvents[] = DomainEventMessage::recordNow( $this->getEntityId(), $event );
}
public function getUncommittedDomainEvents()
{
return $this->uncommittedEvents;
}
private function handle( $event ) {
$method_name = $this->getApplyMethodName($event);
if (! method_exists($this, $method_name)) {
return;
}
$this->$method_name($event);
}
private function getApplyMethodName($event) {
$className = get_class($event);
$classParts = explode('\\', $className);
$methodName = end($classParts);
return 'apply'. $methodName;
}
}
```
To get the code to run, we need to add a DomainEventMessage class, which is just a simple DTO:
app/CQRS/DomainEventMessage.php
```
id = $id;
$this->event = $event;
$this->dateTime = $dateTime;
}
public static function recordNow($id, $event ) {
return new DomainEventMessage($id, $event, new DateTime());
}
/**
* @return DateTime
*/
public function getDateTime()
{
return $this->dateTime;
}
/**
* @return mixed
*/
public function getEvent()
{
return $this->event;
}
/**
* @return mixed
*/
public function getId()
{
return $this->id;
}
}
```
### Persisting events to an event store ###
Following along?
$> git checkout 92ee32e
app/School/Lesson/Events/LessonWasOpened.php
```
class LessonWasOpened implements SerializableEvent {
public function serialize()
{
return array( 'lessonId'=> (string) $this->getLessonId() );
}
}
```
Create the LessonRepository. We can refactor and extract generic CQRS stuff later.
app/School/Lesson/LessonRepository.php
```
eventStoreRepository =
new EloquentEventStoreRepository( new EventSerializer() );
}
public function save(Lesson $lesson) {
/** @var DomainEventMessage $domainEventMessage */
foreach( $lesson->getUncommittedDomainEvents() as $domainEventMessage ) {
$this->eventStoreRepository->append(
$domainEventMessage->getId(),
$domainEventMessage->getEvent(),
$domainEventMessage->getRecordedAt()
);
Event::fire($domainEventMessage->getEvent());
}
}
}
```
If you run the integration test again, then check the domain_events SQL table, you should see two events in the database.
### Listing to events and updating read models ###
Following along?
$> git checkout e202739
app/School/Lesson/Projections/LessonProjector.php
```
id = $event->getLessonId();
$lessonProjection->save();
}
public function applyClientBookedOntoLesson( ClientBookedOntoLesson $event ) {
$lessonProjection = LessonProjection::find($event->getLessonId());
$lessonProjection->clientName = $event->getClientName();
$lessonProjection->save();
}
public function subscribe(Dispatcher $events) {
$fullClassName = self::class;
$events->listen(
LessonWasOpened::class,
$fullClassName.'@applyLessonWasOpened'
);
$events->listen(
ClientBookedOntoLesson::class, $fullClassName.'@applyClientBookedOntoLesson'
);
}
}
```
app/School/Lesson/Projections/LessonProjection.php
```
app/Providers/EventServiceProvider.php
```
public function boot(DispatcherContract $events)
{
parent::boot($events);
Event::subscribe( new LessonProjector() );
}
```
If you run the test, you'll see that there is an SQL error:
Unknown column 'clientName' in 'field list'
Following along?
$> git checkout 3a70e75e
tests/CQRSTest.php
```
public function testFiringEventUpdatesReadModel()
{
$testLessonId = '123e4567-e89b-12d3-a456-426655440000';
$clientName = "George";
$lessonId = new LessonId($testLessonId);
$command = new BookLesson($lessonId, $clientName);
$this->dispatch($command);
$lesson = Lesson::find($testLessonId);
$this->assertEquals( $lesson->id, $testLessonId );
$client = $lesson->clients()->first();
$this->assertEquals($client->name, $clientName);
}
```
The updated projector, read model and migrations are on github - it's basic laravel stuff. It highlights how easy it is to change your read models. Everything up to the event store remains the same.
Smoke testing is something we get for free with an event sourced system - if we change our read model projector, we have a listen of every event that has ever happened in our system. We replay these events using the new projector, check for exceptions and compare the output with the old projections. If the system has been live for some time, we will have a comprehensive list of events to test our projectors with.
### Loading lessons ###
Following along?
$> git checkout a10888e
tests/CQRSTest.php
```
public function testLoadingWriteModel()
{
$testLessonId = '123e4567-e89b-12d3-a456-426655440001';
$lessonId = new LessonId($testLessonId);
$clientName_1 = "George";
$clientName_2 = "Fred";
$command = new BookLesson($lessonId, $clientName_1);
$this->dispatch($command);
$command = new BookClientOntoLesson($lessonId, $clientName_2);
$this->dispatch($command);
$lesson = Lesson::find($testLessonId);
$this->assertClientCollectionContains($lesson->clients, $clientName_1);
$this->assertClientCollectionContains($lesson->clients, $clientName_2);
}
private function assertClientCollectionContains(Collection $clients, $nameToFind)
{
$attributeArray = [];
foreach( $clients as $object ) {
$attributeArray[] = $object->name;
}
$this->assertTrue( in_array($nameToFind, $attributeArray), "Could not find client named: ${nameToFind}" );
}
```
We need a way for our write model to "load" an entity that already has events applying to it in the event store. We can achieve this by replaying every event which refers to the entity's UUID.
The basic process is:
1. Get all relevant event messages from the event store
2. For each message, recreate the appropriate event
3. Create a new entity write model and replay each event
At the moment, our tests throws exceptions so we start by creating the required BookClientOntoLesson command, using the BookLesson command as a template. The handle method will look like:
app/School/Lesson/Commands/BookClientOntoLesson.php
```
public function handle(LessonRepository $repository) {
/** @var Lesson $lesson */
$lesson = $repository->load($this->lessonId);
$lesson->addClient($this->clientName);
$repository->save($lesson);
}
```
Add the load event in the lesson repository:
app/School/Lesson/LessonRepository.php
```
public function load(LessonId $id) {
$events = $this->eventStoreRepository->load($id);
$lesson = new Lesson();
$lesson->initializeState($events);
return $lesson;
}
```
The repository's load function returns an array recreated events. It does this by first finding the event messages in the event store, then delegating to the Serializer to turn each event message into an event.
The Serializer created the messages from events, so we need to add a deserialize() method to reverse the process. You'll remember the Serializer delegated to each event to manage the serialzing of event data (eg client name). We'll do the same when reversing the process so our SerializableEvent interface should be updated with a deserialize() method.
Let's take a look at the code to explain things better.
First the EventStoreRepository's load function:
app/CQRS/EloquentEventStoreRepository.php
```
public function load($uuid) {
$eventMessages = EloquentEventStoreModel::where('uuid', $uuid)->get();
$events = [];
foreach($eventMessages as $eventMessage) {
/* We serialized our event into an event_payload, so we need to deserialize before returning */
$events[] =
$this->eventSerializer->deserialize(
json_decode($eventMessage->event_payload)
);
}
return $events;
}
```
With the corresponding deserialize function in the eventSerializer:
app/CQRS/Serializer/EventSerializer.php
```
public function deserialize( $serializedEvent ) {
$eventClass = $serializedEvent->class;
$eventPayload = $serializedEvent->payload;
return $eventClass::deserialize($eventPayload);
}
```
Finally, the static factory deserialize() method in LessonWasOpened (we need to add this method to every event)
app/School/Lesson/Events/LessonWasOpened.php
```
public static function deserialize($data) {
$lessonId = new LessonId($data->lessonId);
return new self($lessonId);
}
```
Now we have an array of all previous events, we just replay them against our Entity write model to initialize state:
app/CQRS/EventSourcedEntity.php
```
public function initializeState($events) {
foreach( $events as $event ) {
$this->handle($event);
}
}
```
And rerun our test - we're back to Green!
### Protecting against invariants ###
Following along?
$> git checkout eabe2cf
tests/CQRSTest.php
```
public function testMoreThan3ClientsCannotbeAddedToALesson() {
$testLessonId = '123e4567-e89b-12d3-a456-426655440002';
$lessonId = new LessonId($testLessonId);
$this->dispatch( new BookLesson($lessonId, "bob") );
$this->dispatch( new BookClientOntoLesson($lessonId, "george") );
$this->dispatch( new BookClientOntoLesson($lessonId, "fred") );
$this->setExpectedException( TooManyClientsAddedToLesson::class );
$this->dispatch( new BookClientOntoLesson($lessonId, "emma") );
}
```
You'll notice that we only need a lessonId - this test re-initializing the lesson's state with each command.
### Generating UUIDs ###
Following along?
$> git checkout eeeac9e
$> composer require ramsey/uuid
tests/CQRSTest.php
```
public function testEntityCreationWithUUIDGenerator() {
$lessonId = new LessonId( (string) \Rhumsaa\Uuid\Uuid::uuid1() );
$this->dispatch( new BookLesson($lessonId, "bob") );
$this->assertInstanceOf( Lesson::class, Lesson::find( (string) $lessonId) );
}
```
### "Enforcing" Read Model immutability ###
Following along?
$> git checkout 5e62320
app/CQRS/ReadModelImmutableModel.php
```
Is that Async?