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

Reader Connection

<?php

public Reader::fetchDelimitersOccurrence(array $delimiters, int $nbRows = 1): array
public Reader::getHeaderOffset(void): int|null
public Reader::getHeader(void): array
public Reader::setHeaderOffset(?int $offset): self
public Reader::getIterator(void): Iterator
public Reader::select(Statement $stmt): RecordSet

The League\Csv\Reader class extends the general connections capabilities to ease selecting and manipulating CSV document records.

CSV example

Many examples in this reference require an CSV file. We will use the following file file.csv containing the following data:

"First Name","Last Name",E-mail
john,doe,john.doe@example.com
jane,doe,jane.doe@example.com

Detecting the delimiter character

This method allow you to find the occurences of some delimiters in a given CSV object.

<?php

public Reader::fetchDelimitersOccurrence(array $delimiters, int $nbRows = 1): array

The method takes two arguments:

<?php

use League\Csv\Reader;

$reader = Reader::createFromPath('/path/to/file.csv');
$reader->setEnclosure('"');
$reader->setEscape('\\');

$delimiters_list = $reader->fetchDelimitersOccurrence([' ', '|'], 10);
// $delimiters_list can be the following
// [
//     '|' => 20,
//     ' ' => 0,
// ]
// This seems to be a consistent CSV with:
// - the delimiter "|" appearing 20 times in the 10 first rows
// - the delimiter " " never appearing

Warning: This method only test the delimiters you gave it.

Header detection

You can set and retrieve the header offset as well as the header record.

Description

<?php

public Reader::setHeaderOffset(?int $offset): self
public Reader::getHeaderOffset(void): int|null
public Reader::getHeader(void): array

Example

<?php

use League\Csv\Reader;

$csv = Reader::createFromPath('/path/to/file.csv');
$csv->setHeaderOffset(0);
$header_offset = $csv->getHeaderOffset(); //returns 0
$header = $csv->getHeader(); //returns ['First Name', 'Last Name', 'E-mail']

Notes

If no header offset is set:

Because the header is lazy loaded, if you provide a positive offset for an invalid record a RuntimeException will be triggered when trying to access the invalid record.

<?php

use League\Csv\Reader;

$csv = Reader::createFromPath('/path/to/file.csv');
$csv->setHeaderOffset(1000); //valid offset but the CSV does not contain 1000 records
$header_offset = $csv->getHeaderOffset(); //returns 1000
$header = $csv->getHeader(); //triggers a Exception

By setting a header offset you implicitly normalize your CSV document to the field length of the specified header. Missing fields will be added with null content whereas extra fields will be truncated while iterating the CSV records.

Iterating over the document records

Because the Reader class implements the IteratorAggregate interface you can iterate over each record using the foreach construct. While iterating the Reader will:

Example without a header

<?php

use League\Csv\Reader;

$reader = Reader::createFromPath('/path/to/my/file.csv');
foreach ($reader as $offset => $record) {
    //$offset : represents the record offset
    //var_export($record) returns something like
    // array(
    //  'john',
    //  'doe',
    //  'john.doe@example.com'
    // );
    //
}

Example with a header

<?php

use League\Csv\Reader;

$reader = Reader::createFromPath('/path/to/my/file.csv');
$reader->setHeaderOffset(0);
foreach ($reader as $offset => $record) {
    //$offset : represents the record offset
    //var_export($record) returns something like
    // array(
    //  'Fist Name' => 'john',
    //  'Last Name' => 'doe',
    //  'E-mail' => john.doe@example.com'
    // );
    //
}

If a record header is selected, it will be skipped from the iteration.

Selecting CSV records

<?php

public Reader::select(Statement $stmt): RecordSet

This method uses a Statement object to process the Reader object. The found records are returned as a RecordSet object.

Example

<?php

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

$reader = Reader::createFromPath('/path/to/my/file.csv');
$stmt = (new Statement())
    ->offset(3)
    ->limit(5)
;
$records = $reader->select($stmt);
//$records is a League\Csv\RecordSet object

Tips: this method is equivalent of Statement::process.