From b7713d7384a7bd0a8a2b8a444c70641ce9b19b6a Mon Sep 17 00:00:00 2001 From: Simon Frings Date: Tue, 19 Oct 2021 12:48:36 +0200 Subject: [PATCH] Improve documentation to use fully-qualified function names --- README.md | 62 +++++++++++++++++++++++------------------------ src/functions.php | 28 ++++++++++----------- 2 files changed, 45 insertions(+), 45 deletions(-) diff --git a/README.md b/README.md index 0b01cf1..52a09e8 100644 --- a/README.md +++ b/README.md @@ -10,10 +10,10 @@ A simple and modern approach to stream filtering in PHP * [Why?](#why) * [Support us](#support-us) * [Usage](#usage) - * [append()](#append) - * [prepend()](#prepend) - * [fun()](#fun) - * [remove()](#remove) + * [append()](#append) + * [prepend()](#prepend) + * [fun()](#fun) + * [remove()](#remove) * [Install](#install) * [Tests](#tests) * [License](#license) @@ -58,26 +58,26 @@ Let's take these projects to the next level together! 🚀 This lightweight library consists only of a few simple functions. All functions reside under the `Clue\StreamFilter` namespace. -The below examples assume you use an import statement similar to this: +The below examples refer to all functions with their fully-qualified names like this: ```php -use Clue\StreamFilter as Filter; - -Filter\append(…); +Clue\StreamFilter\append(…); ``` -Alternatively, you can also refer to them with their fully-qualified name: +As of PHP 5.6+ you can also import each required function into your code like this: ```php -\Clue\StreamFilter\append(…); +use function Clue\StreamFilter\append; + +append(…); ``` -As of PHP 5.6+ you can also import each required function into your code like this: +Alternatively, you can also use an import statement similar to this: ```php -use function Clue\StreamFilter\append; +use Clue\StreamFilter as Filter; -append(…); +Filter\append(…); ``` ### append() @@ -100,7 +100,7 @@ The `$callback` should be a valid callable function which accepts an individual chunk of data and should return the updated chunk: ```php -$filter = Filter\append($stream, function ($chunk) { +$filter = Clue\StreamFilter\append($stream, function ($chunk) { // will be called each time you read or write a $chunk to/from the stream return $chunk; }); @@ -109,7 +109,7 @@ $filter = Filter\append($stream, function ($chunk) { As such, you can also use native PHP functions or any other `callable`: ```php -Filter\append($stream, 'strtoupper'); +Clue\StreamFilter\append($stream, 'strtoupper'); // will write "HELLO" to the underlying stream fwrite($stream, 'hello'); @@ -119,7 +119,7 @@ If the `$callback` accepts invocation without parameters, then this signature will be invoked once ending (flushing) the filter: ```php -Filter\append($stream, function ($chunk = null) { +Clue\StreamFilter\append($stream, function ($chunk = null) { if ($chunk === null) { // will be called once ending the filter return 'end'; @@ -139,7 +139,7 @@ In order to play nice with PHP's stream handling, the `Exception` will be transformed to a PHP warning instead: ```php -Filter\append($stream, function ($chunk) { +Clue\StreamFilter\append($stream, function ($chunk) { throw new \RuntimeException('Unexpected chunk'); }); @@ -151,12 +151,12 @@ The optional `$read_write` parameter can be used to only invoke the `$callback` when either writing to the stream or only when reading from the stream: ```php -Filter\append($stream, function ($chunk) { +Clue\StreamFilter\append($stream, function ($chunk) { // will be called each time you write to the stream return $chunk; }, STREAM_FILTER_WRITE); -Filter\append($stream, function ($chunk) { +Clue\StreamFilter\append($stream, function ($chunk) { // will be called each time you read from the stream return $chunk; }, STREAM_FILTER_READ); @@ -186,7 +186,7 @@ This function prepends a filter to the start of this list. If the given filter can not be added, it throws an `Exception`. ```php -$filter = Filter\prepend($stream, function ($chunk) { +$filter = Clue\StreamFilter\prepend($stream, function ($chunk) { // will be called each time you read or write a $chunk to/from the stream return $chunk; }); @@ -208,7 +208,7 @@ Using `fun()` makes accessing these as easy as passing an input string to filter and getting the filtered output string. ```php -$fun = Filter\fun('string.rot13'); +$fun = Clue\StreamFilter\fun('string.rot13'); assert('grfg' === $fun('test')); assert('test' === $fun($fun('test')); @@ -221,7 +221,7 @@ or parameters as Zend PHP. Accessing an unknown filter function will result in a `RuntimeException`: ```php -Filter\fun('unknown'); // throws RuntimeException +Clue\StreamFilter\fun('unknown'); // throws RuntimeException ``` Some filters may accept or require additional filter parameters – most @@ -234,7 +234,7 @@ Please refer to the individual filter definition for more details. For example, the `string.strip_tags` filter can be invoked like this: ```php -$fun = Filter\fun('string.strip_tags', ''); +$fun = Clue\StreamFilter\fun('string.strip_tags', ''); $ret = $fun('h
i'); assert('hi' === $ret); @@ -248,7 +248,7 @@ may use internal buffers and may emit a final data chunk on close. The filter function can be closed by invoking without any arguments: ```php -$fun = Filter\fun('zlib.deflate'); +$fun = Clue\StreamFilter\fun('zlib.deflate'); $ret = $fun('hello') . $fun('world') . $fun(); assert('helloworld' === gzinflate($ret)); @@ -258,7 +258,7 @@ The filter function must not be used anymore after it has been closed. Doing so will result in a `RuntimeException`: ```php -$fun = Filter\fun('string.rot13'); +$fun = Clue\StreamFilter\fun('string.rot13'); $fun(); $fun('test'); // throws RuntimeException @@ -277,15 +277,15 @@ The `remove(resource $filter): bool` function can be used to remove a filter previously added via [`append()`](#append) or [`prepend()`](#prepend). ```php -$filter = Filter\append($stream, function () { +$filter = Clue\StreamFilter\append($stream, function () { // … }); -Filter\remove($filter); +Clue\StreamFilter\remove($filter); ``` ## 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/). @@ -300,13 +300,13 @@ 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. Older PHP versions may suffer from a number of inconsistencies documented above. ## 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 @@ -315,7 +315,7 @@ $ composer install To run the test suite, go to the project root and run: ```bash -$ php vendor/bin/phpunit +$ vendor/bin/phpunit ``` ## License diff --git a/src/functions.php b/src/functions.php index 4746d88..cad88a2 100644 --- a/src/functions.php +++ b/src/functions.php @@ -20,7 +20,7 @@ * an individual chunk of data and should return the updated chunk: * * ```php - * $filter = Filter\append($stream, function ($chunk) { + * $filter = Clue\StreamFilter\append($stream, function ($chunk) { * // will be called each time you read or write a $chunk to/from the stream * return $chunk; * }); @@ -29,7 +29,7 @@ * As such, you can also use native PHP functions or any other `callable`: * * ```php - * Filter\append($stream, 'strtoupper'); + * Clue\StreamFilter\append($stream, 'strtoupper'); * * // will write "HELLO" to the underlying stream * fwrite($stream, 'hello'); @@ -39,7 +39,7 @@ * then this signature will be invoked once ending (flushing) the filter: * * ```php - * Filter\append($stream, function ($chunk = null) { + * Clue\StreamFilter\append($stream, function ($chunk = null) { * if ($chunk === null) { * // will be called once ending the filter * return 'end'; @@ -59,7 +59,7 @@ * the `Exception` will be transformed to a PHP warning instead: * * ```php - * Filter\append($stream, function ($chunk) { + * Clue\StreamFilter\append($stream, function ($chunk) { * throw new \RuntimeException('Unexpected chunk'); * }); * @@ -71,12 +71,12 @@ * when either writing to the stream or only when reading from the stream: * * ```php - * Filter\append($stream, function ($chunk) { + * Clue\StreamFilter\append($stream, function ($chunk) { * // will be called each time you write to the stream * return $chunk; * }, STREAM_FILTER_WRITE); * - * Filter\append($stream, function ($chunk) { + * Clue\StreamFilter\append($stream, function ($chunk) { * // will be called each time you read from the stream * return $chunk; * }, STREAM_FILTER_READ); @@ -126,7 +126,7 @@ function append($stream, $callback, $read_write = STREAM_FILTER_ALL) * If the given filter can not be added, it throws an `Exception`. * * ```php - * $filter = Filter\prepend($stream, function ($chunk) { + * $filter = Clue\StreamFilter\prepend($stream, function ($chunk) { * // will be called each time you read or write a $chunk to/from the stream * return $chunk; * }); @@ -168,7 +168,7 @@ function prepend($stream, $callback, $read_write = STREAM_FILTER_ALL) * and getting the filtered output string. * * ```php - * $fun = Filter\fun('string.rot13'); + * $fun = Clue\StreamFilter\fun('string.rot13'); * * assert('grfg' === $fun('test')); * assert('test' === $fun($fun('test')); @@ -181,7 +181,7 @@ function prepend($stream, $callback, $read_write = STREAM_FILTER_ALL) * Accessing an unknown filter function will result in a `RuntimeException`: * * ```php - * Filter\fun('unknown'); // throws RuntimeException + * Clue\StreamFilter\fun('unknown'); // throws RuntimeException * ``` * * Some filters may accept or require additional filter parameters – most @@ -194,7 +194,7 @@ function prepend($stream, $callback, $read_write = STREAM_FILTER_ALL) * For example, the `string.strip_tags` filter can be invoked like this: * * ```php - * $fun = Filter\fun('string.strip_tags', ''); + * $fun = Clue\StreamFilter\fun('string.strip_tags', ''); * * $ret = $fun('h
i'); * assert('hi' === $ret); @@ -208,7 +208,7 @@ function prepend($stream, $callback, $read_write = STREAM_FILTER_ALL) * The filter function can be closed by invoking without any arguments: * * ```php - * $fun = Filter\fun('zlib.deflate'); + * $fun = Clue\StreamFilter\fun('zlib.deflate'); * * $ret = $fun('hello') . $fun('world') . $fun(); * assert('helloworld' === gzinflate($ret)); @@ -218,7 +218,7 @@ function prepend($stream, $callback, $read_write = STREAM_FILTER_ALL) * Doing so will result in a `RuntimeException`: * * ```php - * $fun = Filter\fun('string.rot13'); + * $fun = Clue\StreamFilter\fun('string.rot13'); * $fun(); * * $fun('test'); // throws RuntimeException @@ -288,10 +288,10 @@ function fun($filter, $parameters = null) * Remove a filter previously added via `append()` or `prepend()`. * * ```php - * $filter = Filter\append($stream, function () { + * $filter = Clue\StreamFilter\append($stream, function () { * // … * }); - * Filter\remove($filter); + * Clue\StreamFilter\remove($filter); * ``` * * @param resource $filter