Looping the Loop with SPL Iterators

Looping the
Loop
with
SPL Iterators

Looping the Loop with SPL
Iterators
What is an Iterator?
An Iterator is an object that enables a programmer to
traverse a container, particularly lists.
A Behavioural Design Pattern (GoF)

Iterators
$dataSet = ['A', 'B', 'C'];
foreach($dataSet as $key => $value) {
echo "{$key} => {$value}", PHP_EOL;
}

Iterators
0 => A
1 => B
2 => C

Iterators
$data = ['A', 'B', 'C'];
$dataSet = new ArrayIterator($data);
foreach($dataSet as $key => $value) {
}

Iterators
interface Iterator extends Traversable {
/* Methods */
abstract public current ( void ) : mixed
abstract public key ( void ) : scalar
abstract public next ( void ) : void
abstract public rewind ( void ) : void
abstract public valid ( void ) : bool
}

Iterators
$data = ['A', 'B', 'C'];
$iterator = new ArrayIterator($data);
$iterator->rewind();
while ($iterator->valid()) {
$key = $iterator->key();
$value = $iterator->current();
$iterator->next();
}

Iterators

Iterators
The Iterable Tree
iterable
array
Traversable
Iterator
Generator
IteratorAggregate

Iterators
The Iterable Tree
Not all iterables are equal
You can count the elements in an array !
Can you count the elements in an Iterator?

Iterators
The Iterable Tree
You can access the elements of an array by
their index !
Can you access the elements of an Iterator
by index ?

Iterators
The Iterable Tree
You can rewind an Iterator !
Can you rewind a Generator ?

Iterators
The Iterable Tree
Iterator_* functions (e.g. iterator_to_array)
work on Iterators ?
Can you use iterator_* functions on an
IteratorAggregate ?

Iterators
The Iterable Tree
iterable
array
Traversable
Iterator
Generator
IteratorAggregate
Iterable is a pseudo-type
introduced in PHP 7.1. It accepts
any array, or any object that
implements the Traversable
interface. Both of these types are
iterable using foreach.

Iterators
The Iterable Tree
iterable
array
Traversable
Iterator
Generator
IteratorAggregate
An array in PHP is an ordered map, a
type that associates values to keys. This
type is optimized for several different
uses; it can be treated as an array, list
(vector), hash table (an implementation
of a map), dictionary, collection, stack,
queue, and more.
The foreach control structure exists
specifically for arrays.

Iterators
The Iterable Tree
iterable
array
Traversable
Iterator
Generator
IteratorAggregate
Abstract base interface to detect if a
class is traversable using foreach. It
cannot be implemented alone in
Userland code; but instead must be
implemented through either
IteratorAggregate or Iterator.
Internal (built-in) classes that implement
this interface can be used in a foreach
construct and do not need to implement

Iterators
The Iterable Tree
iterable
array
Traversable
Iterator
Generator
IteratorAggregate
Abstract base interface to detect if a
class is traversable using foreach. It
cannot be implemented alone in
Userland code; but instead must be
implemented through either
PDOStatement
DatePeriod
SimpleXMLElement

Iterators
The Iterable Tree
iterable
array
Traversable
Iterator
Generator
IteratorAggregate
An Interface for external iterators or
objects that can be iterated themselves
internally.
PHP already provides a number of
iterators for many day to day tasks
within the Standard PHP Library (SPL).
SPL Iterators
SPL DataStructures
WeakMaps (PHP 8)

Iterators
The Iterable Tree
iterable
array
Traversable
Iterator
Generator
IteratorAggregate
Generators provide an easy way to
implement simple user-defined iterators
without the overhead or complexity of
implementing a class that implements
the Iterator interface.
This flexibility does come at a cost,
however: generators are forward-only
iterators, and cannot be rewound once
iteration has started.

Iterators
The Iterable Tree
iterable
array
Traversable
Iterator
Generator
IteratorAggregate
IteratorAggregate is a special interface
for implementing an abstraction layer
between user code and iterators.
Implementing an IteratorAggregate will
allow you to delegate the work of
iteration to a separate class, while still
enabling you to use the collection inside
a foreach loop.

