Download the PHP package improved/iterable without Composer

iterable

Functional-style operations, such as map-reduce transformations on arrays, iterators and other traversable objects.

These functions are different from their array_* counterparts, as they work with any kind of iterable rather than just arrays. If you're not familiar with Iterators and Generators in PHP, please first read paragraph "What are iterators?".

The library supports the procedural and object-oriented programming paradigm.

Installation

composer require improved/iterable

Methods

General methods

• then(callable $callback, mixed ...$args)
• getIterator()
• toArray()
• walk()

Chainable methods

Mapping

• map(callable $callback)
• mapKeys(callable $callback)
• apply(callable $callback)
• chunk(int $size)
• group(callable $callback)
• unwind(int|string $column[, int|string|null $mapKey[, bool $preserveKeys]])
• flatten()
• fill(mixed $value)
• column(int|string|null $valueColumn[, int|string|null $keyColumn])
• project(array $mapping)
• reshape(array $columns)
• values()
• keys()
• setKeys(Traversable $keys)
• flip()

Filtering

• filter(callable $matcher)
• cleanup()
• unique([callable $callback])
• uniqueKeys()
• limit(int $size)
• slice(int $offset[, int $size])
• before(callable $matcher[, bool $include])
• after(callable $matcher[, bool $include])

Sorting

• sort([int|callable $compare[, bool $preserveKeys]])
• sortKeys([int|callable $compare])
• reverse()

Type handling

• typeCheck(string|string[] $type[, \Throwable $error])
• typeCast(array $type[, \Throwable $error])

Other methods

Finding

• first([bool $required])
• last([bool $required])
• find(callable $matcher)
• findKey(callable $matcher)
• min([callable $compare])
• max([callable $compare])

Aggregation

• count(): int
• reduce(callable $callback[, mixed $initial])
• sum(): int|float
• average(): int|float
• concat([string $glue]): string

Builder methods

• stub(string $name)
• unstub(string $name, callable callable, mixed ...$args)

Example

All functions and objects are in the Improved namespace. Either alias the namespace as i or import each function individually.

Alternatively use the iterator pipeline.

Usage

This library provides Utility methods for creating streams.

Pipeline takes an array or Traversable object as source argument. The static with() method can be used instead of new.

A pipeline uses PHP generators, which are forward-only and non-rewindable. This means a pipeline can only be used one.

PipelineBuilder

The PipelineBuilder can be used to create a blueprint for pipelines. The builder contains the mapping methods of Pipeline and not the other methods.

The static Pipeline::build() method can be used as syntax sugar to create a builder.

A PipelineBuilder is an immutable object, each method call creates a new copy of the builder.

Alternatively the pipeline builder can be invoked, which creates a pipeline and calls toArray() on it.

The then() method can be used to combine two pipeline builder.

Custom Pipeline class

A Pipeline is not an immutable object, unlike the PipelineBuilder. Only the iterable returned from latest step is relevant and kept by the pipeline. As such, you can extend the Pipeline class and use that any chainable method, without the object changing.

However is a step returns a Pipeline object (including any object that extends the pipeline), the then method will return that object instead of $this. This can be used to inject a custom class later in a pipe or in a pipeline builder.

Starting with your custom class

In an existing pipeline

In a pipeline builder

This is the only way to get a PipelineBuilder to return a custom Pipeline class without also creating a custom PipelineBuilder.

Method reference

then

The then() method defines a new step in the pipeline. As argument it takes a callback that must return a Generator or other Traversable.

It may be used to apply a custom (outer) iterator.

getIterator

The Pipeline implements the IteratorAggregate interface. This means it's traversable. Alternatively you can use getIterator().

toArray

Copy the elements of the iterator into an array.

walk

Traverse over the iterator, not capturing the values. This is particularly useful after apply().

Mapping

map

Map each element to a value using a callback function.

The second argument of the callback is the key.

mapKeys

Map the key of each element to a new key using a callback function.

The second argument of the callback is the value and second is the key.

apply

