The League of Extraordinary Packages

Our Packages:

Presented by The League of Extraordinary Packages

Getting Started

Connections

Inserting Records

Selecting Records

Converting Records

Upgrading Guide

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

Constraint Builder

<?php

public Statement::where(callable $callable): self
public Statement::orderBy(callable $callable): self
public Statement::offset(int $offset): self
public Statement::limit(int $limit): self
public Statement::columns(array $columns): self
public Statement::process(Reader $reader): RecordSet

The League\Csv\Statement class is a constraint builder to help ease selecting records from a CSV document created using the League\Csv\Reader class.

When building a constraint, the methods do not need to be called in any particular order, and may be called multiple times. Because the Statement object is immutable, each time its constraint methods are called they will return a new Statement object without modifying the current Statement object.

Tips: Because the Statement object is independent of the Reader object it can be re-use on multiple Reader objects.

Filtering constraint

The filters attached using the Statement::where method are the first settings applied to the CSV before anything else. This option follow the First In First Out rule.

<?php

public Statement::where(callable $callable): self

The callable filter signature is as follows:

<?php

function(array $record [, int $offset [, Iterator $iterator]]): self

It takes up to three parameters:

Sorting constraint

The sorting options are applied after the Statement::where options. The sorting follows the First In First Out rule.

Warning: 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

Statement::orderBy method adds a sorting function each time it is called.

<?php

public Statement::orderBy(callable $callable): self

The callable sort function signature is as follows:

<?php

function(array $recordA, array $recordB): int

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

Interval constraint

The interval methods enable returning a specific interval of CSV records. When called more than once, only the last filtering settings is taken into account. The interval is calculated after applying Statement::where and Statement::orderBy options.

The interval API is made of the following method

<?php

public Statement::offset(int $offset): self
public Statement::limit(int $limit): self

Statement::offset specifies an optional offset for the return data. By default if no offset was provided the offset equals 0.

Statement::Limit specifies an optional maximum records count for the return data. By default if no limit is provided the limit equals -1, which translate to all records.

When called multiple times, each call override the last settings for these options.

Select constraint

This option enables mapping and selecting specific columns from each record.

<?php

public Statement::columns(array $columns): self

The single parameter is an associative array where:

The Statement::columns option is the last to be applied. So you can not use the alias with the Statement::where or the Statement::orderBy methods.

Tips: To reset the columns value, you need to provide an empty array.

When called multiple times, each call override the last settings for this option.

If the Reader object has no header

<?php

use League\Csv\Statement;

$stmt = (new Statement())
    ->columns(['firstname', 'lastname', 'email'])
;

// is equivalent to:

$stmt = (new Statement())
    ->columns([
        0 => 'firstname',
        1 => 'lastname',
        2 => 'email',
    ])
;

If the Reader object has a header

<?php

use League\Csv\Statement;

$stmt = (new Statement())
    ->columns(['firstname', 'lastname', 'email'])
;

// is equivalent to:

$stmt = (new Statement())
    ->columns([
        'firstname' => 'firstname',
        'lastname' => 'lastname',
        'email' => 'email',
    ])
;

If a Reader object has a header and the column uses undefined header value a RuntimeException is triggered.

Apply the constraints to a CSV document

<?php

public Statement::process(Reader $reader): RecordSet

This method processes a Reader object and returns the found records as a RecordSet object.

<?php

use League\Csv\Reader;
use League\Csv\Statement;

function filterByEmail(array $record): bool
{
    return (bool) filter_var($record[2], FILTER_VALIDATE_EMAIL);
}

function sortByLastName(array $recordA, array $recordB): int
{
    return strcmp($recordB[1], $recordA[1]);
}

$reader = Reader::createFromPath('/path/to/file.csv');
$reader->addStreamFilter('string.toupper');
$stmt = (new Statement())
    ->offset(3)
    ->limit(2)
    ->where('filterByEmail')
    ->orderBy('sortByLastName')
    ->columns(['firstname', 'lastname', 'email'])
;

$records = $stmt->process($reader);

Tips: this method is equivalent of Reader::select.