Iterators
Implementing an Iterator
interface Iterator extends Traversable {
/* Methods */
abstract public current ( void ) : mixed
abstract public key ( void ) : scalar
abstract public next ( void ) : void
abstract public rewind ( void ) : void
abstract public valid ( void ) : bool
}

Iterators
class Utf8StringIterator implements Iterator {
private $string;
private $offset = 0;
private $length = 0;
public function __construct(string $string) {
$this->string = $string;
$this->length = iconv_strlen($string);
}
public function valid(): bool {
return $this->offset < $this->length;
}
...
}

Iterators
class Utf8StringIterator implements Iterator {
...
public function rewind(): void {
$this->offset = 0;
}
public function current(): string {
return iconv_substr($this->string, $this->offset, 1);
}
public function key(): int {
return $this->offset;
}
public function next(): void {
++$this->offset;
}
}

Iterators
$stringIterator = new Utf8StringIterator('Καλησπέρα σε όλους');
foreach($stringIterator as $character) {
echo "[{$character}]";
}

Iterators
[Κ][α][λ][η][σ][π][έ][ρ][α][ ][σ][ε][ ][ό][λ][ο][υ][ς]

Iterators
class FileLineIterator implements Iterator {
private $fileHandle;
private $line = 1;
public function __construct(string $fileName) {
$this->fileHandle = fopen($fileName, 'r');
}
public function __destruct() {
fclose($this->fileHandle);
}
}

Iterators
...
public function current(): string {
$fileData = fgets($this->fileHandle);
return rtrim($fileData, "n");
}
public function key(): int {
return $this->line;
}
public function next(): void {
++$this->line;
}
}

Iterators
...
public function rewind(): void {
fseek($this->fileHandle, 0);
$this->line = 1;
}
public function valid(): bool {
return !feof($this->fileHandle);
}
}

Iterators
$fileLineIterator = new FileLineIterator(__FILE__);
foreach($fileLineIterator as $lineNumber => $fileLine) {
echo "{$lineNumber}: {$fileLine}", PHP_EOL;
}

Iterators
1: <?php
2:
3: class FileLineIterator implements Iterator {
4: private $fileHandle;
5: private $line = 1;
6:
7: public function __construct(string $fileName) {
8: $this->fileHandle = fopen($fileName, 'r’);
9: }
10:
…

Iterators
class UserRepository {
// ...
public function all(): array {
$userQuery = 'SELECT * FROM `users` ...';
$statement = $this->pdo->prepare($userQuery);
$statement->execute();
$users = $statement->fetchAll();
return array_map(fn(array $user): User => User::fromArray($user), $users);
}
}

Iterators
// ...
/**
* @return User[]
*/
public function all(): array {
return array_map(fn(array $user): User => User::fromArray($user), $users);
}
}

Iterators
class UserCollection extends ArrayIterator {
}

Iterators
// ...
public function all(): UserCollection {
return new UserCollection(
array_map(fn(array $user): User => User::fromArray($user), $users)
);
}
}

Iterators
class UserCollection extends ArrayIterator {
public function current(): User {
return User::fromArray(parent::current());
}
}

Iterators
// ...
return new UserCollection($users);
}
}

Iterators
ArrayIterator
Implements:
Countable
ArrayAccess
Serializable
SeekableIterator (which entends Iterator)

Iterators
ArrayIterator
Implements:
Countable

Iterators
ArrayIterator – Countable
interface Countable {
/* Methods */
abstract public count ( void ) : int
}

Iterators
$userData = ['user1', 'user2', 'user3', 'user4'];
$userList = new UserList($userData);
$userCount = count($userList);
echo "There are {$userCount} users in this list", PHP_EOL;

Iterators
echo "There are {$userList->count()} users in this list", PHP_EOL;

Iterators
There are 4 users in this list

Iterators
ArrayIterator
Implements:
Countable
ArrayAccess

Iterators
ArrayIterator – ArrayAccess
interface ArrayAccess {
/* Methods */
abstract public offsetExists ( mixed $offset ) : bool
abstract public offsetGet ( mixed $offset ) : mixed
abstract public offsetSet ( mixed $offset , mixed $value ) : void
abstract public offsetUnset ( mixed $offset ) : void
}

