README

本规范的目的是提供一个通用接口，用于异步操作返回的简单占位符对象。这允许来自不同供应商的库和组件创建协程，而不管使用的占位符实现如何。本规范不旨在取代可能链式调用的Promise实现。相反，通用接口可以由Promise实现扩展。

本文档中的“必须”、“禁止”、“必需”、“应当”、“不应当”、“推荐”、“可能”和“可选”等关键词应按RFC 2119中所述解释。

Promise表示异步操作最终结果。与Promise的交互通过其when()方法进行，该方法注册一个回调以接收Promise的最终值或失败原因。

Promise是异步编程的基本原语。它应该尽可能轻量，因为任何成本都会显著增加。

本规范定义了可互操作的协程的绝对最低要求，这可以通过PHP的生成器实现。

本规范不涉及如何创建、成功或失败Promise，因为只需要消费Promise以实现互操作性。

有关进一步的设计解释和说明，请参阅元文档。

术语

Promise是一个实现AsyncInterop\Promise并符合本规范的对象。
值是任何合法的PHP值（包括null），但不能是AsyncInterop\Promise的实例。
错误是任何可以使用throw语句抛出的值。
原因是一个错误，表明Promise失败的原因。

状态

Promise必须处于三种状态之一：pending、succeeded、failed。

不得更改是指对象在引用情况下是不可变的，而不是对象本身不可变。

一旦Promise成功或失败，它就被解决。

消费

Promise必须实现AsyncInterop\Promise并提供一个when()方法来访问其值或原因。

<?php

namespace AsyncInterop;

/**
 * Representation of the future value of an asynchronous operation.
 */
interface Promise
{
    /**
     * Registers a callback to be invoked when the promise is resolved.
     *
     * If the promise is already resolved, the callback MUST be executed immediately.
     *
     * @param callable(\Throwable|\Exception|null $reason, $value) $onResolved `$reason` shall be `null` on
     *     success, `$value` shall be `null` on failure.
     *
     * @return mixed Return type and value are unspecified.
     */
    public function when(callable $onResolved);
}

在Promise解决之前注册的所有回调必须在解决后按它们注册的顺序执行。在解决后注册的回调必须立即执行。

调用Promise::when()时不得抛出由$onResolved调用引发的异常。如果其中一个回调抛出Exception或Throwable，Promise实现必须捕获它，并使用Exception或Throwable作为第一个参数调用AsyncInterop\Promise\ErrorHandler::notify()。然后，Promise实现必须继续以原始参数调用剩余的回调。

注册的回调不得从启用严格类型的文件中调用（declare(strict_types=1)）。

错误处理

从注册到 Promise::when() 的回调函数抛出的未捕获异常，将通过 Promise 实现 转发到 ErrorHandler。可以使用 ErrorHandler::set() 来注册一个可调用的函数来优雅地处理这些异常，例如通过记录它们。如果处理程序再次抛出或未设置，将触发一个 E_USER_ERROR。如果使用 set_error_handler 设置了 PHP 错误处理程序并且它抛出异常，则将短消息写入 STDERR，并以代码 255 退出程序。因此，强烈建议设置一个错误处理程序并确保它不会抛出异常，特别是如果 PHP 错误处理程序被配置为将错误转换为异常的话。

async-interop / promise

维护者

详情

README

术语

状态

消费

错误处理

贡献者