README

事件发射器是对象，通过整数或字符串标识事件。当对象发出事件时，它会调用一组已注册在该事件标识符上的回调。

每个事件发射器都必须实现 Icicle\EventEmitter\EventEmitterInterface。类应通过扩展 Icicle\EventEmitter\EventEmitter 或在类定义中使用特质 Icicle\EventEmitter\EventEmitterTrait 来实现此接口。

此实现与其他事件发射器库不同，它确保特定回调只能为特定事件标识符注册一次。尝试注册已注册的回调是无效操作。

事件标识符也严格强制执行，以帮助调试。事件发射器对象必须初始化它们希望发出的事件标识符。如果尝试在不存在的事件上注册回调，将抛出 Icicle\EventEmitter\Exception\InvalidEventException。

use Icicle\EventEmitter\EventEmitterInterface;
use Icicle\EventEmitter\EventEmitterTrait;

class ExampleEventEmitter implements EventEmitterInterface
{
    use EventEmitterTrait;

    public function __construct()
    {
        $this->createEvent('action'); // Creates event with 'action' identifier.
    }

    public function doAction($arg1, $arg2)
    {
        $this->emit('action', $arg1, $arg2); // Emits an event with 'action' identifier.
    }
}

上面的示例类实现了 Icicle\EventEmitter\EventEmitterInterface，因此它可以向一组监听器发出事件。以下示例演示了如何向此类的一个实例添加监听器以及发出事件的行为。此类将在以下其他几个示例中使用。

$emitter = new ExampleEventEmitter();

// Registers a callback to be called each time the event is emitted.
$emitter->on('action', function ($arg1, $arg2) {
    echo "Argument 1 value: {$arg1}\n";
    echo "Argument 2 value: {$arg2}\n";
});

// Registers a callback to be called only the next time the event is emitted.
$emitter->once('action', function ($arg1, $arg2) {
    $result = $arg1 * $arg2;
    echo "Result: {$result}\n";
});

$emitter->doAction(404, 3.14159); // Calls both functions above.
$emitter->doAction(200, 2.71828); // Calls only the first function.

• PHP 5.4+

建议使用 Composer 包管理器进行安装。（有关安装和使用 Composer 的信息，请参阅 Composer 安装指南。）

运行以下命令以在项目中使用此库

composer require icicleio/event-emitter

您还可以手动编辑 composer.json，将此库作为项目需求添加。

// composer.json
{
    "require": {
        "icicleio/event-emitter": "~1"
    }
}

文档

• EventEmitterInterface
  • addListener() - 添加事件监听器。
  • on() - 每次发出事件时添加事件监听器。
  • once() - 只在下次发出事件时添加事件监听器。
  • removeListener() - 删除事件监听器。
  • off() - 删除事件监听器。
  • removeAllListeners() - 从标识符或所有标识符中删除所有监听器。
  • getListeners() - 返回事件标识符的监听器集合。
  • getListenerCount() - 返回事件标识符上的监听器数量。
  • emits() - 确定对象是否发出具有给定标识符的事件。
  • getEventList() - 返回对象发出的事件标识符列表。
• EventEmitterTrait
  • createEvent() - 创建事件标识符。
  • emit() - 发出事件。
• 从事件创建Promise
• 在事件上执行协程

以下语法描述了对象实例方法的原型

ReturnType $classOrInterfaceName->methodName(ArgumentType $arg1, ArgumentType $arg2)

以下语法描述了静态方法的原型

ReturnType ClassName::methodName(ArgumentType $arg1, ArgumentType $arg2)

为了记录用作方法参数或返回类型的回调函数的预期原型，以下文档使用了以下语法来表示callable类型

callable<ReturnType (ArgumentType $arg1, ArgumentType $arg2)>

EventEmitterInterface

Icicle\EventEmitter\EventEmitterInterface是一个接口，任何类都可以实现以发射事件。实现此接口的最简单方法是使用类定义中的Icicle\EventEmitter\EventEmitterTrait，或者使类扩展Icicle\EventEmitter\EventEmitter。

$this $eventEmitterInterface->addListener(
    string|int $event,
    callable<void (mixed ...$args)> $callback,
    bool $once = false
)

向事件标识符$event添加由$callback定义的事件监听器。如果$once为true，监听器将仅在下次事件发射时被调用，否则监听器将在每次事件发射时被调用。如果$event提供的标识符不存在，将抛出Icicle\EventEmitter\Exception\InvalidEventException。

$this $eventEmitterInterface->on(string|int $event, callable<void (mixed ...$args)> $callback)

向事件标识符$event添加由$callback定义的事件监听器，该监听器将在每次事件发射时被调用。此方法与调用addListener()并将$once设置为false相同。如果$event提供的标识符不存在，将抛出Icicle\EventEmitter\Exception\InvalidEventException。

