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

Result Set

<?php

class ResultSet implements Countable, IteratorAggregate
{
    public function count(): int
    public function fetchAll(): array
    public function fetchColumn(string|int $columnIndex = 0): Generator
    public function fetchOne(int $offset = 0): array
    public function fetchPairs(string|int $offsetIndex = 0, string|int $valueIndex = 1): Generator
    public function getColumnNames(): array
    public function getIterator(): Generator
    public function isRecordOffsetPreserved(): bool
    public function preserveRecordOffset(bool $status): self
}

A League\Csv\ResultSet object represents the associated result set of processing a CSV document with a constraint builder. This object is returned from Reader::select or Statement::process execution.

Result set informations

Accessing the result set column names

<?php
public ResultSet::getColumnNames(): array

ResultSet::getColumnNames returns the columns name information associated with the current object. This is usefull if the ResultSet object was created from a Reader object where Reader::getHeader is not empty;

Example: no header information was given

<?php

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

$reader = Reader::createFromPath('/path/to/my/file.csv');
$records = (new Statement())->process($reader);
$records->getColumnNames(); // is empty because no header information was given

Example: header information given by the Reader object

<?php

use League\Csv\Reader;

$reader = Reader::createFromPath('/path/to/my/file.csv');
$reader->setHeaderOffset(0);

$records = (new Statement())->process($reader);
$records->getColumnNames(); // returns ['First Name', 'Last Name', 'E-mail'];

Accessing the number of records in the result set

The ResultSet class implements implements the Countable interface.

<?php

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

$reader = Reader::createFromPath('/path/to/my/file.csv');
$records = (new Statement())->process($reader);
count($records); //return the total number of records found

Result set options

Preserving the original CSV record offset

<?php

public ResultSet::isRecordOffsetPreserved(): bool
public ResultSet::preserveRecordOffset(bool $status): self

ResultSet::preserveRecordOffset indicates if the ResultSet must keep the original CSV document records offset or can re-index them. When the $status is true, the original CSV document record offset will be preserved and outputted in methods where it makes sense.

At any given time you can tell whether the CSV document offset is kept by calling ResultSet::isRecordOffsetPreserved which returns a boolean.

By default, the ResultSet object does not preserve the original offset.

Iterating over the result set

Description

<?php

public ResultSet::fetchAll(void): array

To iterate over each found records you can:

The foreach construct enables using the memory efficient Generator object.

<?php

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

$reader = Reader::createFromPath('/path/to/my/file.csv');
$records = (new Statement())->process($reader);
foreach ($records as $record) {
    //do something here
}

foreach ($records->fetchAll() as $record) {
    //do something here
}

Accessing the CSV document record offset

If the ResultSet::preserveRecordOffset is set to true, the $offset parameter will contains the original CSV document offset index, otherwise it will contain a numerical index starting from 0.

<?php

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

$reader = Reader::createFromPath('/path/to/my/file.csv');

 //we will start iterating from the 6th record
$stmt = (new Statement())->offset(5);
$records = $stmt->process($reader);
$records->isRecordOffsetPreserved(); //returns false
foreach ($records as $offset => $record) {
    //during the first iteration $offset will be equal to 0
}

$records->preserveRecordOffset(true); //we are preserving the original offset
$records->isRecordOffsetPreserved(); //returns true
foreach ($records->fetchAll() as $offset => $record) {
    //during the first iteration $offset will be equal to 5
}

Usage with the column names

If the ResultSet::getColumnNames is not an empty array the found records keys will contains the method returned values.

<?php

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

$reader = Reader::createFromPath('/path/to/my/file.csv');
$reader->setHeaderOffset(0);
$records = (new Statement())->process($reader);
$records->getColumnNames(); //returns ['First Name', 'Last Name', 'E-mail']
foreach ($records as $record) {
    // $records contains the following data
    // array(
    //     'First Name' => 'john',
    //     'Last Name' => 'doe',
    //     'E-mail' => 'john.doe@example.com',
    // );
    //
}

Selecting a specific record

