Appearance

事件开发文档 ​

ECShopX 采用 Laravel/Lumen Event + Listener 模式，按 Bundle 分域注册。事件注册入口：bootstrap/app.php 中各 Bundle 的 EventServiceProvider。

1. 关键路径 ​

路径说明
src/{Bundle}/Events/*.php事件定义
src/{Bundle}/Listeners/*.php监听器实现
src/{Bundle}/Providers/EventServiceProvider.php$listen 映射
src/EspierBundle/Listeners/BaseListeners.phpListener 基类

2. 已注册 EventServiceProvider 的 Bundle ​

（见 bootstrap/app.php）

Bundle典型事件域
OrdersBundle订单支付、取消、流程日志
MembersBundle会员注册成功
GoodsBundle商品创建、编辑、库存
DistributionBundle店铺创建
ThirdPartyBundle交易同步、退款
SystemLinkBundleERP 链路
WechatBundle微信相关
ReservationBundle预约完成
CompanysBundle企业/操作员
OpenapiBundle开放 API
EspierBundle平台级
HfPayBundle汇付分账
YoushuBundle有数统计

3. 核心事件示例 ​

订单域（OrdersBundle） ​

Event触发时机典型 Listener
TradeFinishEvent支付完成统计、分润、短信、ERP、发票、企微等
NormalOrderAddEvent创单供应商拆单
NormalOrderCancelEvent取消名额释放、库存回滚等
OrderProcessLogEvent流程节点流程日志

会员域（MembersBundle） ​

Event说明
CreateMemberSuccessEvent注册成功 → 促销、积分、通知

商品域（GoodsBundle） ​

Event说明
ItemCreateEvent新建商品
ItemEditEvent编辑商品、同步分销店

4. 新增与注册步骤 ​

4.1 定义 Event ​

src/{YourBundle}/Events/YourEvent.php
php
namespace YourBundle\Events;

class YourEvent
{
    public function __construct(public array $payload) {}
}

4.2 实现 Listener ​

src/{YourBundle}/Listeners/YourListener.php

可继承 EspierBundle\Listeners\BaseListeners。

php
namespace YourBundle\Listeners;

class YourListener
{
    public function handle(YourEvent $event): void
    {
        // 业务逻辑
    }
}

4.3 注册映射 ​

在 src/{YourBundle}/Providers/EventServiceProvider.php：

php
protected $listen = [
    \YourBundle\Events\YourEvent::class => [
        \YourBundle\Listeners\YourListener::class,
    ],
];

4.4 注册 Provider ​

在 bootstrap/app.php 中确保：

php
$app->register(YourBundle\Providers\EventServiceProvider::class);

4.5 派发事件 ​

php
event(new \YourBundle\Events\YourEvent($data));
// 或
\Event::dispatch(new \YourBundle\Events\YourEvent($data));

5. 参考范例（订单支付完成） ​

项路径
Eventsrc/OrdersBundle/Events/TradeFinishEvent.php
Listenersrc/OrdersBundle/Listeners/TradeFinishSmsNotify.php
注册src/OrdersBundle/Providers/EventServiceProvider.php
派发TradeService / 支付回调逻辑中 event(new TradeFinishEvent(...))

6. 注意事项 ​

  1. Listener 内避免长阻塞；重逻辑应 dispatch(new XxxJob(...)) 入队。
  2. 跨 Bundle 监听：在目标 Bundle 的 EventServiceProvider 中注册即可。
  3. 新增 Bundle 时勿忘记注册 EventServiceProvider。