$this $eventEmitterInterface->once(string|int $event, callable<void (mixed ...$args)> $callback)

向事件标识符$event添加由$callback定义的事件监听器，该监听器将仅在下次事件发射时被调用。此方法与调用addListener()并将$once设置为true相同。如果$event提供的标识符不存在，将抛出Icicle\EventEmitter\Exception\InvalidEventException。

$this $eventEmitterInterface->removeListener(string|int $event, callable<void (mixed ...$args)> $callback)

从事件标识符$event中删除由$callback定义的事件监听器。此方法将删除监听器，无论监听器是在每次事件发射时调用，还是在下次事件发射时调用。如果没有在给定的事件上注册监听器，则此函数为空操作。如果$event提供的标识符不存在，将抛出Icicle\EventEmitter\Exception\InvalidEventException。

$this $eventEmitterInterface->off(string|int $event, callable<void (mixed ...$args)> $callback)

此方法是removeListener()的别名。

$this $eventEmitterInterface->removeAllListeners(string|int|null $event = null)

从事件标识符中删除所有监听器，如果$event为null，则从所有事件中删除所有监听器。如果$event提供的标识符不存在，将抛出Icicle\EventEmitter\Exception\InvalidEventException。

callable[] $eventEmitterInterface->getListeners(string|int $event)

返回事件标识符上的所有监听器，作为可调用对象数组。如果$event提供的标识符不存在，将抛出Icicle\EventEmitter\Exception\InvalidEventException。

int $eventEmitterInterface->getListenerCount(string|int $event)

获取事件标识符上的监听器数量。如果$event提供的标识符不存在，将抛出Icicle\EventEmitter\Exception\InvalidEventException。

bool $eventEmitterInterface->emits(string|int $event)

确定对象是否使用$event提供的标识符发射事件。

array $eventEmitterInterface->getEventList()

返回对象发射的事件标识符数组。

EventEmitterTrait

Icicle\EventEmitter\EventEmitterTrait 是一个简单的实现 Icicle\EventEmitter\EventEmitterInterface 接口的方式。这个特性定义了受保护的方法，这些方法不是 Icicle\EventEmitter\EventEmitterInterface 的一部分，用于创建和发射事件。

$this $eventEmitterTrait->create(string|int $identifier)

此方法创建一个事件标识符，以便可以发射事件并添加监听器。通常，此方法会在构造函数中调用，以初始化一系列事件标识符。

bool $eventEmitterTrait->emit(string|int $event, mixed ...$args)

发射一个具有事件标识符 $event 的事件，并将此函数提供的其余参数作为每个事件监听器的参数传递。如果调用任何事件监听器，则该方法返回 true，如果没有调用，则返回 false。如果 $event 给出的标识符不存在，将抛出 Icicle\EventEmitter\Exception\InvalidEventException 异常。

从事件创建 Promise

Promise 是 Icicle 的一个组件，这是一个用于在 PHP 中编写异步代码的库。Promise 作为异步操作未来值的占位符。

可以使用静态方法 Icicle\Promise\Promise::promisify() 创建一个函数，该函数返回一个 Promise，在事件发射器发射事件时解决。

use Icicle\Loop\Loop;
use Icicle\Promise\Promise;

// Include ExampleEventEmitter class definition from above.

$emitter = new ExampleEventEmitter();

// Use once() since promises can only be resolved once.
$promisor = Promise::promisify([$emitter, 'once'], 1);

$promise = $promisor('action'); // Promise for 'action' event.

$promise = $promise->then(function (array $args) {
    list($arg1, $arg2) = $args;
    echo "Argument 1 value: {$arg1}\n";
    echo "Argument 2 value: {$arg2}\n";
});

// Simulates an event being emitted while running the loop.
Loop::schedule(function () use ($emitter) {
    $emitter->doAction(404, 3.14159); // Fulfills promise.
});

Loop::run();

有关使用 Promise 的更多信息，请参阅 Promise API 文档。

在事件上执行协程

协程 使用生成器创建协作式协程。它们是 Icicle 的一个组件，这是一个用于在 PHP 中编写异步代码的库。

事件发射器可用于在每次发射事件时创建和执行协程。静态方法 Icicle\Coroutine\Coroutine::async() 返回一个函数，可以用作事件发射器上的事件监听器。

use Icicle\Coroutine\Coroutine;
use Icicle\Loop\Loop;

// Include ExampleEventEmitter class definition from above.

$emitter = new ExampleEventEmitter();

$emitter->on('action', Coroutine::async(function ($arg1, $arg2) {
    $result = (yield $arg1 * $arg2);
    echo "Result: {$result}\n";
}));

// Simulates an event being emitted while running the loop.
Loop::schedule(function () use ($emitter) {
    $emitter->doAction(404, 3.14159); // Creates and runs coroutine.
});

Loop::run();

有关使用协程的更多信息，请参阅 协程 API 文档。