PSR-14：事件分发器与监听器深度实践

好的，各位观众老爷们，大家好！我是你们的老朋友，代码界的段子手，bug 的终结者，今天咱们来聊聊一个既重要又有趣的话题：PSR-14：事件分发器与监听器。

想象一下，你正在举办一场盛大的派对 ?，各种活动层出不穷：有人在跳舞，有人在喝酒，有人在聊天。作为派对的主办方，你不可能面面俱到，时刻关注每个人的动向。这个时候，你就需要一个“事件分发器”，它能敏锐地捕捉到派对中发生的各种“事件”，比如“有人开始跳舞了”，然后通知那些对这个事件感兴趣的“监听器”，比如“DJ”和“想加入跳舞的人”。

PSR-14，就是一套关于如何优雅地组织和管理这种“事件-监听”机制的标准。它就像派对的组织章程，让每个人都知道该做什么，该如何配合。

一、 什么是 PSR-14？ 为什么我们需要它？

PSR-14，全称是 PHP Standards Recommendation 14，是 PHP-FIG (PHP Framework Interoperability Group) 制定的一项关于事件分发器的接口标准。简单来说，它定义了一组接口，规定了事件分发器和事件监听器应该如何协同工作。

为什么我们需要 PSR-14 呢？

如果没有统一的标准，每个框架或库都可能使用自己的一套事件机制，导致不同组件之间难以互操作。就像参加一个国际会议，每个人都说自己的方言，那还怎么交流？ ?

PSR-14 的出现，就像制定了一种“世界语”，让不同的框架和库能够使用相同的事件机制进行通信，提高了代码的可移植性和可重用性。

就像乐高积木一样，PSR-14 让我们能够轻松地将不同的组件组合在一起，构建更复杂、更强大的应用。

二、 PSR-14 的核心概念：事件、监听器、分发器

在深入了解 PSR-14 的细节之前，我们先来认识一下它的三个核心概念：

• 事件 (Event)：事件是程序中发生的某种事情的表示。它可以是一个用户登录，一个订单创建，或者任何你认为需要通知其他组件的状态变化。事件通常是一个实现了特定接口的类，包含了事件的相关信息。

• 监听器 (Listener)：监听器是负责处理特定事件的对象。当一个事件被触发时，分发器会通知所有注册的监听器，让它们执行相应的操作。监听器通常是一个实现了特定接口或定义了特定方法的类。

• 分发器 (Dispatcher)：分发器是事件机制的核心，它负责接收事件，并将事件传递给所有注册的监听器。分发器通常是一个实现了特定接口的类，提供了注册监听器和分发事件的方法。

用表格来总结一下：

概念	描述	作用

三、 PSR-14 的接口

PSR-4 定义了四个核心接口，它们是：

• PsrEventDispatcherEventDispatcherInterface：定义了事件分发器的接口。
• PsrEventDispatcherStoppableEventInterface：定义了事件接口，允许事件被停止传播。
• PsrEventDispatcherListenerProviderInterface：定义了监听器提供者的接口，负责根据事件类型返回相应的监听器列表。
• PsrEventDispatcherEventDispatcherInterface：定义了事件分发器的接口，负责将事件分发给相应的监听器。

让我们逐个来看一下这些接口：

1. PsrEventDispatcherEventDispatcherInterface

这个接口定义了事件分发器的核心方法 dispatch()，它接收一个事件作为参数，并将事件分发给所有注册的监听器。

namespace PsrEventDispatcher;

interface EventDispatcherInterface
{
    /**
     * Provides all relevant listeners with an event to process.
     *
     * @param object $event The event to process.
     *
     * @return object The event that was passed, now may have been acted on by listeners.
     */
    public function dispatch(object $event): object;
}

2. PsrEventDispatcherStoppableEventInterface

这个接口定义了一个 isPropagationStopped() 方法，用于判断事件是否已经被停止传播。如果一个监听器调用了事件的 stopPropagation() 方法，后续的监听器将不会再收到该事件。

namespace PsrEventDispatcher;

interface StoppableEventInterface
{
    /**
     * Checks if the event is currently stopped from propagating.
     *
     * @return bool
     */
    public function isPropagationStopped(): bool;
}

3. PsrEventDispatcherListenerProviderInterface