Apply a callback to each element of an iterator. Any value returned by the callback is ignored.

chunk

Divide iterable into chunks of specified size.

Chunks are iterators rather than arrays. Keys are preserved.

group

Group elements of an iterator, with the group name as key and an array of elements as value.

The second argument is the key.

flatten

Walk through all sub-iterables and concatenate them.

By default the keys are dropped, replaces by an incrementing counter (so as an numeric array). By passing true as second parameters, the keys are remained.

unwind

Deconstruct an iterable property/item for each element. The result is one element for each item in the iterable property. You must specify which column to unwind.

The second argument is optional, taking a column name to add each key to the element.

By default each new element of the resulting iterator is a numeric sequence. To preverse the keys, pass true as third argument. Beware that this will result in duplicate keys.

fill

Set all values of the iterable. Don't touch the keys.

This can be used in combination with flip to something similar to array_fill_keys.

column

Return the values from a single column / property. Each element should be an array or object.

Create key/value pairs by specifying the key.

Alternatively you may only specify the key column, using null for the value column, to keep the value unmodified.

If an element doesn't have a specified key, the key and/or value will be null.

project

Project each element of an iterator to an associated (or numeric) array. Each element should be an array or object.

For the projection, a mapping [new key => old key] must be supplied.

If an element doesn't have a specified key, the value will be null.

The order of keys of the projected array is always the same as the order of the mapping. The mapping may also be a numeric array.

reshape

Reshape each element of an iterator, adding or removing properties or keys.

The method takes an array with the column name as key. The value may be a boolean, specifying if th column should remain or be removed. Alternatively the column may be a string or int, renaming the column name (key).

Columns that are not specified are untouched. This has the same effect as 'column' => true.

Note that unlike with project(), the array or object is modified. If the element does not have the specific key, it's ignored. If the element is not an object or array, it's untouched.

values

Keep the values, drop the keys. The keys become an incremental number. This is comparable to array_values.

keys

Use the keys as values. The keys become an incremental number. This is comparable to array_keys.

setKeys

Use another iterator as keys and the current iterator as values.

The key may be any type and doesn't need to be unique.

The number of elements yielded from the iterator only depends on the number of keys. If there are more keys than values, the value defaults to null. If there are more values than keys, the additional values are not returned.

flip

Use values as keys and visa versa.

Both the value and key may be any type and don't need to be unique.

Filtering

filter

Eliminate elements based on a criteria.

The callback function is required and should return a boolean.

The second argument of the callback is the key.

cleanup()

Filter out null values or null keys from iterable.

With iterators, keys may be of any type. Elements with null keys are also filtered out.

unique

Filter on unique elements.

You can pass a callback, which should return a value. Filtering on distinct values will be based on that value.

All values are stored for reference. The callback function can also be used to serialize and hash the value.

The seconds argument is the key.

Uses strict comparison (===), so '10' and 10 won't match.

uniqueKeys

The keys of an iterator don't have to be unique (and don't have to be a scalar). This is unlike an associated array.

The uniqueKeys() method filters our duplicate keys.

limit

Get only the first elements of an iterator.

slice

Get a limited subset of the elements using an offset.

You may also specify a limit.

before

Get elements until a match is found.

The seconds argument is the key.

Optionally the matched value can be included in the result

after

Get elements after a match is found.

The seconds argument is the key.

Optionally the matched value can be included in the result

Sorting

Sorting requires traversing through the iterator to index all elements.

sort

Create an iterator with sorted elements.

Instead of using the default sorting, a callback may be passed as user defined comparison function.

The callback must return < 0 if str1 is less than str2; > 0 if str1 is greater than str2, and 0 if they are equal.

sortKeys

Create an iterator with sorted elements by key.

A callback may be passed as user defined comparison function.

reverse

Create an iterator with elements in the reversed orderd. The keys are preserved.

Type handling

typeCheck

Validate that a value has a specific type using type_check. A TypeError is thrown if any element of the iterable doesn't match the type.

