The League of Extraordinary Packages

Our Packages:

Presented by The League of Extraordinary Packages

Getting Started

Connections Settings

Inserting Records

Selecting Records

Converting Records

Upgrading Guide

This is the documentation for the upcoming version 9.0. This is a work in progress

Stream Filters

To ease performing operations on the CSV document as it is being read from or written to, you can add PHP stream filters to the Reader and Writer objects.

Detecting stream filter support

<?php

public AbstractCsv::supportsStreamFilter(void): bool

Tells whether the stream filter API is supported by the current object.

<?php

use League\Csv\Reader;
use League\Csv\Writer;

$reader = Reader::createFromPath('/path/to/my/file.csv');
$reader->supportsStreamFilter(); //return true

$writer = Writer::createFromFileObject(new SplTempFileObject());
$writer->supportsStreamFilter(); //return false the API can not be use

Warning: A LogicException exception may be thrown if you try to use the API under certain circumstances without prior validation using supportsStreamFilter

Cheat sheet

Here’s a table to quickly determine if PHP stream filters works depending on how the CSV object was instantiated.

Named constructor supportsStreamFilter
createFromString true
createFromPath true
createFromStream true
createFromFileObject false

Adding a stream filter

<?php

public AbstractCsv::addStreamFilter(string $filtername, mixed $params = null): self
public AbstractCsv::hasStreamFilter(string $filtername): bool

The AbstractCsv::addStreamFilter method adds a stream filter to the connection.

Warning: Each time your call addStreamFilter with the same argument the corresponding filter is register again.

The AbstractCsv::hasStreamFilter: tells whether a stream filter is already attached to the connection.

<?php

use League\Csv\Reader;
use MyLib\Transcode;

stream_filter_register('convert.utf8decode', Transcode::class);
// 'MyLib\Transcode' is a class that extends PHP's php_user_filter class

$reader = Reader::createFromPath('/path/to/my/chinese.csv');
if ($reader->supportsStreamFilter()) {
	$reader->addStreamFilter('convert.utf8decode');
	$reader->addStreamFilter('string.toupper');
}

$reader->hasStreamFilter('string.toupper'); //returns true
$reader->hasStreamFilter('string.tolower'); //returns false

foreach ($reader as $row) {
	// each row cell now contains strings that have been:
	// first UTF8 decoded and then uppercased
}

Attached stream filters are removed on the CSV object destruction.

<?php

use League\Csv\Reader;

$fp = fopen('/path/to/my/chines.csv', 'r');
stream_filter_append($fp, 'string.rot13');
$reader = Reader::createFromStream($fp);
$reader->addStreamFilter('convert.utf8decode');
$reader->addStreamFilter('string.toupper');
$reader->hasStreamFilter('string.rot13'); //returns false
$reader = null;
// only the filters attached using addStreamFilter to `$fp` are removed.
// 'string.rot13' is still attached to `$fp`
// filters added using `addStreamFilter` are removed

Only the filters added by the package are removed, filters added to the resource prior to being used in the library are not affected.