README

Laravel EventSauce

👋 该项目目前正在寻找新的维护者。

此库允许您轻松地将 EventSauce 集成到您的 Laravel 应用程序中。它消除了设置自己的消息派发器的繁琐工作，并提供了一个简单的 API 来设置 聚合根、聚合根存储库、消费者 等。它还提供了一系列脚手架控制台命令，以轻松生成启动事件源应用程序所需的样板代码。

⚠️ 虽然已经可以使用，但此库目前仍在开发中。随着时间的推移，将添加更多文档和功能。我们感谢有助于扩展和改进此项目的 pull requests。

要求

• PHP 7.4 或更高版本
• Laravel 8.0 或更高版本

安装

在安装新包之前，始终清除您的配置缓存是个好主意

php artisan config:clear

您可以通过 Composer 安装此库。这还将安装 主 EventSauce 库。

composer require eventsauce/laravel-eventsauce

配置

您可以使用以下命令发布配置文件

php artisan vendor:publish --tag="eventsauce-config"

迁移

默认的 domain_messages 表将通过库的服务提供者加载并迁移

php artisan migrate

您也可以使用以下命令发布和修改它

php artisan vendor:publish --tag="eventsauce-migrations"

默认连接

可以通过设置 EVENTSAUCE_CONNECTION 环境变量来修改默认数据库连接

EVENTSAUCE_CONNECTION=mysql

默认表

您可以使用 EVENTSAUCE_TABLE 环境变量设置您的领域消息的默认表名

EVENTSAUCE_TABLE=event_store

脚手架

Laravel EventSauce 附带了一些命令，您可以使用这些命令来生成构建您的领域事件应用程序所需的对象和文件。这些命令消除了编写这些内容的繁琐工作，并让您专注于编写实际的领域逻辑。

生成聚合根

Laravel EventSauce 可以为您生成 聚合根 及其相关文件。通过使用 make:aggregate-root 命令，您可以生成以下对象和文件

• AggregateRoot
• AggregateRootId
• AggregateRootRepository
• 迁移文件

要为“注册”过程生成这些文件，请运行以下命令

php artisan make:aggregate-root Domain/Registration

这将生成以下文件

• App\Domain\Registration
• App\Domain\RegistrationId
• App\Domain\RegistrationRepository
• database/migrations/xxxx_xx_xx_create_registration_domain_messages_table.php

这些都是您开始使用 https://github.com/EventSaucePHP/LaravelEventSauce 所需的所有文件。

生成消费者

Laravel EventSauce 还可以为您生成 消费者。例如，运行 make:consumer 命令以生成 SendEmailConfirmation 流程管理器

php artisan make:consumer Domain/SendEmailConfirmation

这将在 App\Domain\SendEmailConfirmation 创建一个类，您现在可以在此定义 handle{EventName} 方法来处理事件。

生成命令和事件

EventSauce 可以为您生成命令和事件，您无需自己编写。首先，定义一个 commands_and_events.yml 文件，其中包含您的定义

namespace: App\Domain\Registration
commands:
  ConfirmUser:
    fields:
      identifier: RegistrationAggregateRootId
      user_id: int
events:
  UserWasConfirmed:
    fields:
      identifier: RegistrationAggregateRootId
      user_id: int

然后在 AggregateRootRepository 中定义输入和输出文件

final class RegistrationAggregateRootRepository extends AggregateRootRepository
{
    ...

    /** @var string */
    protected static $inputFile = __DIR__.'/commands_and_events.yml';

    /** @var string */
    protected static $outputFile = __DIR__.'/commands_and_events.php';
}

并在您的 eventsauce.php 配置文件中注册 AggregateRootRepository

'repositories' => [
    App\Domain\Registration\RegistrationAggregateRootRepository::class,
],

现在，您可以通过运行以下命令生成所有已添加存储库的命令和事件

php artisan eventsauce:generate

有关使用 EventSauce 创建事件和命令的更多信息，以及如何定义不同类型，请参阅EventSauce 文档。

用法

聚合根

更多文档即将推出...

聚合根存储库

更多文档即将推出...

队列属性

您可以通过设置 $queue 属性来指示 Laravel 将所有消费者放入特定的队列

use App\Domain\SendConfirmationNotification;
use EventSauce\LaravelEventSauce\AggregateRootRepository;

final class RegistrationAggregateRootRepository extends AggregateRootRepository
{
    protected array $consumers = [
        SendConfirmationNotification::class,
    ];
    
    protected string $queue = 'registrations';
}

这将强制所有实现了 ShouldQueue 协议的消费者使用 registrations 队列而不是您的 queue.php 配置文件中定义的默认队列。

消费者

消费者是响应从聚合根触发事件的类。有两种类型的消费者：投影和处理管理器。投影更新读取模型（例如在数据库中更新数据、更新报告等），而处理管理器处理一次性任务（例如发送电子邮件、触发构建等）。有关如何使用它们的更多信息，请参阅 EventSauce 的事件响应文档。

例如，一个 SendEmailConfirmation 处理管理器可以看起来像这样

use App\Events\UserWasRegistered;
use App\Models\User;
use App\Notifications\NewUserNotification;
use EventSauce\LaravelEventSauce\Consumer;

final class SendConfirmationNotification extends Consumer
{
    protected function handleUserWasRegistered(UserWasRegistered $event): void
    {
        User::where('email', $event->email())
            ->first()
            ->notify(new NewUserNotification());
    }
}

在此消费者中，您始终定义遵循 handle{EventName} 规范的方法。

注册消费者

编写您的消费者后，您可以通过在相关的 AggregateRootRepository 上的 $consumers 属性中注册它们

use App\Domain\SendConfirmationNotification;
use EventSauce\LaravelEventSauce\AggregateRootRepository;

final class RegistrationAggregateRootRepository extends AggregateRootRepository
{
    protected array $consumers = [
        SendConfirmationNotification::class,
    ];
}

添加消费者的顺序不应很重要，因为这些消费者中的数据处理应始终被视为相互独立。

队列消费者

默认情况下，消费者以同步方式处理。要队列消费者，您应该在您的消费者类上实现 ShouldQueue 协议。

use EventSauce\LaravelEventSauce\Consumer;
use Illuminate\Contracts\Queue\ShouldQueue;

final class SendConfirmationNotification extends Consumer implements ShouldQueue
{
    ...
}

通过这样做，我们将指示 Laravel 队列消费者，并允许在稍后的时间处理数据处理。这对于延迟长时间运行的数据处理很有用。

变更日志

请在此存储库中查看所有最近更改的变更日志。

维护者

该项目目前正在寻找新的维护者。

致谢

感谢 Frank De Jonge 构建 EventSauce。感谢 Freek Van der Herten 和 Spatie 的 Laravel EventSauce 库，它们为该软件包的一些功能提供了灵感。

许可

Laravel EventSauce 是开源软件，许可协议为 MIT 许可。