Logo
CSV

This is the documentation for the unsupported version 7.0. Please consider upgrading your code to the latest stable version

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.

Accessing and Setting CSV properties

The delimiter character

$csv->setDelimiter(';');
$delimiter = $csv->getDelimiter(); //returns ";"

The default delimiter character is ,.

The enclosure character

$csv->setEnclosure('|');
$enclosure = $csv->getEnclosure(); //returns "|"

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 a 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 that will format your content.

$csv->setEscape('\\');
$escape = $csv->getEscape(); //returns "\"

The default escape character is \.

The SplFileObject flags

League\Csv objects rely internally on the SplFileObject class. In order to fine tune the class behavior you can adjust the SplFileObject flags used.

$csv->setFlags(SplFileObject::READ_AHEAD|SplFileObject::SKIP_EMPTY);
$flags = $csv->getFlags(); //returns an integer

Since version 7.0.1, the setFlags method has been fixed to prevent a bug in SplFileObject.

Since version 7.2.0, the flags on instantiation are have been changed to correct a bug when parsing row cells with multiple lines

  • On instantiation the flags set are :
    • SplFileObject::READ_CSV
    • SplFileObject::READ_AHEAD
    • SplFileObject::SKIP_EMPTY
  • On update you can add or remove any SplFileObject flags except for the SplFileObject::READ_CSV flag.

Detecting CSV delimiter

fetchDelimitersOccurrence(array $delimiters, $nbRows = 1)

This method is introduced in version 7.2.0

The method takes two arguments:

  • an array containing the delimiters to check;
  • an integer which represents the number of rows to scan (defaults to 1);
$reader = Reader::createFromPath('/path/to/your/csv/file.csv', 'r');

$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

This method only test the delimiters you gave it.

detectDelimiterList($nbRows = 1, array $delimiters = [])

This method is deprecated since version 7.2.0 and will be remove in the next major release

If multiple delimiters share the same occurrences count only the last found delimiter will be returned in the response array.

This method will only give you a hint, a better approach is to ask the CSV provider for the document controls properties.

If you are no sure about the delimiter you can ask the library to detect it for you using the detectDelimiterList method.

The method takes two arguments:

  • the number of rows to scan (defaults to 1);
  • the possible delimiters to check (you don’t need to specify the following delimiters as they are already checked by the method: ",", ";", "\t");
$reader = Reader::createFromPath('/path/to/your/csv/file.csv', 'r');

$reader->setEnclosure('"');
$reader->setEscape('\\');
$reader->setFlags(SplFileObject::READ_AHEAD|SplFileObject::SKIP_EMPTY);

$delimiters_list = $reader->detectDelimiterList(10, [' ', '|']);
// $delimiters_list can be the following
// [
//     20 => '|',
//     3 => ';'
// ]
// This is a inconsistent CSV with:
// - the delimiter "|" appearing 20 times in the 10 first rows
// - the delimiter ";" appearing 3 times in the 10 first rows

The more rows and delimiters you add, the more time and memory consuming the operation will be. The method returns an array of the delimiters found.

  • If a single delimiter is found the array will contain only one delimiter;
  • If multiple delimiters are found the array will contain the found delimiters sorted descendingly according to their occurrences in the defined rows set;
  • If no delimiter is found or your CSV is composed of a single column, the array will be empty;

BC Break: Starting with version 7.0, the index of each found delimiter represents the occurrences of the found delimiter in the selected rows.

Whenever a user creates a new CSV object using the newWriter or the newReader methods, the current CSV object properties are copied to the new instance.

Writing mode only properties

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

The newline sequence

The newline sequence is appended to each CSV newly inserted line. To improve interoperability with programs interacting with CSV and because the php fputcsv implementation has a hardcoded "\n", we need to be able to replace this last LF code with one supplied by the developer.

$csv->setNewline("\r\n");
$newline = $csv->getNewline(); //returns "\r\n"

The default newline sequence is \n;

Since version 7.0, the $newline getter and setter methods are also available on the Reader class.

The BOM character

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

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

$bom = $csv->getInputBOM();

You can of course set the outputting BOM you want your CSV to be associated with.

$csv->setOutputBOM(Reader::BOM_UTF8);
$bom = $csv->getOutputBOM(); //returns "\xEF\xBB\xBF"

The default output BOM character is set to null.

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

Conversion only properties

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

The encoding charset

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 using the library stream filtering mechanism.

When this is not applicable you can fallback by providing the CSV original encoding charset to the CSV class using the following method:

$reader->setEncodingFrom('iso-8859-15');
echo $reader->getEncodingFrom(); //returns iso-8859-15;

By default getEncodingFrom returns UTF-8 if setEncodingFrom 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.
$reader = Reader::createFromFileObject(new SplFileObject('/path/to/bengali.csv'));
//we are using the setEncodingFrom method to transcode the CSV into UTF-8
$reader->setEncodingFrom('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