You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This library is a work in progress. More docs coming soon...
24
+
This library allows you to easily integrate [EventSauce](https://eventsauce.io) with your Laravel application. It takes out the tedious work of having to set up your own message dispatcher and provides an easy API to set up Aggregate Roots, Aggregate Root Repositories, Consumers, and more. It also comes with a range of scaffolding console commands to easily generate the boilerplate needed to get started with an Event Sourced application.
25
+
26
+
Thanks to [Frank de Jonge](https://github.com/frankdejonge) for building and maintaining the main [EventSauce](https://eventsauce.io) project.
27
+
28
+
While already usable, this library is currently still a work in progress. More documentation and features will be added over time. We appreciate pull requests that help extend and improve this project.
23
29
24
30
## Table of Contents
25
31
@@ -29,8 +35,14 @@ This library is a work in progress. More docs coming soon...
@@ -93,50 +105,44 @@ The default table name for your domain messages can be set with the `EVENTSAUCE_
93
105
EVENTSAUCE_TABLE=event_store
94
106
```
95
107
96
-
## Usage
108
+
## Scaffolding
97
109
98
-
### Create aggregate root & repository
110
+
Laravel EventSauce comes with some commands that you can use to scaffold objects and files which you'll need to build your Event Sourced app. These commands take out the tedious work of writing these yourself and instead let you focus on actually writing your domain logic.
99
111
100
-
Use the `php artisan make:aggregate-root YourAggregateRootName` command to generate skeleton classes for your aggregate root.
101
-
Generated classes:
102
-
* Aggregate root
103
-
* Aggregate root repository
104
-
* Aggregate root Id
105
-
* migration
112
+
### Generating Aggregate Roots
106
113
107
-
### Create consumers
114
+
Laravel EventSauce can generate aggregate roots and its related files for you. By using the `make:aggregate-root` command, you can generate the following objects and files:
108
115
109
-
Use the `php artisan make:consumer YourConsumerName` command to generate a consumer.
110
-
Within this consumer you can create methods following the `handle{EventName}` specification.
116
+
- The `AggregateRoot`
117
+
- The `AggregateRootId`
118
+
- The `AggregateRootRepository`
119
+
- The migration file
111
120
112
-
For example, if you want to handle the `UserRegistered` event, the method within the consumer would look like:
113
-
```php
114
-
public function handleUserRegistered(UserRegistered $userRegistered, Message $message)
These are all the files you need to get started with an Aggregate Root.
135
+
136
+
### Generating Consumers
137
+
138
+
Laravel EventSauce can also generate consumers for you. For example, run the `make:consumer` command to generate a `SendEmailConfirmation` process manager:
This will create a class at `App\Domain\SendEmailConfirmation` where you can now define `handle{EventName}` methods to handle events.
145
+
140
146
### Generating Commands & Events
141
147
142
148
EventSauce can generate commands and events for you so you don't need to write these yourself. First, define a `commands_and_events.yml` file which contains your definitions:
@@ -184,7 +190,96 @@ You can now generate commands and events for all repositories that you've added
184
190
php artisan eventsauce:generate
185
191
```
186
192
187
-
For more info on creating events and commands with EventSauce, as well as how to define different types, see: https://eventsauce.io/docs/getting-started/create-events-and-commands
193
+
For more info on creating events and commands with EventSauce, as well as how to define different types, [see the EventSauce documentation](https://eventsauce.io/docs/event-sourcing/create-events-and-commands).
194
+
195
+
## Usage
196
+
197
+
### Aggregate Roots
198
+
199
+
More docs coming soon...
200
+
201
+
### Aggregate Root Repositories
202
+
203
+
More docs coming soon...
204
+
205
+
#### Queue Property
206
+
207
+
You can instruct Laravel to queue all consumers onto a specific queue by setting the `$queue` property:
208
+
209
+
```php
210
+
use App\Domain\SendConfirmationNotification;
211
+
use EventSauce\LaravelEventSauce\AggregateRootRepository;
212
+
213
+
final class RegistrationAggregateRootRepository extends AggregateRootRepository
214
+
{
215
+
protected array $consumers = [
216
+
SendConfirmationNotification::class,
217
+
];
218
+
219
+
protected string $queue = 'registrations';
220
+
}
221
+
```
222
+
223
+
This will force all consumers who have the `ShouldQueue` contract implemented to make use of the `registrations` queue instead of the default queue defined in your `queue.php` config file.
224
+
225
+
### Consumers
226
+
227
+
Consumers are classes that react to events fired from your aggregate roots. There's two types of consumers: projections and process managers. Projections update read models (think updating data in databases, updating reports,...) while process managers handle one-time tasks (think sending emails, triggering builds, ...). For more information on how to use them, check out EventSauce's [Reacting to Events](https://eventsauce.io/docs/reacting-to-events/setup-consumers/) documentation.
228
+
229
+
A `SendEmailConfirmation` process manager, for example, can look like this:
230
+
231
+
```php
232
+
use App\Events\UserWasRegistered;
233
+
use App\Models\User;
234
+
use App\Notifications\NewUserNotification;
235
+
use EventSauce\LaravelEventSauce\Consumer;
236
+
237
+
final class SendConfirmationNotification extends Consumer
238
+
{
239
+
protected function handleUserWasRegistered(UserWasRegistered $event): void
240
+
{
241
+
User::where('email', $event->email())
242
+
->first()
243
+
->notify(new NewUserNotification());
244
+
}
245
+
}
246
+
```
247
+
248
+
Within this consumer you always define methods following the `handle{EventName}` specification.
249
+
250
+
#### Registering Consumers
251
+
252
+
After writing your consumer, you can register them with the `$consumers` property on the related `AggregateRootRepository`:
253
+
254
+
```php
255
+
use App\Domain\SendConfirmationNotification;
256
+
use EventSauce\LaravelEventSauce\AggregateRootRepository;
257
+
258
+
final class RegistrationAggregateRootRepository extends AggregateRootRepository
259
+
{
260
+
protected array $consumers = [
261
+
SendConfirmationNotification::class,
262
+
];
263
+
}
264
+
```
265
+
266
+
The sequence of adding consumers shouldn't matter as the data handling within these consumers should always be treated as independent from each other.
267
+
268
+
#### Queueing Consumers
269
+
270
+
By default, consumers are handled synchronous. To queue a consumer you should implement the `ShouldQueue` contract on your consumer class.
271
+
272
+
```php
273
+
use EventSauce\LaravelEventSauce\Consumer;
274
+
use Illuminate\Contracts\Queue\ShouldQueue;
275
+
276
+
final class SendConfirmationNotification extends Consumer implements ShouldQueue
277
+
{
278
+
...
279
+
}
280
+
```
281
+
282
+
By doing so, we'll instruct Laravel to queue the consumer and let the data handling be done at a later point in time. This is useful to delay long-running data processing.
0 commit comments