The League of Extraordinary Packages

Our Packages:

Presented by The League of Extraordinary Packages

Getting Started

Connections Settings

Inserting Records

Selecting Records

Interoperability

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, JsonSerializable
{
    public function fetchColumn(string|int $columnIndex = 0): Generator
    public function fetchOne(int $nth_record = 0): array
    public function fetchPairs(string|int $offsetIndex = 0, string|int $valueIndex = 1): Generator
    public function getHeader(): array
    public function getRecords(): 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 Statement::process execution.

Informations

Accessing the result set column names

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

ResultSet::getHeader returns the header associated with the current object.

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->getHeader(); // 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->getHeader(); // returns ['First Name', 'Last Name', 'E-mail'];

Example: header information given by the Statement object

<?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, ['Prénom', 'Nom', 'E-mail']);
$records->getHeader(); // returns ['Prénom', 'Nom', '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

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.

Records

Description

<?php

public ResultSet::getRecords(void): Iterator

To iterate over each found records you can:

<?php

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

$reader = Reader::createFromPath('/path/to/my/file.csv');
$records = (new Statement())->process($reader);

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

foreach ($records 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->getRecords() as $offset => $record) {
    //during the first iteration $offset will be equal to 5
}

Usage with the header

If the ResultSet::getHeader 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->getHeader(); //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 $nth_record = 0): array

The $nth_record argument represents the nth record contained 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 $nth_record argument is not affected by ResultSet::preserveRecordOffset status.

Selecting a single 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 RuntimeException if
    //no `foobar` column name is found
    //in $records->getHeader() 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.

Conversions

The ResultSet class implements the JsonSerializable interface. As such you can use the json_encode function directly on the instantiated object.

The method is affected by ResultSet::preserveRecordOffset

The returned JSON string data depends on the ResultSet properties:

<?php

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

$records = [
    ['firstname', 'lastname', 'e-mail', 'phone'],
    ['john', 'doe', 'john.doe@example.com', '0123456789'],
    ['jane', 'doe', 'jane.doe@example.com', '0123456789'],
];

$tmp = new SplTempFileObject();
foreach ($records as $record) {
    $tmp->fputcsv($record);
}

$reader = Reader::createFromFileObject($tmp)->setHeaderOffset(0);
$stmt = (new Statement())->offset(1)->limit(1);
$result = $stmt->process($reader);

echo '<pre>', PHP_EOL;
echo json_encode($result, JSON_PRETTY_PRINT), PHP_EOL;
//display
//[
//    {
//        "firstname": "jane",
//        "lastname": "doe",
//        "e-mail": "jane.doe@example.com",
//        "phone": "0123456789"
//    }
//]

$result->preserveRecordOffset(true);
echo json_encode($result, JSON_PRETTY_PRINT), PHP_EOL;
//display
//{
//    "2": {  //here '2' refers to the record offset in the source CSV document
//        "firstname": "jane",
//        "lastname": "doe",
//        "e-mail": "jane.doe@example.com",
//        "phone": "0123456789"
//    }
//}

To convert your ResultSet to JSON you must be sure its content is UTF-8 encoded, using, for instance, the library CharsetConverter stream filter.

If you wish to convert your ResultSet in XML or HTML please refer to the converters bundled with this library.

Using the JsonSerializable interface is not recommended for large ResultSet as iterator_to_array is used internally.