<commit_before>CQRS / Event Sourcing
---------------------

### Commands and Events

It is required to implement `Command` interface in command and `DomainEvent` interface in domain event classes. Since these interfaces extend `ObjectInterface`, it is recommended to extend `Object` in your classes which can be also found in precore library.

All commands store the ID of the aggregate which should be passed to, and the current version of the aggregate. Both parameters are optional. ID should be NULL if the purpose of the command is creating a new aggregate. The version field can be used to define which version of the aggregate the user has operated on. This check must be enforced by the repository. If you don't need it, just leave it when you instantiate the command class.

These values also occur in domain event objects. If a domain event extends `AbstractDomainEvent` and `DoctrineAggregateRootRepository` or `EventSourcingRepository` is being used, ID and version parameters can be omitted during object construction in ARs unless you need to read them in that particular transaction. Both repository implementations automatically set these values during the persisting process.

### Command handling

There are two ways to handle commands:
 1. You create your own command handlers
 2. predaddy forwards all commands directly to the appropriate aggregate

You can mix these ways. Even if your application is configured to use the second approach, you can register your own command handlers in order to override the builtin process.

The CQRS example follows the first, the ES follows the second approach. The read storage synchronization is not part of the examples below.

### CQRS

The following example uses annotation based configuration.

#### Configuration

```php
// you can use any ObservableTransactionManager implementation, see trf4php
$transactionManager = new DoctrineTransactionManager($entityManager);

$trBuses = TransactionalBusesBuilder::create($transactionManager)->build();

$eventBus = $trBuses->eventBus();
$commandBus = $trBuses->commandBus();

// register the command handlers
$commandBus->register(new UserCommandHandler($userRepository));

// register the event handlers
$eventBus->register(new UserEventHandler());
```

Hint: `Repository` interface is required only for {{DirectCommandBus}} and EventSourced aggregates. `$userRepository` in this example can
implement a domain specific, customized `UserRepository` interface.

#### The domain model

```php
class User extends AbstractAggregateRoot
{
    private $id;
    private $email;

    // some missing methods
<commit_msg>fixed markdown<commit_after>CQRS / Event Sourcing
---------------------

### Commands and Events

It is required to implement `Command` interface in command and `DomainEvent` interface in domain event classes. Since these interfaces extend `ObjectInterface`, it is recommended to extend `Object` in your classes which can be also found in precore library.

All commands store the ID of the aggregate which should be passed to, and the current version of the aggregate. Both parameters are optional. ID should be NULL if the purpose of the command is creating a new aggregate. The version field can be used to define which version of the aggregate the user has operated on. This check must be enforced by the repository. If you don't need it, just leave it when you instantiate the command class.

These values also occur in domain event objects. If a domain event extends `AbstractDomainEvent` and `DoctrineAggregateRootRepository` or `EventSourcingRepository` is being used, ID and version parameters can be omitted during object construction in ARs unless you need to read them in that particular transaction. Both repository implementations automatically set these values during the persisting process.

### Command handling

There are two ways to handle commands:
 1. You create your own command handlers
 2. predaddy forwards all commands directly to the appropriate aggregate

You can mix these ways. Even if your application is configured to use the second approach, you can register your own command handlers in order to override the builtin process.

The CQRS example follows the first, the ES follows the second approach. The read storage synchronization is not part of the examples below.

### CQRS

The following example uses annotation based configuration.

#### Configuration

```php
// you can use any ObservableTransactionManager implementation, see trf4php
$transactionManager = new DoctrineTransactionManager($entityManager);

$trBuses = TransactionalBusesBuilder::create($transactionManager)->build();

$eventBus = $trBuses->eventBus();
$commandBus = $trBuses->commandBus();

// register the command handlers
$commandBus->register(new UserCommandHandler($userRepository));

// register the event handlers
$eventBus->register(new UserEventHandler());
```

Hint: `Repository` interface is required only for `DirectCommandBus` and EventSourced aggregates. `$userRepository` in this example can
implement a domain specific, customized `UserRepository` interface.

#### The domain model

```php
class User extends AbstractAggregateRoot
{
    private $id;
    private $email;

    // some missing methods

{'fraction_non_alphanumeric': 0.06492266564827191, 'fraction_numerical': 0.0011456940996753867, 'mean_word_length': 4.952272727272727, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 13, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6318898', 'n_tokens_mistral': 1203, 'n_tokens_neox': 1162, 'n_words': 667}