The League of Extraordinary Packages

Our Packages:

Presented by The League of Extraordinary Packages

Getting Started

The API

Upgrading Guide

CSV properties

Once your object is instantiated you can optionally set several CSV properties. The following methods works on both the Reader and the Writer class.

Since version 8.1.1 The underlying CSV controls from the submitted CSV are inherited by the return AbstractCsv object.

<?php

$file = new SplTempFileObject();
$file->setFlags(SplFileObject::READ_CSV);
$file->setCsvControl('|');

$csv = Reader::createFromFileObject($file);

echo $csv->getDelimiter(); //display '|'

Of note, The escape character is only inherited starting with PHP 5.6.25 in the PHP5 line and 7.0.10 in the PHP7 version.

Accessing and Setting CSV properties

The CSV delimiter character.

Description

<?php

public AbstractCsv::setDelimiter(string $delimiter): AbstractCsv
public AbstractCsv::getDelimiter(void): string

Example

<?php

use League\Csv\Reader;

$csv = Reader::createFromPath('/path/to/file.csv');
$csv->setDelimiter(';');
$delimiter = $csv->getDelimiter(); //returns ";"

Notes

The default delimiter character is ,.

The enclosure character

Description

<?php

public AbstractCsv::setEnclosure(string $delimiter): AbstractCsv
public AbstractCsv::getEnclosure(void): string

Example

<?php

use League\Csv\Writer;

$csv = Writer::createFromPath('/path/to/file.csv');
$csv->setEnclosure('|');
$enclosure = $csv->getEnclosure(); //returns "|"

Notes

The default enclosure character is ".

The escape character

Warning: The library depends on PHP SplFileObject class. Since this class exhibits a reported bug, Data using the escape character are correctly escaped but the escape character is not removed from the CSV content.
A possible workaround to this issue while waiting for a PHP bug fix is to register a callable to your extracting method when possible.

Description

<?php

public AbstractCsv::setEscape(string $delimiter): AbstractCsv
public AbstractCsv::getEscape(void): string

Example

<?php

use League\Csv\Reader;

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

Notes

The default escape character is \.

fetchDelimitersOccurrence

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

<?php

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

The method takes two arguments:

<?php

use League\Csv\Reader;

$reader = Reader::createFromPath('/path/to/your/csv/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.

Writing mode only properties

The following properties only affect the CSV object when you are writing and/or saving data to it.

The Reader class still have access to them.

The newline sequence

To improve interoperability with programs interacting with CSV, the newline sequence is appended to each CSV newly inserted line.

Description

<?php

public AbstractCsv::setNewline(string $sequence): AbstractCsv
public AbstractCsv::getNewline(void): string

Example

<?php

use League\Csv\Writer;

$csv = Writer::createFromPath('/path/to/file.csv');
$csv->setNewline("\r\n");
$newline = $csv->getNewline(); //returns "\r\n"

Notes

The default newline sequence is \n;

The BOM sequence

To improve interoperability with programs interacting with CSV, you can manage the presence of the BOM sequence in your CSV content.

Detect the currently used BOM sequence

BC Break: getInputBOM always return a string

<?php

public AbstractCsv::getInputBOM(void): string

Detect the current BOM character is done using the getInputBOM method. This method returns the currently used BOM character or an empty string if none is found or recognized.

<?php

use League\Csv\Writer;

$csv = Writer::createFromPath('/path/to/file.csv');
$bom = $csv->getInputBOM();

Set the outputting BOM sequence

<?php

public AbstractCsv::setOutputBOM(string $sequence): AbstractCsv
public AbstractCsv::getOutputBOM(void): string

BC Break: getOutputBOM always return a string

<?php

use League\Csv\Reader;

$csv = Reader::createFromPath('/path/to/file.csv');
$csv->setOutputBOM(Reader::BOM_UTF8);
$bom = $csv->getOutputBOM(); //returns "\xEF\xBB\xBF"

Notes

Please refer to the BOM character dedicated documentation page for more informations on how the library helps you manage this feature.

Conversion only properties

The following properties and method only works when converting your CSV document into other available formats.

To convert your CSV document into another format it must be encoded in UTF-8.

When this is not the case, you should transcode it first using the library stream filtering mechanism. When this is not applicable you should provide the CSV original encoding charset to the CSV object using the following methods.

methods

These methods are introduced in version 8.1.0

<?php

public AbstractCsv::setInputEncoding(string $sequence): AbstractCsv
public AbstractCsv::getInputEncoding(void): string

The following methods are deprecated since version 8.1.0 and will be remove in the next major release

<?php

public AbstractCsv::setEncodingFrom(string $sequence): AbstractCsv
public AbstractCsv::getEncodingFrom(void): string

Example

<?php

use League\Csv\Reader;

$csv = Reader::createFromPath('/path/to/file.csv');
$csv->setInputEncoding('iso-8859-15');
echo $csv->getInputEncoding(); //returns iso-8859-15;

Notes

By default getInputEncoding returns UTF-8 if setInputEncoding was not used.

The encoding properties have no effect when reading or writing to a CSV document. You should instead use the Stream Filter API or the Writing Formatter API.
<?php

use League\Csv\Reader;

$reader = Reader::createFromFileObject(new SplFileObject('/path/to/bengali.csv'));
//we are using the setInputEncoding method to transcode the CSV into UTF-8
$reader->setInputEncoding('iso-8859-15');
echo json_encode($reader);
//the CSV is transcoded from iso-8859-15 to UTF-8
//before being converted to JSON format;
echo $reader; //outputting the data is not affected by the conversion