这个接口定义了一个 getListenersForEvent() 方法，用于根据事件类型返回一个可迭代的监听器列表。分发器会使用这个接口来获取需要处理特定事件的监听器。

namespace PsrEventDispatcher;

interface ListenerProviderInterface
{
    /**
     * Returns an iterable (array, iterator, or generator) of callables
     * that are listeners for the given event.
     *
     * @param object $event An event for which to find listeners for.
     *
     * @return iterable<callable> An iterable list of events.
     */
    public function getListenersForEvent(object $event): iterable;
}

4. PsrEventDispatcherEventDispatcherInterface (是的，又出现了这个接口！)

你可能会感到困惑，为什么 EventDispatcherInterface 出现了两次？这是因为 PSR-14 的设计允许分发器和服务容器解耦。第一个 EventDispatcherInterface 定义了最基本的分发事件的功能，而第二个 EventDispatcherInterface 可以被用来定义更高级的分发器，例如可以从服务容器中获取监听器的分发器。

三、 如何使用 PSR-14？一个简单的例子

说了这么多理论，不如来点实际的。我们来创建一个简单的例子，演示如何使用 PSR-14 来实现一个事件分发器。

1. 定义一个事件类：

class UserRegisteredEvent
{
    private $user;

    public function __construct(array $user)
    {
        $this->user = $user;
    }

    public function getUser(): array
    {
        return $this->user;
    }
}

2. 定义一个监听器类：

class SendWelcomeEmailListener
{
    public function __invoke(UserRegisteredEvent $event): void
    {
        // 发送欢迎邮件的逻辑
        $user = $event->getUser();
        echo "发送欢迎邮件给 " . $user['email'] . "n";
    }
}

class LogUserRegistrationListener
{
    public function __invoke(UserRegisteredEvent $event): void
    {
        // 记录用户注册日志的逻辑
        $user = $event->getUser();
        echo "记录用户注册日志，用户ID: " . $user['id'] . "n";
    }
}

3. 创建一个监听器提供者：

use PsrEventDispatcherListenerProviderInterface;

class MyListenerProvider implements ListenerProviderInterface
{
    private $listeners = [];

    public function __construct(array $listeners = [])
    {
        $this->listeners = $listeners;
    }

    public function getListenersForEvent(object $event): iterable
    {
        $eventName = get_class($event);
        if (isset($this->listeners[$eventName])) {
            return $this->listeners[$eventName];
        }

        return [];
    }

    public function addListener(string $eventName, callable $listener): void
    {
        if (!isset($this->listeners[$eventName])) {
            $this->listeners[$eventName] = [];
        }
        $this->listeners[$eventName][] = $listener;
    }
}

4. 创建一个事件分发器：

use PsrEventDispatcherEventDispatcherInterface;
use PsrEventDispatcherListenerProviderInterface;

class MyEventDispatcher implements EventDispatcherInterface
{
    private $listenerProvider;

    public function __construct(ListenerProviderInterface $listenerProvider)
    {
        $this->listenerProvider = $listenerProvider;
    }

    public function dispatch(object $event): object
    {
        foreach ($this->listenerProvider->getListenersForEvent($event) as $listener) {
            $listener($event);
        }

        return $event;
    }
}

5. 使用事件分发器：

// 创建监听器提供者
$listenerProvider = new MyListenerProvider();
$listenerProvider->addListener(UserRegisteredEvent::class, new SendWelcomeEmailListener());
$listenerProvider->addListener(UserRegisteredEvent::class, new LogUserRegistrationListener());

// 创建事件分发器
$dispatcher = new MyEventDispatcher($listenerProvider);

// 创建一个用户注册事件
$user = ['id' => 123, 'email' => '[email protected]'];
$event = new UserRegisteredEvent($user);

// 分发事件
$dispatcher->dispatch($event);

运行这段代码，你将会看到以下输出：

发送欢迎邮件给 [email protected]
记录用户注册日志，用户ID: 123

恭喜你！你已经成功地使用 PSR-14 实现了一个简单的事件分发器。 ?

四、 PSR-14 的高级应用：中间件、优先级、停止传播

除了基本的事件分发功能，PSR-14 还支持一些高级特性，例如：