Iterators
echo "The 3rd entry in the list is {$userList[2]}", PHP_EOL;

Iterators
The 3rd entry in the list is user3

Iterators
ArrayIterator
Implements:
Countable
ArrayAccess
Serializable

Iterators
ArrayIterator – Serializable
interface Serializable {
/* Methods */
abstract public serialize ( void ) : string
abstract public unserialize ( string $serialized ) : void
}

Iterators
var_dump(serialize($userList));

Iterators
string(117)
"O:8:"UserList":4:{i:0;i:0;i:1;a:4:{i:0;s:5:"user1";
i:1;s:5:"user2";i:2;s:5:"user3";i:3;s:5:"user4";}i:2;
a:0:{}i:3;N;}"

Iterators
ArrayIterator – SeekableIterator
SeekableIterator extends Iterator {
/* Methods */
abstract public seek ( int $position ) : void
/* Inherited methods */
abstract public Iterator::current ( void ) : mixed
abstract public Iterator::key ( void ) : scalar
abstract public Iterator::next ( void ) : void
abstract public Iterator::rewind ( void ) : void
abstract public Iterator::valid ( void ) : bool
}

Iterators
$userList->seek(2);
while ($userList->valid()) {
echo $userList->current(), PHP_EOL;
$userList->next();
}

Iterators
user3
user4

Iterators
$userList->seek(2);
foreach($userList as $userName) {
echo $userName, PHP_EOL;
}

Iterators
user1
user2
user3
user4


Iterators
$userData = ['A' => 'user1', 'B' => 'user2', 'C' => 'user3', 'D' => 'user4'];
$userList->seek('C');
while ($userList->valid()) {
echo $userList->current(), PHP_EOL;
$userList->next();
}

Iterators
PHP7
Warning:
ArrayIterator::seek() expects parameter 1 to be int,
string given


Iterators
PHP8
Fatal error: Uncaught TypeError
ArrayIterator::seek(): Argument #1 ($position) must be
of type int, string given


Iterators
ArrayIterator
Implements:
Countable
ArrayAccess
Serializable
SeekableIterator (which entends Iterator)
Also provides methods for sorting
Doesn’t work with array_* functions

Iterators
LimitIterator
$userList = new LimitIterator(
new UserList($userData),
2,
1
);
foreach($userList as $value) {
echo $value, PHP_EOL;
}

Iterators
LimitIterator
user3

Iterators
InfiniteIterator
$weekdayNames = ['Sun', 'Mon', 'Tues', 'Wed', 'Thurs', 'Fri', 'Sat'];
$todayOffset = (int) (new DateTime('2020-09-08'))->format('w');
$weekdayList = new LimitIterator(
new InfiniteIterator( new ArrayIterator($weekdayNames) ),
$todayOffset,
14
);
foreach($weekdayList as $dayOfWeek) {
echo $dayOfWeek, PHP_EOL;
}

Iterators
InfiniteIterator
Tues
Wed
Thurs
Fri
Sat
Sun
Mon
Tues
Wed
Thurs
Fri
Sat
Sun
Mon

Iterators
CallbackFilterIterator
$workdayList = new CallbackFilterIterator(
new LimitIterator(
$todayOffset,
14
),
fn($dayName): bool => $dayName !== 'Sat' && $dayName !== 'Sun'
);
foreach($workdayList as $dayOfWeek) {
}

Iterators
Tues
Wed
Thurs
Fri
Mon
Tues
Wed
Thurs
Fri
Mon

Iterators
FilterIterator
abstract FilterIterator extends IteratorIterator implements OuterIterator {
/* Methods */
public abstract accept ( void ) : bool
public __construct ( Iterator $iterator )
public current ( void ) : mixed
public getInnerIterator ( void ) : Iterator
public key ( void ) : mixed
public next ( void ) : void
public rewind ( void ) : void
public valid ( void ) : bool
}

