Iterators implemented in PHP, copy-pasted from Python

1.6.5 2019-01-30 11:02 UTC


A set of iterators for PHP based on pythons itertools.

Build Status Scrutinizer Quality Score Code Coverage

Some iterator examples

// iterate the lines of a csv file
$lines = new FileLineIterator('file.csv');

// filter all non unique lines
$uniqueLines = new UniqueIterator($lines);

// convert unique csv string lines to array
$rows = new StringCsvIterator($uniqueLines);

// extract column 1 from the csv file
$column1 = new MapIterator($rows, function($row) { return $row['column1']; });

// output all rows in parallel
foreach(new ForkingIterator($column1) as $row) {
    echo $row;

Install Guide

composer require suramon/itertools

Manual Install

  1. Download itertools directly from GitHub, or clone it with Git: git clone
  2. Include the autoload header located in src/autload.php (eg: require 'relike/src/autoload.php';) or you can use psr-0
  3. Learn and use itertools by looking at the examples, tests and source code

Some iterators explained


Iterator equivalent of flattening a 2-dimensional array.

$iterators = new ArrayIterator(array(new RangeIterator(1, 5), new RangeIterator(6, 10)));
$fattenedIterators = new ChainIterator($iterators); // will contain all numbers from 1 to 10


Splits a iterator into smaller chunks. this can be used for batch processing.

$iterator = new RangeIterator();
$batchsize = 100;
foreach(new ChunkingIterator($iterator, $batchsize) as $chunk) {
    foreach($chunk as $element) {
        // process the iterator elements. using the transaction inside the chunkiterator makes sure the transaction stays small


This linux-only iterator is designed to be iterated by a foreach loop and forks a new process for each iteration.

$elements = new RangeIterator(0, 10);
foreach(new ForkingIterator($elements) as $i) {
    var_dump($i, getmypid()); // wil spawn a new process to iterate each element


An iterator that keeps track of the elements it iterates. It differs from the CachingIterator in the standard PHP library because this implementations allows the history size to be specified.

$range = new HistoryIterator(new ArrayIterator(range(1, 10)));
foreach($range as $i) {
    if($range->hasPrev()) {
        echo $i, $range->prev(), "\n";


Iterator equivalent or array_map.

$positiveNumbers = new RangeIterator(0, INF); // all numbers from 0 to infinity
$positiveSquareNumbers = new MapIterator($positiveNumbers, function($n) {return $n*$n;}); // all positive square numbers


Iterator equivalent of array_slice.

$lines = new SliceIterator(new FileLineIterator('file.txt'), 0, 1000); // will iterate the first 1000 lines of the file


Iterator equivalent of array_unique but only works for sorted input.

$uniqueEntries = new UniqueIterator(new ArrayIterator(array(1, 2, 2, 2, 3, 4, 2))); // will contain 1, 2, 3, 4, 2


Iterator equivalent of range.

$lines = new SliceIterator(new FileLineIterator('file.txt'), 0, 1000); // will iterate the first 1000 lines of the file


Inspired by pythons zip function. It can be constructed with an array of iterators and it iterates all of its arguments at the same index, returning during each iteration an array of the elements of each iterator on the same iteration positon

$csv1 = new FileCsvIterator('file1.csv');
$csv2 = new FileCsvIterator('file2.csv');
foreach(new ZipIterator(array($csv1, $csv2)) as $combinedRows) {
    $row1 = $combinedRows[0]; // a row in file1.csv
    $row2 = $combinedRows[1]; // row in file2.csv on same position