From f3271fa9ad7d18d52d0af00d72b097d4b1080ef3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20L=C3=BCck?= Date: Tue, 12 Oct 2021 07:43:59 +0200 Subject: [PATCH 1/3] Improve documentation to use fully-qualified function names --- README.md | 38 +++++++++++++++++++++++--------------- src/functions.php | 20 ++++++++++---------- 2 files changed, 33 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index f38f099..ca68c1a 100644 --- a/README.md +++ b/README.md @@ -22,18 +22,26 @@ for [ReactPHP](https://reactphp.org/). This lightweight library consists only of a few simple functions. All functions reside under the `React\Promise\Stream` namespace. -The below examples assume you use an import statement similar to this: +The below examples assume refer to them with their fully-qualified names like this: ```php -use React\Promise\Stream; +React\Promise\Stream\buffer(…); +``` -Stream\buffer(…); +As of PHP 5.6+ you can also import each required function into your code like this: + +```php +use function React\Promise\Stream\buffer; + +buffer(…); ``` -Alternatively, you can also refer to them with their fully-qualified name: +Alternatively, you can also use an import statement similar to this: ```php -\React\Promise\Stream\buffer(…); +use React\Promise\Stream; + +Stream\buffer(…); ``` ### buffer() @@ -44,7 +52,7 @@ create a `Promise` which resolves with the stream data buffer. ```php $stream = accessSomeJsonStream(); -Stream\buffer($stream)->then(function ($contents) { +React\Promise\Stream\buffer($stream)->then(function ($contents) { var_dump(json_decode($contents)); }); ``` @@ -64,7 +72,7 @@ will be rejected with an `\OverflowException`. ```php $stream = accessSomeToLargeStream(); -Stream\buffer($stream, 1024)->then(function ($contents) { +React\Promise\Stream\buffer($stream, 1024)->then(function ($contents) { var_dump(json_decode($contents)); }, function ($error) { // Reaching here when the stream buffer goes above the max size, @@ -81,7 +89,7 @@ create a `Promise` which resolves once the given event triggers for the first ti ```php $stream = accessSomeJsonStream(); -Stream\first($stream)->then(function ($chunk) { +React\Promise\Stream\first($stream)->then(function ($chunk) { echo 'The first chunk arrived: ' . $chunk; }); ``` @@ -109,7 +117,7 @@ create a `Promise` which resolves with an array of all the event data. ```php $stream = accessSomeJsonStream(); -Stream\all($stream)->then(function ($chunks) { +React\Promise\Stream\all($stream)->then(function ($chunks) { echo 'The stream consists of ' . count($chunks) . ' chunk(s)'; }); ``` @@ -141,7 +149,7 @@ be piped to the output stream. //$promise = someFunctionWhichResolvesWithAStream(); $promise = startDownloadStream($uri); -$stream = Stream\unwrapReadable($promise); +$stream = React\Promise\Stream\unwrapReadable($promise); $stream->on('data', function ($data) { echo $data; @@ -159,7 +167,7 @@ an `error` event and close: ```php $promise = startDownloadStream($invalidUri); -$stream = Stream\unwrapReadable($promise); +$stream = React\Promise\Stream\unwrapReadable($promise); $stream->on('error', function (Exception $error) { echo 'Error: ' . $error->getMessage(); @@ -178,7 +186,7 @@ You can `close()` the resulting stream at any time, which will either try to ```php $promise = startDownloadStream($uri); -$stream = Stream\unwrapReadable($promise); +$stream = React\Promise\Stream\unwrapReadable($promise); $loop->addTimer(2.0, function () use ($stream) { $stream->close(); @@ -200,7 +208,7 @@ have written to the proxy will be forwarded transparently to the inner stream. //$promise = someFunctionWhichResolvesWithAStream(); $promise = startUploadStream($uri); -$stream = Stream\unwrapWritable($promise); +$stream = React\Promise\Stream\unwrapWritable($promise); $stream->write('hello'); $stream->end('world'); @@ -217,7 +225,7 @@ an `error` event and close: ```php $promise = startUploadStream($invalidUri); -$stream = Stream\unwrapWritable($promise); +$stream = React\Promise\Stream\unwrapWritable($promise); $stream->on('error', function (Exception $error) { echo 'Error: ' . $error->getMessage(); @@ -236,7 +244,7 @@ You can `close()` the resulting stream at any time, which will either try to ```php $promise = startUploadStream($uri); -$stream = Stream\unwrapWritable($promise); +$stream = React\Promise\Stream\unwrapWritable($promise); $loop->addTimer(2.0, function () use ($stream) { $stream->close(); diff --git a/src/functions.php b/src/functions.php index b74494f..bc82dff 100644 --- a/src/functions.php +++ b/src/functions.php @@ -14,7 +14,7 @@ * ```php * $stream = accessSomeJsonStream(); * - * Stream\buffer($stream)->then(function ($contents) { + * React\Promise\Stream\buffer($stream)->then(function ($contents) { * var_dump(json_decode($contents)); * }); * ``` @@ -34,7 +34,7 @@ * ```php * $stream = accessSomeToLargeStream(); * - * Stream\buffer($stream, 1024)->then(function ($contents) { + * React\Promise\Stream\buffer($stream, 1024)->then(function ($contents) { * var_dump(json_decode($contents)); * }, function ($error) { * // Reaching here when the stream buffer goes above the max size, @@ -97,7 +97,7 @@ function buffer(ReadableStreamInterface $stream, $maxLength = null) * ```php * $stream = accessSomeJsonStream(); * - * Stream\first($stream)->then(function ($chunk) { + * React\Promise\Stream\first($stream)->then(function ($chunk) { * echo 'The first chunk arrived: ' . $chunk; * }); * ``` @@ -170,7 +170,7 @@ function first(EventEmitterInterface $stream, $event = 'data') * ```php * $stream = accessSomeJsonStream(); * - * Stream\all($stream)->then(function ($chunks) { + * React\Promise\Stream\all($stream)->then(function ($chunks) { * echo 'The stream consists of ' . count($chunks) . ' chunk(s)'; * }); * ``` @@ -251,7 +251,7 @@ function all(EventEmitterInterface $stream, $event = 'data') * //$promise = someFunctionWhichResolvesWithAStream(); * $promise = startDownloadStream($uri); * - * $stream = Stream\unwrapReadable($promise); + * $stream = React\Promise\Stream\unwrapReadable($promise); * * $stream->on('data', function ($data) { * echo $data; @@ -269,7 +269,7 @@ function all(EventEmitterInterface $stream, $event = 'data') * ```php * $promise = startDownloadStream($invalidUri); * - * $stream = Stream\unwrapReadable($promise); + * $stream = React\Promise\Stream\unwrapReadable($promise); * * $stream->on('error', function (Exception $error) { * echo 'Error: ' . $error->getMessage(); @@ -288,7 +288,7 @@ function all(EventEmitterInterface $stream, $event = 'data') * ```php * $promise = startDownloadStream($uri); * - * $stream = Stream\unwrapReadable($promise); + * $stream = React\Promise\Stream\unwrapReadable($promise); * * $loop->addTimer(2.0, function () use ($stream) { * $stream->close(); @@ -316,7 +316,7 @@ function unwrapReadable(PromiseInterface $promise) * //$promise = someFunctionWhichResolvesWithAStream(); * $promise = startUploadStream($uri); * - * $stream = Stream\unwrapWritable($promise); + * $stream = React\Promise\Stream\unwrapWritable($promise); * * $stream->write('hello'); * $stream->end('world'); @@ -333,7 +333,7 @@ function unwrapReadable(PromiseInterface $promise) * ```php * $promise = startUploadStream($invalidUri); * - * $stream = Stream\unwrapWritable($promise); + * $stream = React\Promise\Stream\unwrapWritable($promise); * * $stream->on('error', function (Exception $error) { * echo 'Error: ' . $error->getMessage(); @@ -352,7 +352,7 @@ function unwrapReadable(PromiseInterface $promise) * ```php * $promise = startUploadStream($uri); * - * $stream = Stream\unwrapWritable($promise); + * $stream = React\Promise\Stream\unwrapWritable($promise); * * $loop->addTimer(2.0, function () use ($stream) { * $stream->close(); From bb0ad5257f18455139ee13000cd9ed02f511f913 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20L=C3=BCck?= Date: Tue, 12 Oct 2021 08:15:53 +0200 Subject: [PATCH 2/3] Minor documentation improvements --- README.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index ca68c1a..bcc6d14 100644 --- a/README.md +++ b/README.md @@ -8,11 +8,11 @@ for [ReactPHP](https://reactphp.org/). **Table of Contents** * [Usage](#usage) - * [buffer()](#buffer) - * [first()](#first) - * [all()](#all) - * [unwrapReadable()](#unwrapreadable) - * [unwrapWritable()](#unwrapwritable) + * [buffer()](#buffer) + * [first()](#first) + * [all()](#all) + * [unwrapReadable()](#unwrapreadable) + * [unwrapWritable()](#unwrapwritable) * [Install](#install) * [Tests](#tests) * [License](#license) @@ -253,7 +253,7 @@ $loop->addTimer(2.0, function () use ($stream) { ## Install -The recommended way to install this library is [through Composer](https://getcomposer.org). +The recommended way to install this library is [through Composer](https://getcomposer.org/). [New to Composer?](https://getcomposer.org/doc/00-intro.md) This project follows [SemVer](https://semver.org/). @@ -268,12 +268,12 @@ See also the [CHANGELOG](CHANGELOG.md) for details about version upgrades. This project aims to run on any platform and thus does not require any PHP extensions and supports running on legacy PHP 5.3 through current PHP 8+ and HHVM. -It's *highly recommended to use PHP 7+* for this project. +It's *highly recommended to use the latest supported PHP version* for this project. ## Tests To run the test suite, you first need to clone this repo and then install all -dependencies [through Composer](https://getcomposer.org): +dependencies [through Composer](https://getcomposer.org/): ```bash $ composer install @@ -282,7 +282,7 @@ $ composer install To run the test suite, go to the project root and run: ```bash -$ php vendor/bin/phpunit +$ vendor/bin/phpunit ``` ## License From e5f90330c6a8d02bffa6e45bb35e50bd0c080b8f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20L=C3=BCck?= Date: Sat, 16 Oct 2021 18:53:25 +0200 Subject: [PATCH 3/3] Improve promise and type documentation --- README.md | 100 ++++++++++++++++++++++---------------------- src/functions.php | 104 +++++++++++++++++++++++----------------------- 2 files changed, 104 insertions(+), 100 deletions(-) diff --git a/README.md b/README.md index bcc6d14..10d9548 100644 --- a/README.md +++ b/README.md @@ -46,28 +46,28 @@ Stream\buffer(…); ### buffer() -The `buffer(ReadableStreamInterface $stream, ?int $maxLength = null): PromiseInterface` function can be used to -create a `Promise` which resolves with the stream data buffer. +The `buffer(ReadableStreamInterface $stream, ?int $maxLength = null): PromiseInterface` function can be used to +create a `Promise` which will be fulfilled with the stream data buffer. ```php $stream = accessSomeJsonStream(); -React\Promise\Stream\buffer($stream)->then(function ($contents) { +React\Promise\Stream\buffer($stream)->then(function (string $contents) { var_dump(json_decode($contents)); }); ``` -The promise will resolve with all data chunks concatenated once the stream closes. +The promise will be fulfilled with a `string` of all data chunks concatenated once the stream closes. -The promise will resolve with an empty string if the stream is already closed. +The promise will be fulfilled with an empty `string` if the stream is already closed. -The promise will reject if the stream emits an error. +The promise will be rejected with a `RuntimeException` if the stream emits an error. -The promise will reject if it is cancelled. +The promise will be rejected with a `RuntimeException` if it is cancelled. The optional `$maxLength` argument defaults to no limit. In case the maximum length is given and the stream emits more data before the end, the promise -will be rejected with an `\OverflowException`. +will be rejected with an `OverflowException`. ```php $stream = accessSomeToLargeStream(); @@ -83,67 +83,69 @@ React\Promise\Stream\buffer($stream, 1024)->then(function ($contents) { ### first() -The `first(ReadableStreamInterface|WritableStreamInterface $stream, string $event = 'data'): PromiseInterface` function can be used to -create a `Promise` which resolves once the given event triggers for the first time. +The `first(ReadableStreamInterface|WritableStreamInterface $stream, string $event = 'data'): PromiseInterface` function can be used to +create a `Promise` which will be fulfilled once the given event triggers for the first time. ```php $stream = accessSomeJsonStream(); -React\Promise\Stream\first($stream)->then(function ($chunk) { +React\Promise\Stream\first($stream)->then(function (string $chunk) { echo 'The first chunk arrived: ' . $chunk; }); ``` -The promise will resolve with whatever the first event emitted or `null` if the -event does not pass any data. +The promise will be fulfilled with a `mixed` value of whatever the first event +emitted or `null` if the event does not pass any data. If you do not pass a custom event name, then it will wait for the first "data" -event and resolve with a string containing the first data chunk. +event. +For common streams of type `ReadableStreamInterface`, this means it will be +fulfilled with a `string` containing the first data chunk. -The promise will reject if the stream emits an error – unless you're waiting for -the "error" event, in which case it will resolve. +The promise will be rejected with a `RuntimeException` if the stream emits an error +– unless you're waiting for the "error" event, in which case it will be fulfilled. -The promise will reject once the stream closes – unless you're waiting for the -"close" event, in which case it will resolve. +The promise will be rejected with a `RuntimeException` once the stream closes +– unless you're waiting for the "close" event, in which case it will be fulfilled. -The promise will reject if the stream is already closed. +The promise will be rejected with a `RuntimeException` if the stream is already closed. -The promise will reject if it is cancelled. +The promise will be rejected with a `RuntimeException` if it is cancelled. ### all() -The `all(ReadableStreamInterface|WritableStreamInterface $stream, string $event = 'data'): PromiseInterface` function can be used to -create a `Promise` which resolves with an array of all the event data. +The `all(ReadableStreamInterface|WritableStreamInterface $stream, string $event = 'data'): PromiseInterface` function can be used to +create a `Promise` which will be fulfilled with an array of all the event data. ```php $stream = accessSomeJsonStream(); -React\Promise\Stream\all($stream)->then(function ($chunks) { +React\Promise\Stream\all($stream)->then(function (array $chunks) { echo 'The stream consists of ' . count($chunks) . ' chunk(s)'; }); ``` -The promise will resolve with an array of whatever all events emitted or `null` if the -events do not pass any data. +The promise will be fulfilled with an `array` once the stream closes. The array +will contain whatever all events emitted or `null` values if the events do not pass any data. If you do not pass a custom event name, then it will wait for all the "data" -events and resolve with an array containing all the data chunks. +events. +For common streams of type `ReadableStreamInterface`, this means it will be +fulfilled with a `string[]` array containing all the data chunk. -The promise will resolve with an array once the stream closes. +The promise will be fulfilled with an empty `array` if the stream is already closed. -The promise will resolve with an empty array if the stream is already closed. +The promise will be rejected with a `RuntimeException` if the stream emits an error. -The promise will reject if the stream emits an error. - -The promise will reject if it is cancelled. +The promise will be rejected with a `RuntimeException` if it is cancelled. ### unwrapReadable() -The `unwrapReadable(PromiseInterface $promise): ReadableStreamInterface` function can be used to -unwrap a `Promise` which resolves with a `ReadableStreamInterface`. +The `unwrapReadable(PromiseInterface,Exception> $promise): ReadableStreamInterface` function can be used to +unwrap a `Promise` which will be fulfilled with a `ReadableStreamInterface`. -This function returns a readable stream instance (implementing `ReadableStreamInterface`) +This function returns a readable stream instance (implementing `ReadableStreamInterface`) right away which acts as a proxy for the future promise resolution. -Once the given Promise resolves with a `ReadableStreamInterface`, its data will -be piped to the output stream. +Once the given Promise will be fulfilled with a `ReadableStreamInterface`, its +data will be piped to the output stream. ```php //$promise = someFunctionWhichResolvesWithAStream(); @@ -151,7 +153,7 @@ $promise = startDownloadStream($uri); $stream = React\Promise\Stream\unwrapReadable($promise); -$stream->on('data', function ($data) { +$stream->on('data', function (string $data) { echo $data; }); @@ -176,9 +178,8 @@ $stream->on('error', function (Exception $error) { The given `$promise` SHOULD be pending, i.e. it SHOULD NOT be fulfilled or rejected at the time of invoking this function. -If the given promise is already settled and does not resolve with an -instance of `ReadableStreamInterface`, then you will not be able to receive -the `error` event. +If the given promise is already settled and does not fulfill with an instance of +`ReadableStreamInterface`, then you will not be able to receive the `error` event. You can `close()` the resulting stream at any time, which will either try to `cancel()` the pending promise or try to `close()` the underlying stream. @@ -195,14 +196,16 @@ $loop->addTimer(2.0, function () use ($stream) { ### unwrapWritable() -The `unwrapWritable(PromiseInterface $promise): WritableStreamInterface` function can be used to -unwrap a `Promise` which resolves with a `WritableStreamInterface`. +The `unwrapWritable(PromiseInterface,Exception> $promise): WritableStreamInterface` function can be used to +unwrap a `Promise` which will be fulfilled with a `WritableStreamInterface`. -This function returns a writable stream instance (implementing `WritableStreamInterface`) +This function returns a writable stream instance (implementing `WritableStreamInterface`) right away which acts as a proxy for the future promise resolution. -Any writes to this instance will be buffered in memory for when the promise resolves. -Once the given Promise resolves with a `WritableStreamInterface`, any data you -have written to the proxy will be forwarded transparently to the inner stream. +Any writes to this instance will be buffered in memory for when the promise will +be fulfilled. +Once the given Promise will be fulfilled with a `WritableStreamInterface`, any +data you have written to the proxy will be forwarded transparently to the inner +stream. ```php //$promise = someFunctionWhichResolvesWithAStream(); @@ -234,9 +237,8 @@ $stream->on('error', function (Exception $error) { The given `$promise` SHOULD be pending, i.e. it SHOULD NOT be fulfilled or rejected at the time of invoking this function. -If the given promise is already settled and does not resolve with an -instance of `WritableStreamInterface`, then you will not be able to receive -the `error` event. +If the given promise is already settled and does not fulfill with an instance of +`WritableStreamInterface`, then you will not be able to receive the `error` event. You can `close()` the resulting stream at any time, which will either try to `cancel()` the pending promise or try to `close()` the underlying stream. diff --git a/src/functions.php b/src/functions.php index bc82dff..da66de8 100644 --- a/src/functions.php +++ b/src/functions.php @@ -9,27 +9,27 @@ use React\Stream\WritableStreamInterface; /** - * Creates a `Promise` which resolves with the stream data buffer. + * Create a `Promise` which will be fulfilled with the stream data buffer. * * ```php * $stream = accessSomeJsonStream(); * - * React\Promise\Stream\buffer($stream)->then(function ($contents) { + * React\Promise\Stream\buffer($stream)->then(function (string $contents) { * var_dump(json_decode($contents)); * }); * ``` * - * The promise will resolve with all data chunks concatenated once the stream closes. + * The promise will be fulfilled with a `string` of all data chunks concatenated once the stream closes. * - * The promise will resolve with an empty string if the stream is already closed. + * The promise will be fulfilled with an empty `string` if the stream is already closed. * - * The promise will reject if the stream emits an error. + * The promise will be rejected with a `RuntimeException` if the stream emits an error. * - * The promise will reject if it is cancelled. + * The promise will be rejected with a `RuntimeException` if it is cancelled. * * The optional `$maxLength` argument defaults to no limit. In case the maximum * length is given and the stream emits more data before the end, the promise - * will be rejected with an `\OverflowException`. + * will be rejected with an `OverflowException`. * * ```php * $stream = accessSomeToLargeStream(); @@ -45,7 +45,7 @@ * * @param ReadableStreamInterface $stream * @param ?int $maxLength Maximum number of bytes to buffer or null for unlimited. - * @return PromiseInterface + * @return PromiseInterface */ function buffer(ReadableStreamInterface $stream, $maxLength = null) { @@ -92,34 +92,36 @@ function buffer(ReadableStreamInterface $stream, $maxLength = null) } /** - * Creates a `Promise` which resolves once the given event triggers for the first time. + * Create a `Promise` which will be fulfilled once the given event triggers for the first time. * * ```php * $stream = accessSomeJsonStream(); * - * React\Promise\Stream\first($stream)->then(function ($chunk) { + * React\Promise\Stream\first($stream)->then(function (string $chunk) { * echo 'The first chunk arrived: ' . $chunk; * }); * ``` * - * The promise will resolve with whatever the first event emitted or `null` if the - * event does not pass any data. + * The promise will be fulfilled with a `mixed` value of whatever the first event + * emitted or `null` if the event does not pass any data. * If you do not pass a custom event name, then it will wait for the first "data" - * event and resolve with a string containing the first data chunk. + * event. + * For common streams of type `ReadableStreamInterface`, this means it will be + * fulfilled with a `string` containing the first data chunk. * - * The promise will reject if the stream emits an error – unless you're waiting for - * the "error" event, in which case it will resolve. + * The promise will be rejected with a `RuntimeException` if the stream emits an error + * – unless you're waiting for the "error" event, in which case it will be fulfilled. * - * The promise will reject once the stream closes – unless you're waiting for the - * "close" event, in which case it will resolve. + * The promise will be rejected with a `RuntimeException` once the stream closes + * – unless you're waiting for the "close" event, in which case it will be fulfilled. * - * The promise will reject if the stream is already closed. + * The promise will be rejected with a `RuntimeException` if the stream is already closed. * - * The promise will reject if it is cancelled. + * The promise will be rejected with a `RuntimeException` if it is cancelled. * * @param ReadableStreamInterface|WritableStreamInterface $stream * @param string $event - * @return PromiseInterface + * @return PromiseInterface */ function first(EventEmitterInterface $stream, $event = 'data') { @@ -165,32 +167,32 @@ function first(EventEmitterInterface $stream, $event = 'data') } /** - * Creates a `Promise` which resolves with an array of all the event data. + * Create a `Promise` which will be fulfilled with an array of all the event data. * * ```php * $stream = accessSomeJsonStream(); * - * React\Promise\Stream\all($stream)->then(function ($chunks) { + * React\Promise\Stream\all($stream)->then(function (array $chunks) { * echo 'The stream consists of ' . count($chunks) . ' chunk(s)'; * }); * ``` * - * The promise will resolve with an array of whatever all events emitted or `null` if the - * events do not pass any data. + * The promise will be fulfilled with an `array` once the stream closes. The array + * will contain whatever all events emitted or `null` values if the events do not pass any data. * If you do not pass a custom event name, then it will wait for all the "data" - * events and resolve with an array containing all the data chunks. + * events. + * For common streams of type `ReadableStreamInterface`, this means it will be + * fulfilled with a `string[]` array containing all the data chunk. * - * The promise will resolve with an array once the stream closes. + * The promise will be fulfilled with an empty `array` if the stream is already closed. * - * The promise will resolve with an empty array if the stream is already closed. + * The promise will be rejected with a `RuntimeException` if the stream emits an error. * - * The promise will reject if the stream emits an error. - * - * The promise will reject if it is cancelled. + * The promise will be rejected with a `RuntimeException` if it is cancelled. * * @param ReadableStreamInterface|WritableStreamInterface $stream * @param string $event - * @return PromiseInterface + * @return PromiseInterface */ function all(EventEmitterInterface $stream, $event = 'data') { @@ -240,12 +242,12 @@ function all(EventEmitterInterface $stream, $event = 'data') } /** - * Unwraps a `Promise` which resolves with a `ReadableStreamInterface`. + * Unwrap a `Promise` which will be fulfilled with a `ReadableStreamInterface`. * - * This function returns a readable stream instance (implementing `ReadableStreamInterface`) + * This function returns a readable stream instance (implementing `ReadableStreamInterface`) * right away which acts as a proxy for the future promise resolution. - * Once the given Promise resolves with a `ReadableStreamInterface`, its data will - * be piped to the output stream. + * Once the given Promise will be fulfilled with a `ReadableStreamInterface`, its + * data will be piped to the output stream. * * ```php * //$promise = someFunctionWhichResolvesWithAStream(); @@ -253,7 +255,7 @@ function all(EventEmitterInterface $stream, $event = 'data') * * $stream = React\Promise\Stream\unwrapReadable($promise); * - * $stream->on('data', function ($data) { + * $stream->on('data', function (string $data) { * echo $data; * }); * @@ -278,9 +280,8 @@ function all(EventEmitterInterface $stream, $event = 'data') * * The given `$promise` SHOULD be pending, i.e. it SHOULD NOT be fulfilled or rejected * at the time of invoking this function. - * If the given promise is already settled and does not resolve with an - * instance of `ReadableStreamInterface`, then you will not be able to receive - * the `error` event. + * If the given promise is already settled and does not fulfill with an instance of + * `ReadableStreamInterface`, then you will not be able to receive the `error` event. * * You can `close()` the resulting stream at any time, which will either try to * `cancel()` the pending promise or try to `close()` the underlying stream. @@ -295,8 +296,8 @@ function all(EventEmitterInterface $stream, $event = 'data') * }); * ``` * - * @param PromiseInterface $promise - * @return ReadableStreamInterface + * @param PromiseInterface,\Exception> $promise + * @return ReadableStreamInterface */ function unwrapReadable(PromiseInterface $promise) { @@ -304,13 +305,15 @@ function unwrapReadable(PromiseInterface $promise) } /** - * Unwraps a `Promise` which resolves with a `WritableStreamInterface`. + * unwrap a `Promise` which will be fulfilled with a `WritableStreamInterface`. * - * This function returns a writable stream instance (implementing `WritableStreamInterface`) + * This function returns a writable stream instance (implementing `WritableStreamInterface`) * right away which acts as a proxy for the future promise resolution. - * Any writes to this instance will be buffered in memory for when the promise resolves. - * Once the given Promise resolves with a `WritableStreamInterface`, any data you - * have written to the proxy will be forwarded transparently to the inner stream. + * Any writes to this instance will be buffered in memory for when the promise will + * be fulfilled. + * Once the given Promise will be fulfilled with a `WritableStreamInterface`, any + * data you have written to the proxy will be forwarded transparently to the inner + * stream. * * ```php * //$promise = someFunctionWhichResolvesWithAStream(); @@ -342,9 +345,8 @@ function unwrapReadable(PromiseInterface $promise) * * The given `$promise` SHOULD be pending, i.e. it SHOULD NOT be fulfilled or rejected * at the time of invoking this function. - * If the given promise is already settled and does not resolve with an - * instance of `WritableStreamInterface`, then you will not be able to receive - * the `error` event. + * If the given promise is already settled and does not fulfill with an instance of + * `WritableStreamInterface`, then you will not be able to receive the `error` event. * * You can `close()` the resulting stream at any time, which will either try to * `cancel()` the pending promise or try to `close()` the underlying stream. @@ -359,8 +361,8 @@ function unwrapReadable(PromiseInterface $promise) * }); * ``` * - * @param PromiseInterface $promise - * @return WritableStreamInterface + * @param PromiseInterface,\Exception> $promise + * @return WritableStreamInterface */ function unwrapWritable(PromiseInterface $promise) {