Iterators
FilterIterator
class ImageFileIterator extends FilterIterator {
// Overwrite the constructor to automagically create an inner iterator
// to iterate the file system when given a path name.
public function __construct(string $path) {
parent::__construct(new FilesystemIterator($path));
}
// Overwrite the accept method to perform a super simple test to
// determine if the files found were images or not.
public function accept(): bool {
$fileObject = $this->getInnerIterator()->current();
return preg_match('/^(?:gif|jpe?g|png)$/i', $fileObject->getExtension());
}
}

Iterators
FilterIterator
// Overwrite the constructor to automagically create an inner iterator
// to iterate the file system when given a path name.
public function __construct(string $path) {
parent::__construct(new FilesystemIterator($path));
}
// Overwrite the accept method to perform a super simple test to
// determine if the files found were images or not.
public function accept(): bool {
return preg_match('/^(?:gif|jpe?g|png)$/i', $this->getExtension());
}
}

Iterators
FilterIterator
$path = dirname(__FILE__);
foreach(new ImageFileIterator($path) as $imageObject) {
echo $imageObject->getBaseName(), PHP_EOL;
}

Iterators
FilterIterator
anubis.jpg
Carpet.jpg
Crazy Newspaper Headlines.jpg
elephpant.jpg
Pie Chart.jpg
PowerOfBooks.jpg
Struggling-Team.png
TeddyBears.jpg

Iterators
Iterator Keys
...
// Overwrite the key method to return the file extension as the key
public function key(): string {
return $this->getExtension();
}
}
foreach(new ImageFileIterator($path) as $extension => $imageObject) {
echo "{$extension} => {$imageObject->getBaseName()}", PHP_EOL;
}

Iterators
Iterator Keys
jpg => anubis.jpg
jpg => Carpet.jpg
jpg => Crazy Newspaper Headlines.jpg
jpg => elephpant.jpg
jpg => Pie Chart.jpg
jpg => PowerOfBooks.jpg
png => Struggling-Team.png
jpg => TeddyBears.jpg

Iterators
Iterator Keys
...
// Overwrite the key method to return the last modified date/time as the key
public function key(): DateTime {
return DateTime::createFromFormat('U', $this->getMTime());
}
}
foreach(new ImageFileIterator($path) as $date => $imageObject) {
echo "{$date->format('Y-m-d H:i:s')} => {$imageObject->getBaseName()}",
PHP_EOL;
}

Iterators
Iterator Keys
2012-03-24 00:38:24 => anubis.jpg
2013-01-27 22:32:20 => Carpet.jpg
2013-03-07 12:16:24 => Crazy Newspaper Headlines.jpg
2012-02-16 22:31:56 => elephpant.jpg
2012-10-09 11:51:56 => Pie Chart.jpg
2012-07-17 12:22:32 => PowerOfBooks.jpg
2012-12-30 18:14:24 => Struggling-Team.png
2012-01-31 11:17:32 => TeddyBears.jpg

Iterators
MultipleIterator
$dates = ['Q1-2019', 'Q2-2019', 'Q3-2019', 'Q4-2019'];
$budget = [1200, 1300, 1400, 1500];
$expenditure = [1250, 1315, 1440, 1485];
$budgetElements = count($budget);
for ($i = 0; $i < $budgetElements; $i++) {
echo "{$dates[$i]} - {$budget[$i]}, {$expenditure[$i]}", PHP_EOL;
}

Iterators
MultipleIterator
$dates = ['Q1-2019', 'Q2-2019', 'Q3-2019', 'Q4-2019'];
$budget = [1200, 1300, 1400, 1500];
$expenditure = [1250, 1315, 1440, 1485];
foreach($dates as $key => $period) {
echo "{$period} - {$budget[$key]}, {$expenditure[$key]}", PHP_EOL;
}

Iterators
MultipleIterator
Q1-2019 - 1200, 1250
Q2-2019 - 1300, 1315
Q3-2019 - 1400, 1440
Q4-2019 - 1500, 1485

