The League of Extraordinary Packages

Our Packages:

Presented by The League of Extraordinary Packages

Getting Started

The API

Upgrading Guide

Query Filtering

Query Filters

You can restrict extract methods and conversion methods output by setting query options. To set those options you will need to use the methods described below. But keep in mind that:

Modifying content methods

AbstractCsv::stripBOM

This method specifies if the BOM sequence must be removed or not from the CSV’s first cell of the first row.

<?php

public AbstractCsv::stripBOM(bool $status): AbstractCsv

stripBom’s only argument $status must be a boolean.

The actual stripping will take place only if a BOM sequence is detected and the first row is selected in the resultset or if its offset is used as the first argument of the Reader::fetchAssoc method.

The BOM sequence is never removed from the CSV document, it is only stripped from the resultset.

Filtering methods

The filtering options are the first settings applied to the CSV before anything else. The filters follow the First In First Out rule.

AbstractCsv::addFilter

The addFilter method adds a callable filter function each time it is called.

<?php

public AbstractCsv::addFilter(callable $callable): AbstractCsv

The callable filter signature is as follows:

<?php

function(array $row [, int $rowOffset [, Iterator $iterator]]): AbstractCsv

It takes up to three parameters:

Sorting methods

The sorting options are applied after the CSV filtering options. The sorting follows the First In First Out rule.

To sort the data iterator_to_array is used, which could lead to a performance penalty if you have a heavy CSV file to sort

AbstractCsv::addSortBy

addSortBy method adds a sorting function each time it is called.

<?php

public AbstractCsv::addSortBy(callable $callable): AbstractCsv

The callable sort function signature is as follows:

<?php

function(array $row, array $row): int

The sort function takes exactly two parameters, which will be filled by pairs of rows.

Interval methods

The interval methods enable returning a specific interval of CSV rows. When called more than once, only the last filtering settings is taken into account. The interval is calculated after filtering and/or sorting but before extracting the data.

The interval API is made of the following method

<?php

public AbstractCsv::setOffset(int $offset = 0): AbstractCsv
public AbstractCsv::setLimit(int $limit = -1): AbstractCsv

Where

Both methods have no effect on the fetchOne method output.

Examples

Modifying extract methods output

Here’s an example on how to use the query features of the Reader class to restrict the fetchAssoc result:

<?php

use League\Csv\Reader;

function filterByEmail($row)
{
    return filter_var($row[2], FILTER_VALIDATE_EMAIL);
}

function sortByLastName($rowA, $rowB)
{
    return strcmp($rowB[1], $rowA[1]);
}

$reader = Reader::createFromPath('/path/to/file.csv');
$data = $reader
    ->stripBom(false)
    ->setOffset(3)
    ->setLimit(2)
    ->addFilter('filterByEmail')
    ->addSortBy('sortByLastName')
    ->fetchAssoc(['firstname', 'lastname', 'email'], function ($value) {
    return array_map('strtoupper', $value);
});
// data length will be equals or lesser that 2 starting from the row index 3.
// will return something like this :
//
// [
//   ['firstname' => 'JANE', 'lastname' => 'RAMANOV', 'email' => 'JANE.RAMANOV@EXAMPLE.COM'],
//   ['firstname' => 'JOHN', 'lastname' => 'DOE', 'email' => 'JOHN.DOE@EXAMPLE.COM'],
// ]
//

Modifying conversion methods output

The query options can also modify the output from the conversion methods as shown below with the toHTML method.

<?php

use League\Csv\Reader;

function filterByEmail($row)
{
    return filter_var($row[2], FILTER_VALIDATE_EMAIL);
}

function sortByLastName($rowA, $rowB)
{
    return strcmp($rowB[1], $rowA[1]);
}

$reader = Reader::createFromPath('/path/to/file.csv');
$data = $reader
    ->stripBom(true)
    ->setOffset(3)
    ->setLimit(2)
    ->addFilter('filterByEmail')
    ->addSortBy('sortByLastName')
    ->toHTML("simple-table");
// $data contains the HTML table code equivalent to:
//
//<table class="simple-table">
//  <tr><td>JANE</td><td>RAMANOV</td><td>JANE.RAMANOV@EXAMPLE.COM</td></tr>
//  <tr><td>JOHN</td><td>DOE</td><td>JOHN.DOE@EXAMPLE.COM</td></tr>
//</table>
//