Simple [C]ommand [Q]uery [R]esponsibility [S]egregation and [E]vent [S]ourcing library.
READMEThis library is to show another way to tackle CQRS and event sourcing, but is not considered as suitable for real production projects. For this purpose rather use Prooph toolbox or Nette extension for Prooph toolbox. It supports snapshoting, read model projections, is easy to make event replaying and is way more flexible.
This PHP CQRS EventSourcing library is based on Benjamin Eberlei's LiteCQRS for php which was not maintained for quite a long time. This fork is bringing it back to life, but it is not to be considered as a stable library, since there may be BC breaks in the near future.
Main differences are:
- Minimal required version of PHP is 7.0, it will be 7.1 soon.
- Commanding - to the CommandBus you can register only implementations of ComandHandler (has only handle method). The reason behind this is to enforce explicitness in naming and structuring conventions. When you see XxxCommand and you need to see the implementation, you know there should be XxxCommandHandler implemented somewhere.
Small naming-convention based CQRS library for PHP (loosely based on LiteCQRS for C#) that relies on the MessageBus, Command, EventSourcing and Domain Event patterns.
CQS is Command-Query-Separation: A paradigm where read methods never change state and write methods never return data. Build on top, CQRS suggests the separation of read- from write-model and uses the DomainEvent pattern to notify the read model about changes in the write model.
Glow uses the command pattern and a central message bus service that
finds the corresponding handler to execute a command. A command must implement
Glow\Commanding\Command. It should be a plain DTO (data transfer object)
with just some properties describing it (imutability is encouraged).
After this object is passed as a parameter into the CommandBus'
handle(Command $command) method, CommandBus finds a proper CommandHandler and invokes the
same method with the same parameter on it. Enforced convention is that there
has to be XxxCommandHandler (implementing CommandHandler) for every XxxCommand.
During the execution of a command, domain events can be triggered. These are
again just simple classes with some properties and they can optionally implement
An event queue knows what domain events have been triggered during a command and then publishes them to an event message bus, where many listeners can listen to them.
- Each XxxCommand DTO is mapped to XxxCommandHandler when XxxCommand implements Command and XxxCommandHandler implements CommandHandler.
- Domain Events are applied to Event Handlers "Event Class Shortname" => "onEventClassShortname". An event listener is registered only if this matches.
- Domain Events are applied on Entities/Aggregate Roots "Event Class Shortname" => "applyEventClassShortname"
- You can optionally extend the
DefaultDomainEventwhich has a constructor that maps its array input to properties and throws an exception if an unknown property is passed.
- There is also a
DefaultCommandwith the same semantics as
DefaultDomainEvent. Extending this is not required.
GreetingCommand implements Commandmaps to the
handle(GreetingCommand $command)method on the registered GreetingCommandHandler implementing CommandHandler.
HelloWorld\GreetedEventis passed to all event handlers that have a method
HelloWorld\Events\Greetedis passed to all event handlers that have a method
HelloWorld\GreetedEventis delegated to
applyGreeted($event)when created on the aggregate root
Install with Composer:
composer require lidskasila/glow
These are the steps that a command regularly takes through the Glow stack during execution:
- You push commands into a
CommandBus. Commands are simple objects implementing
Commandcreated by you.
CommandBuschecks for a handler that can execute your command. Every command has exactly one handler.
- The command handler changes state of the domain model. It does so by
creating events (that represent a state change) and passing them to the
DomainEventProvider::raise()method of your domain objects.
- When the command is completed, the command bus will check all objects in the identity map for events.
- All found events will be passed to the
- The EventMessageBus dispatches all events to observing event handlers.
- Event Handlers can create new commands again using the
Command and Event handler execution can be wrapped in handlers that manage transactions. Event handling is always triggered outside of any command transaction. If the command fails with any exception all events created by the command are forgotten/ignored. No event handlers will be triggered in this case.
In the case of InMemory CommandBus and EventMessageBus Glow makes sure that the execution of commands and event handlers is never nested, but in sequential linearized order. This prevents independent transactions for each command from affecting each other.
#TODO following is not updated
See examples/ for some examples:
example1.phpshows usage of the Command- and EventMessageBus with one domain object
example2_event.phpshows direct usage of the EventMessageBus inside a command
example3_sequential_commands.phpdemonstrates how commands are processed sequentially.
tictactoe.phpimplements a tic tac toe game with CQRS.
example1.phpimplemented within the scope of a Symfony2 project.
- In Memory Command Handlers, no event publishing/observing
<?php $userService = new UserService(); $commandBus = new DirectCommandBus() $commandBus->register('MyApp\ChangeEmailCommand', $userService);
- In Memory Commands and Events Handlers
Glow\EventProviderInterface instances to trigger domain events.
<?php // 1. Setup the Library with InMemory Handlers $messageBus = new InMemoryEventMessageBus(); $identityMap = new SimpleIdentityMap(); $queue = new EventProviderQueue($identityMap); $commandBus = new DirectCommandBus(array( new EventMessageHandlerFactory($messageBus, $queue) )); // 2. Register a command service and an event handler $userService = new UserService($identityMap); $commandBus->register('MyApp\ChangeEmailCommand', $userService); $someEventHandler = new MyEventHandler(); $messageBus->register($someEventHandler);
- In Memory Commands + Custom Event Queue
Glow knows about triggered events by asking
Provide your own implementation to be independent of
your domain objects having to implement
<?php $messageBus = new InMemoryEventMessageBus(); $queue = new MyCustomEventQueue(); $commandBus = new DirectCommandBus(array( new EventMessageHandlerFactory($messageBus, $queue) ));
- Create a command object that receives all the necessary input values. Use public properties and extend
- Add a new method with the name of the command to any of your services (command handler)
- Register the command handler to handle the given command on the CommandBus.
- Have your entities implement
- Use protected method
raise(DomainEvent $event)or apply(DomainEvent $event)`` to attach events to your aggregate root objects.
That is all there is for simple use-cases.
If your command triggers events that listeners check for, you should:
- Create a domain specific event class. Use public properties to simplify.
- Create a event handler(s) or add method(s) to existing event handler(s).
While it seems "complicated" to create commands and events for every use-case. These objects are really dumb and only contain public properties. Using your IDE or editor functionality you can easily generate them in no time. In turn, they will make your code very explicit.
There are two ways to publish events to the outside world.
DomainEventProvider#raise(DomainEvent $event)is the simple one, it emits an event and does nothing more.
AggregateRoot#apply(DomainEvent $event)requires you to add a method
apply$eventName($event)that can be used to replay events on objects. This is used to replay an object from events.
If you don't use event sourcing then you are fine just using
raise() and ignoring
The EventMessageBus prevents exceptions from bubbling up. To allow some debugging of failed event handler
execution there is a special event "EventExecutionFailed" that you can listen to. You will get passed
an instance of
Glow\Bus\EventExecutionFailed with properties
$event to allow analysing failures in your application.
You should implement your own
CommandBus or extend the existing to wire the whole process together
exactly as you need it to work.
Inside symfony you can use Glow by registering services with
lite_cqrs.command_handler or the
lite_cqrs.event_handler tag. These
services are then autodiscovered for commands and events.
Command- and Event-Handlers are lazily loaded from the Symfony Dependency Injection Container.
To enable the bundle put the following in your Kernel:
You can enable/disable the bundle by adding the following to your config.yml:
Please refer to the SymfonyExample.md document for a full demonstration of using Glow from within a Symfony2 project.
A plugin that logs the execution of every command and handler using Monolog. It includes the type and name of the message, its parameters as json and if its execution succeeded or failed.
The Monolog integration into Symfony registers a specific channel
which you can configure differently from the default channels in Symfony. See
for more information.