Iterators
MultipleIterator
function wrapArrayAsIterator(array $array) {
return new ArrayIterator($array);
}
$combinedIterable = new MultipleIterator(MultipleIterator::MIT_KEYS_ASSOC);
$combinedIterable->attachIterator(wrapArrayAsIterator($dates), 'date');
$combinedIterable->attachIterator(wrapArrayAsIterator($budget), 'budget');
$combinedIterable->attachIterator(wrapArrayAsIterator($expenditure), 'expenditure');

Iterators
MultipleIterator
foreach($combinedIterable as $dateValues) {
echo $dateValues['date'],
" - {$dateValues['budget']}, {$dateValues['expenditure']}",
PHP_EOL;
}

Iterators
MultipleIterator
[$date, $budget, $expenditure] = $dateValues;
echo "{$date} - {$budget}, {$expenditure}", PHP_EOL;
}

Iterators
MultipleIterator
extract($dateValues);
echo "{$date} - {$budget}, {$expenditure}", PHP_EOL;
}

Iterators
MultipleIterator
$allocations = $totalAdvance->allocateTo(count($cars));
foreach ($cars as $i => $car) {
$car->setAdvance($allocations[$i]);
}

Iterators
MultipleIterator
$allocations = $totalAdvance->allocateTo(count($cars));
$advanceAllocations = new MultipleIterator(MultipleIterator::MIT_KEYS_ASSOC);
$advanceAllocations->attachIterator(ArrayIterator($cars), 'car');
$advanceAllocations->attachIterator(ArrayIterator($allocations), 'advance');
foreach($advanceAllocations as $advanceAllocation) {
extract($advanceAllocation);
$car->setAdvance($advance);
}

Iterators
Inner and Outer Iterators
Inner Iterator
Implements Iterator, or extends a class that
implements Iterator
ArrayIterator
SeekableIterator
FilesystemIterator
MultipleIterator

Iterators
Inner and Outer Iterators
Outer Iterator
Implements OuterIterator, or extends an
Iterator that already implements
OuterIterator
LimitIterator
InfiniteIterator
FilterIterator

Iterators
Recursive Iterators
A RecursiveIterator defines methods to
allow iteration over hierarchical data
structures.
Nested Arrays (and Objects if using
ArrayAccess)
Filesystem Directories/Folders

Iterators
// ...
public function all(): Generator {
while ($user = $statement->fetch()) {
yield User::fromArray($user);
}
}
}

Iterators
// ...
/**
* @return Generator|User[]
*/
public function all(): Generator {
while ($user = $statement->fetch()) {
}
}
}

Iterators
IteratorAggregate
IteratorAggregate extends Traversable {
/* Methods */
abstract public getIterator ( void ) : Traversable
}

Iterators
class UserCollection implements IteratorAggregate {
private PDOStatement $pdoStatement;
public function __construct(PDOStatement $pdoStatement) {
$this->pdoStatement = $pdoStatement;
}
public function getIterator(): Traversable {
$this->pdoStatement->execute();
while ($user = $this->pdoStatement->fetch()) {
}
}
}

Iterators
// ...
return new UserCollection($statement);
}
}

Iterators
Implementing a Fluent Nested Iterator
$workdayList = new CallbackFilterIterator(
new LimitIterator(
$todayOffset,
14
),
);
}

Iterators
class FluentNestedIterator implements IteratorAggregate {
protected iterable $iterator;
public function __construct(iterable $iterator) {
$this->iterator = $iterator;
}
public function with(string $iterable, ...$args): self {
$this->iterator = new $iterable($this->iterator, ...$args);
return $this;
}
public function getIterator() {
return $this->iterator;
}
}

Iterators
$workdayList = (new FluentNestedIterator(new ArrayIterator($weekdayNames)))
->with(InfiniteIterator::class)
->with(LimitIterator::class, $todayOffset, 14)
->with(
CallbackFilterIterator::class,
);
}

Iterators
Thurs
Fri
Mon
Tues
Wed
Thurs
Fri
Mon
Tues
Wed

Iterators
Array Functions
Don’t work with Traversables

Iterators
Array Functions – Filter
function filter(iterable $iterator, Callable $callback = null) {
if ($callback === null) {
$callback = 'iterableFilterNotEmpty';
}
foreach ($iterator as $key => $value) {
if ($callback($value)) {
yield $key => $value;
}
}
}

