Skip to content

Improve documentation to use fully-qualified function names #43

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
clue merged 1 commit into from
Oct 19, 2021
Merged

Improve documentation to use fully-qualified function names #43

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
62 changes: 31 additions & 31 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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()
Expand All @@ -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;
});
Expand All @@ -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');
Expand All @@ -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';
Expand All @@ -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');
});

Expand All @@ -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);
Expand Down Expand Up @@ -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;
});
Expand All @@ -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'));
Expand All @@ -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
Expand All @@ -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', '<a><b>');
$fun = Clue\StreamFilter\fun('string.strip_tags', '<a><b>');

$ret = $fun('<b>h<br>i</b>');
assert('<b>hi</b>' === $ret);
Expand All @@ -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));
Expand All @@ -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
Expand All @@ -277,15 +277,15 @@ The `remove(resource<stream filter> $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/).
Expand All @@ -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
Expand All @@ -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
Expand Down
28 changes: 14 additions & 14 deletions src/functions.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
* });
Expand All @@ -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');
Expand All @@ -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';
Expand All @@ -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');
* });
*
Expand All @@ -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);
Expand Down Expand Up @@ -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;
* });
Expand Down Expand Up @@ -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'));
Expand All @@ -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
Expand All @@ -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', '<a><b>');
* $fun = Clue\StreamFilter\fun('string.strip_tags', '<a><b>');
*
* $ret = $fun('<b>h<br>i</b>');
* assert('<b>hi</b>' === $ret);
Expand All @@ -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));
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down