As type you may specific any PHP type, a pseudo types like iterable or callable, as class name or a resource type. For resources use the resource type, plus "resource", eg "stream resource".

As second argument, a Throwable object may be passed, this is either an Exception or Error.

The error message may contain up to three sprintf place holders. The first %s is replaced with the type of the value. The second is used for the description of the key. The third is typically not needed, but when specified is replaced with the given type(s).

A question mark can be added to a class to accept null, eg "?string" is similar to using ["string", "null"].

typeCast

Cast a value to the specific type. This method uses type_cast.

If the value can't be cast, a TypeError is thrown. Similar to typeCheck() a Throwable with a message may be passed as second argument.

In contrary typeCheck, only one type may be specified. A question mark can be added to a class to accept null, eg ?string will try to cast everything to a string except null.

Finding

These methods invoke traversing through the iterator and return a single element.

first

Get the first element.

Optionally a RangeException can be thrown if the iterable is empty.

last

Get the last element.

find

Find the first element that matches a condition. Returns null if no element is found.

It's possible to use the key in this callable.

findKey

Find the first element that matches a condition and return the key (rather than the value). Returns null if no element is found.

It's possible to use the key in this callable.

hasAny

Check if any element matches the given condition.

The callback is similar to find.

hasAll

Check if all elements match the given condition.

The callback is similar to find.

hasNone

Check the no element matches the given condition. This is the inverse of hasAny().

The callback is similar to find.

min

Returns the minimal element according to a given comparator.

It's possible to pass a callable for custom logic for comparison.

max

Returns the maximal element according to a given comparator.

It's possible to pass a callable for custom logic for comparison.

Aggregation

Traverse through all elements and reduce it to a single value.

count

Returns the number of elements.

reduce

Reduce all elements to a single value using a callback.

The third argument is the key

sum

Calculate the sum of a numbers. If no elements are present, the result is 0.

average

Calculate the arithmetic mean. If no elements are present, the result is NAN.

concat

Concatenate the input elements, separated by the specified delimiter, in encounter order.

This is comparable to implode on normal arrays.

stub

The stub() method a stub step, which does nothing but can be replaced later using unstub().

PipelineBuilder stub(string name)
PipelineBuilder unstub(string name, callable $callable, mixed ...$args) 

These methods only exists in the pipeline builder.

What are iterators?

Iterators are traversable objects. That means that when you use them in a foreach loop, you're not looping through the properties of the object. Instead the current(), key() and valid() methods are called each time we go through the loop.

The current() method gives the current value, the key() method gives the current key and the valid() method checks if we're should continue looping.

In the following example we extend IteratorIterator to overwrite the current() class.

At this point nothing is executed. Neither string_case_convert or string_replace. Only once we loop, these functions are called.

This will be the same as doing

Difference to working with arrays

When working with arrays, we tend to loop through them for each operation. Look at array_map

Which is similar to

Of course we could combine these operators an apply them in a simple loop without the use of iterators. However this couples all that logic. If a method returns all values in upper case, a second and unrelated method (in a different class) might remove the spaces. For iterators this doesn't matter.

Iterator keys

With iterators, the key doesn't need to be a string or integer, but can be any type and doesn't need to be unique.

It can very convenient to make the key an array or object and keeping the value a scalar. As such you can do link operations like case conversion, etc. Another application is to group child objects per parent object.

Generators

Generators are special iterators which are automatically created by PHP when you use the yield syntax.

PHP 7.2+ is highly optimized to work with generators increasing performance and saving memory. This makes generators preferable to custom iterators, which can be slow.

Unexpected generator behaviour

If you add a return statement, the function will still return a Generator object. You can get that result with the Generator->getReturn() method, but this is typically not what's intended.

The following code will not work as intended. It will not return an array, but always a Generator object.

Also note that the none of the code in the get_values function will execute until the we start the loop

Forward-only iterators

Some iterators, including generators, are forward-only iterators, meaning you can only loop through them once.

This has consequences when using the iterable_ functions and Pipeline objects. Though this can be overcome using a PipelineBuilder.

And now you know :-)