Iterators
$startTime = new DateTime('2015-11-23 13:20:00Z');
$endTime = new DateTime('2015-11-23 13:30:00Z');
$timeFilter = function($timestamp) use ($startTime, $endTime) {
return $timestamp >= $startTime && $timestamp <= $endTime;
};
$filteredTrackingData = filter(
$gpxReader->getElements('trkpt'),
$timeFilter,
ARRAY_FILTER_USE_KEY
);
foreach ($filteredTrackingData as $time => $element) {
...
}

Iterators
2015-11-23 13:24:40
latitude: 53.5441 longitude: -2.7416 elevation: 124
2015-11-23 13:24:49
2015-11-23 13:24:59
2015-11-23 13:25:09
2015-11-23 13:25:19
2015-11-23 13:25:29
2015-11-23 13:25:39

Iterators
Of course, we could always use a
CallBackFilterIterator

Iterators
Array Functions – Map
function map(Callable $callback, iterable $iterator) {
foreach ($iterator as $key => $value) {
yield $key => $callback($value);
}
}

Iterators
$distanceCalculator = new GpxReaderHelpersDistanceCalculator();
$mappedTrackingData = map(
[$distanceCalculator, 'setDistanceProperty'],
$gpxReader->getElements('trkpt')
);
foreach ($mappedTrackingData as $time => $element) {
...
}

Iterators
2015-11-23 14:57:07
distance from previous point: 6.93 m
2015-11-23 14:57:17
2015-11-23 14:57:27
2015-11-23 14:57:37
2015-11-23 14:57:47

Iterators
Array Functions – Walk
iterator_apply()
iterator_apply(
Traversable $iterator,
Callable $callback
[, array $args = NULL ]
) : int

Iterators
Array Functions – Reduce
function reduce(iterable $iterator, Callable $callback, $initial = null) {
$result = $initial;
foreach($iterator as $value) {
$result = $callback($result, $value);
}
return $result;
}

Iterators
$distanceCalculator = new GpxReaderHelpersDistanceCalculator();
$totalDistance = reduce(
map(
[$distanceCalculator, 'setDistanceProperty'],
$gpxReader->getElements('trkpt')
),
function($runningTotal, $value) {
return $runningTotal + $value->distance;
},
0.0
);

Iterators
Total distance travelled is 4.33 km

Iterators
Array Functions – Other Iterator
Functions
Iterator_count()
iterator_count ( Traversable $iterator ) : int

Iterators
Array Functions – Other Iterator
Functions
Iterator_to_array()
iterator_to_array (
Traversable $iterator
[, bool $use_keys = TRUE ]
) : array

Iterators
A Functional Guide to Cat Herding with PHP
Generators
• https://markbakeruk.net/2016/01/19/a-functional-guide-to-cat-herding-with-php-generators/
• https://markbakeruk.net/2020/01/05/filtering-and-mapping-with-spl-iterators/
• https://markbakeruk.net/2019/12/31/parallel-looping-in-php-with-spls-multipleiterator/

Iterators
Iterating PHP Iterators
By Cal Evans
https://leanpub.com/iteratingphpiterators
by Joshua Thijssen
https://www.phparch.com/books/mastering-the-spl-library/

Who am I?
Mark Baker
Most Recently: Senior Software Engineer
MessageBird BV, Amsterdam
Coordinator and Developer of:
Open Source PHPOffice library
PHPExcel, PHPWord, PHPPowerPoint, PHPProject, PHPVisio
Minor contributor to PHP core (SPL DataStructures)
Other small open source libraries available on github
@Mark_Baker
https://github.com/MarkBaker
http://uk.linkedin.com/pub/mark-baker/b/572/171
http://markbakeruk.net
Looping the
Loop
with
SPL Iterators

Looping the Loop with SPL Iterators

More Related Content

What's hot (20)

Similar to Looping the Loop with SPL Iterators (20)

More from Mark Baker (20)

Recently uploaded (20)

Looping the Loop with SPL Iterators