If you are only interested in one particular record from the ResultSet you can use the ResultSet::fetchOne method to return a single record.

<?php

public ResultSet::fetchOne(int $offset = 0): array

The $offset argument represents the record offset in the result set starting at 0. If no argument is given the method will return the first record from the result set. If no record is found an empty array is returned.

<?php

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

$reader = Reader::createFromPath('/path/to/my/file.csv');
$reader->setHeaderOffset(0);

$stmt = (new Statement())
    ->offset(10)
    ->limit(12)
;
$data = $stmt->proce($reader)->fetchOne(3);
// access the 4th record from the recordset (indexing starts at 0)
// will return something like this :
//
//   ['john', 'doe', 'john.doe@example.com']
//

The $offset argument is not affected by ResultSet::preserveRecordOffset status.

Selecting a specific column

<?php

public ResultSet::fetchColumn(string|int $columnIndex = 0): Generator

ResultSet::fetchColumn returns a Generator of all values in a given column from the ResultSet object.

the $columnIndex parameter can be:

<?php

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

$reader = Reader::createFromPath('/path/to/my/file.csv');
$records = (new Statement())->process($reader);
foreach ($records->fetchColumn(2) as $value) {
    //$value is a string representing the value
    //of a given record for the selected column
    //$value may be equal to 'john.doe@example.com'
}

$reader = Reader::createFromPath('/path/to/my/file.csv');
$reader->setHeaderOffset(0);

$records = (new Statement())->process($reader);
foreach ($records->fetchColumn('E-mail') as $value) {
    //$value is a string representing the value
    //of a given record for the selected column
    //$value may be equal to 'john.doe@example.com'
}

If for a given record the column value is null, the record will be skipped.

<?php

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

$reader = Reader::createFromPath('/path/to/my/file.csv');
$records = (new Statement())->process($reader);
count($records); //returns 10;
count(iterator_to_array($records->fetchColumn(2), false)); //returns 5
//5 records were skipped because the column value is null

The method is affected by ResultSet::preserveRecordOffset

<?php

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

$reader = Reader::createFromPath('/path/to/my/file.csv');

 //we will start iterating from the 6th record
$stmt = (new Statement())->offset(5);
$records = $stmt->process($reader);
$records->preserveRecordOffset(true);
foreach ($records->fetchColumn(0) as $offset => $value) {
    //$value is a string representing the value
    //of a given record for the column 0
    //the first iteration will give $offset equal to 5
    //if the record contains the selected column
}

If the ResultSet contains column names and the $columnIndex is not found a RuntimeException is thrown.

<?php

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

$reader = Reader::createFromPath('/path/to/my/file.csv');
$reader->setHeaderOffset(0);

$records = (new Statement())->process($reader);
foreach ($records->fetchColumn('foobar') as $record) {
    //throw an InvalidArgumentException if
    //no `foobar` column name is found
    //in $records->getColumnNames() result
}

Selecting key-value pairs

ResultSet::fetchPairs method returns a Generator of key-value pairs.

<?php

public ResultSet::fetchPairs(string|int $offsetIndex = 0, string|int $valueIndex = 1): Generator

Both arguments, $offsetIndex and $valueIndex can be:

These arguments behave exactly like the $columnIndex from ResultSet::fetchColumn.

<?php

use League\Csv\Reader;

$str = <<EOF
john,doe
jane,doe
foo,bar
sacha
EOF;

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

$reader = Reader::createFromString($str);
$records = (new Statement())->process($reader);

foreach ($records->fetchPairs() as $firstname => $lastname) {
    // - first iteration
    // echo $firstname; -> 'john'
    // echo $lastname;  -> 'doe'
    // - second iteration
    // echo $firstname; -> 'jane'
    // echo $lastname;  -> 'doe'
    // - third iteration
    // echo $firstname; -> 'foo'
    // echo $lastname; -> 'bar'
    // - fourth iteration
    // echo $firstname; -> 'sacha'
    // echo $lastname; -> 'null'
}

Notes

If the ResultSet contains column names and the submitted arguments are not found a RuntimeException is thrown.