README

建立在 React PHP 之上的 Promise-land 和 Stream-land 之间的缺失连接。

目录

• 使用方法
  • buffer()
  • first()
  • all()
  • unwrapReadable()
  • unwrapWritable()
• 安装
• 许可证

注意：该项目处于测试阶段！请随意报告您遇到的问题。

使用方法

这个轻量级库只包含几个简单的函数。所有函数都位于 Clue\React\Promise\Stream 命名空间下。

以下示例假设您使用类似下面的导入语句

use Clue\React\Promise\Stream;

Stream\buffer(…);

或者，您也可以使用它们的完全限定名称来引用它们

\Clue\React\Promise\Stream\buffer(…);

buffer()

buffer(ReadableStreamInterface $stream) 函数可以用来创建一个解析为流数据缓冲区的 Promise。

$stream = accessSomeJsonStream();

Stream\buffer($stream)->then(function ($contents) {
    var_dump(json_decode($contents));
});

当流关闭时，Promise 将解析为所有数据块连接在一起。

如果流已经关闭，Promise 将解析为一个空字符串。

如果流发出错误，Promise 将拒绝。

如果它被取消，Promise 将拒绝。

first()

first(ReadableStreamInterface|WritableStreamInterface $stream, $event = 'data') 函数可以用来创建一个在给定事件第一次触发时解决的 Promise。

$stream = accessSomeJsonStream();

Stream\first($stream)->then(function ($chunk) {
    echo 'The first chunk arrived: ' . $chunk;
});

Promise 将解析为第一个发出的任何事件或 null（如果事件未传递任何数据）。如果您不传递自定义事件名称，则它将等待第一个 "data" 事件，并以包含第一个数据块的字符串解决。

当流关闭时，Promise 将拒绝 - 除非您正在等待 "close" 事件，在这种情况下，它将解决。

如果流已经关闭，Promise 将拒绝。

如果它被取消，Promise 将拒绝。

all()

all(ReadableStreamInterface|WritableStreamInterface $stream, $event = 'data') 函数可以用来创建一个解析为所有事件数据的 Promise。

$stream = accessSomeJsonStream();

Stream\all($stream)->then(function ($chunks) {
    echo 'The stream consists of ' . count($chunks) . ' chunk(s)';
});

Promise 将解析为一个包含所有发出事件的数组或 null（如果事件未传递任何数据）。如果您不传递自定义事件名称，则它将等待所有的 "data" 事件，并以包含所有数据块的数组解决。

当流关闭时，Promise 将解析为一个数组。

如果流已经关闭，Promise 将解析为一个空数组。

如果流发出错误，Promise 将拒绝。

如果它被取消，Promise 将拒绝。

unwrapReadable()

unwrapReadable(PromiseInterface $promise) 函数可以用来解包一个解析为 ReadableStreamInterface 的 Promise。

该函数立即返回一个可读流实例（实现 ReadableStreamInterface），作为未来承诺解决的代理。一旦给定的 Promise 解析为 ReadableStreamInterface，其数据将被管道传输到输出流。

//$promise = someFunctionWhichResolvesWithAStream();
$promise = startDownloadStream($uri);

$stream = Stream\unwrapReadable($promise);

$stream->on('data', function ($data) {
   echo $data;
});

$stream->on('end', function () {
   echo 'DONE';
});

如果给定的Promise被拒绝或者用除了ReadableStreamInterface实例之外的任何内容满足，则输出流将触发一个error事件并关闭

$promise = startDownloadStream($invalidUri);

$stream = Stream\unwrapReadable($promise);

$stream->on('error', function (Exception $error) {
    echo 'Error: ' . $error->getMessage();
});

给定的$promise应该是挂起的，即它不应该在调用此函数时已经满足或拒绝。如果给定的Promise已经解决并且没有使用ReadableStreamInterface实例解决，那么您将无法接收到error事件。

unwrapWritable()

unwrapWritable(PromiseInterface $promise)函数可以用来解开一个解决为WritableStreamInterface的Promise。

此函数立即返回一个可写流实例（实现了WritableStreamInterface），它作为未来Promise解决的代理。一旦给定的Promise解决为WritableStreamInterface，您写入代理的任何数据都将被管道传输到内部流。

//$promise = someFunctionWhichResolvesWithAStream();
$promise = startUploadStream($uri);

$stream = Stream\unwrapWritable($promise);

$stream->write('hello');
$stream->end('world');

$stream->on('close', function () {
   echo 'DONE';
});

如果给定的Promise被拒绝或者用除了WritableStreamInterface实例之外的任何内容满足，则输出流将触发一个error事件并关闭

$promise = startUploadStream($invalidUri);

$stream = Stream\unwrapWritable($promise);

$stream->on('error', function (Exception $error) {
    echo 'Error: ' . $error->getMessage();
});

给定的$promise应该是挂起的，即它不应该在调用此函数时已经满足或拒绝。如果给定的Promise已经解决并且没有使用WritableStreamInterface实例解决，那么您将无法接收到error事件。

安装

安装此库的推荐方法是通过Composer。 对Composer不熟悉？

这将安装最新的支持版本

$ composer require clue/promise-stream-react:^0.1.2

有关版本升级的详细信息，请参阅变更日志。

许可证

MIT