• 中间件 (Middleware)：可以将监听器作为中间件来处理事件，在事件传播的过程中对事件进行修改或增强。
• 优先级 (Priority)：可以为监听器设置优先级，控制监听器的执行顺序。
• 停止传播 (Stop Propagation)：可以阻止事件继续传播给后续的监听器。

1. 中间件

中间件的概念在 Web 开发中非常常见，它可以用来在请求到达最终处理程序之前或之后执行一些通用的操作，例如身份验证、日志记录等。

在 PSR-14 中，我们可以将监听器作为中间件来处理事件。例如，我们可以创建一个监听器，用于在事件传播的过程中对事件进行修改：

class AddTimestampListener
{
    public function __invoke(MyEvent $event): void
    {
        $event->timestamp = time();
    }
}

2. 优先级

有时候，我们需要控制监听器的执行顺序。例如，我们可能希望先执行一个验证监听器，再执行一个处理监听器。

PSR-14 本身没有提供直接设置监听器优先级的功能，但是我们可以通过自定义监听器提供者来实现这个功能。例如，我们可以使用一个数组来存储监听器，并根据优先级对数组进行排序：

class MyListenerProvider implements ListenerProviderInterface
{
    private $listeners = [];

    public function addListener(string $eventName, callable $listener, int $priority = 0): void
    {
        if (!isset($this->listeners[$eventName])) {
            $this->listeners[$eventName] = [];
        }
        $this->listeners[$eventName][] = ['listener' => $listener, 'priority' => $priority];
        usort($this->listeners[$eventName], function ($a, $b) {
            return $b['priority'] <=> $a['priority']; // 降序排列
        });
    }

    public function getListenersForEvent(object $event): iterable
    {
        $eventName = get_class($event);
        if (isset($this->listeners[$eventName])) {
            foreach ($this->listeners[$eventName] as $listenerData) {
                yield $listenerData['listener'];
            }
        }
    }
}

3. 停止传播

有时候，我们希望某个监听器能够阻止事件继续传播给后续的监听器。例如，如果一个验证监听器发现事件不合法，就可以停止传播，防止后续的处理程序执行。

为了实现停止传播的功能，我们需要让事件类实现 StoppableEventInterface 接口，并提供一个 stopPropagation() 方法：

use PsrEventDispatcherStoppableEventInterface;

class MyEvent implements StoppableEventInterface
{
    private $isPropagationStopped = false;

    public function stopPropagation(): void
    {
        $this->isPropagationStopped = true;
    }

    public function isPropagationStopped(): bool
    {
        return $this->isPropagationStopped;
    }
}

然后，在分发器中，我们需要检查事件是否已经被停止传播：

class MyEventDispatcher implements EventDispatcherInterface
{
    private $listenerProvider;

    public function dispatch(object $event): object
    {
        foreach ($this->listenerProvider->getListenersForEvent($event) as $listener) {
            if ($event instanceof StoppableEventInterface && $event->isPropagationStopped()) {
                break; // 停止传播
            }
            $listener($event);
        }

        return $event;
    }
}

五、 PSR-14 的优缺点

优点：

• 标准化：PSR-14 提供了一套标准的事件分发器接口，使得不同的框架和库可以互操作。
• 解耦：事件分发器将事件的触发者和处理者解耦，提高了代码的灵活性和可维护性。
• 扩展性：可以通过添加新的监听器来扩展系统的功能，而不需要修改现有的代码。
• 灵活性：支持中间件、优先级、停止传播等高级特性，可以满足不同的应用场景需求。

缺点：

• 复杂性：相比于简单的回调函数，事件分发器需要更多的代码和配置。
• 性能：事件分发器可能会带来一定的性能开销，特别是当有大量的监听器时。
• 学习曲线：需要一定的学习成本才能掌握 PSR-14 的使用方法。

六、 总结

PSR-14 是一套强大的事件分发器接口标准，它可以帮助我们构建更灵活、更可维护、更可扩展的应用。虽然它有一定的复杂性和性能开销，但是在很多情况下，它的优点 outweigh 它的缺点。

希望今天的讲解能够帮助你更好地理解和使用 PSR-14。记住，编程的乐趣在于不断学习和探索，让我们一起在代码的世界里自由翱翔吧！ ?

最后，送给大家一句名言：Talk is cheap, show me the code! ?‍?