How to persist custom events with PES

[codeliner]

Provide an example and may improve the ES API to ease usage of custom domain events.

[codeliner]

See prooph/event-sourcing#3

[codeliner]

#37 is somewhat related. The two requirements can be combined.

The ES adapters should only handle plain arrays (serialized domain events).
The Stream class should provide the possibility to attach a Serializer/Unserializer.
The EventStore should inject a serializer when handling the Stream. Default serializer will be a ProophMessageSerializer but custom implementations are allowed (interface required).
Stream::getEventsAsArrays will use the serializer and Stream::getEvents will use the unserializer (can of course be the same instance)
Generators will work great for the two methods.
An adapter can then f.e. wrap a PDOStatement with an own iterator to convert the table row into the event array structure and then pass the iterator to a new Stream instance. The Stream is returned to the event store and the store uses setter injection to add the serializer and unserializer. Now the outside world can iterate over Stream::getEvents and will get a ready to use custom domain event.
Just keep in mind that a PDOStatement does not provide a rewind functionality in all cases so we have to workaround this (maybe by caching the event arrays in the stream?).
A stream interface is maybe also a good idea so we could allow usage of custom stream implementations. One stream would implement a cache and another one not (f.e. to use the pass through mechanism when upcasting or replaying events).

[codeliner]

@mvriel: prooph/event-store 5.x will have better support for custom domain events. I wrote down a rough idea (see last comment) but now have to think about it in detail to come up with something that can be implemented.

[codeliner]

With prooph/common v3.3 a new Prooph\Common\Messaging\Message interface was introduced.
The event store and all adapters will be adjusted to type hint only this interface in the future. So custom domain event implementations need to implement the interface but no longer extend a abstract class. That is the best compromise we can make between duck typing (working with plain PHP arrays only) and a strong coupling (extend an abstract class).

[codeliner]

Removed BC break label because Prooph\Common\Messaging\DomainMessage implements the new interface and can therefor be handled by the event store without adjustments.

[codeliner]

Closed with #52