Formatting does not affect the CSV document content.
### Controlling the presence of empty records
The record offset is always independent of the presence of empty records.
```php
use League\Csv\Reader;
$source = <<isEmptyRecordsIncluded(); //returns false
iterator_to_array($reader, true);
// [
// 0 => ['parent name', 'child name', 'title'],
// 3 => ['parentA', 'childA', 'titleA'],
// ];
$reader->includeEmptyRecords();
$reader->isEmptyRecordsIncluded(); //returns true
iterator_to_array($reader, true);
// [
// 0 => ['parent name', 'child name', 'title'],
// 1 => [],
// 2 => [],
// 3 => ['parentA', 'childA', 'titleA'],
// ];
$reader->setHeaderOffset(0);
iterator_to_array($reader, true);
// [
// 1 => ['parent name' => null, 'child name' => null, 'title' => null],
// 2 => ['parent name' => null, 'child name' => null, 'title' => null],
// 3 => ['parent name' => 'parentA', 'child name' => 'childA', 'title' => 'titleA'],
// ];
$reader->skipEmptyRecords();
$reader->isEmptyRecordsIncluded(); //returns false
$res = iterator_to_array($reader, true);
// [
// 3 => ['parent name' => 'parentA', 'child name' => 'childA', 'title' => 'titleA'],
// ];
```
## Document header
While accessing the CSV header is done via the `getHeader` method which is part of the `TabularDataReader` API,
Because CSV documents come in difference shape and form the class exposes a way to select and get the document Header
record via the `setHeaderOffset` and `getHeaderOffset` method.
### Description
```php
public Reader::setHeaderOffset(?int $offset): self
public Reader::getHeaderOffset(void): ?int
public Reader::getHeader(void): array
```
### Example
```php
use League\Csv\Reader;
$csv = Reader::createFromPath('/path/to/file.csv', 'r');
$csv->setHeaderOffset(0);
$header_offset = $csv->getHeaderOffset(); //returns 0
$header = $csv->getHeader(); //returns ['First Name', 'Last Name', 'E-mail']
```
If no header offset is set:
- `Reader::getHeader` method will return an empty array.
- `Reader::getHeaderOffset` will return `null`.
By default no header offset is set.
Because the header is lazy loaded, if you provide a positive offset
for an invalid record a SyntaxError exception will be triggered when trying
to access the invalid record.
```php
use League\Csv\Reader;
$csv = Reader::createFromPath('/path/to/file.csv', 'r');
$csv->setHeaderOffset(1000); //valid offset but the CSV does not contain 1000 records
$header_offset = $csv->getHeaderOffset(); //returns 1000
$header = $csv->getHeader(); //throws a SyntaxError exception
```
Because the CSV document is treated as tabular data the header can not contain duplicate entries.
If the header contains duplicates an exception will be thrown on usage.
```php
use League\Csv\Reader;
$csv = Reader::createFromPath('/path/to/file.csv', 'r');
$csv->nth(0); //returns ['field1', 'field2', 'field1', 'field4']
$csv->setHeaderOffset(0); //valid offset but the record contain duplicates
$header_offset = $csv->getHeaderOffset(); //returns 0
$records = $csv->getRecords(); //throws a SyntaxError exception
```
Starting with 9.7.0 the SyntaxError exception thrown
will return the list of duplicate column names.
```php
use League\Csv\Reader;
use League\Csv\SyntaxError;
$csv = Reader::createFromPath('/path/to/file.csv', 'r');
$csv->nth(0); //returns ['field1', 'field2', 'field1', 'field4']
$csv->setHeaderOffset(0); //valid offset but the record contain duplicates
$header_offset = $csv->getHeaderOffset(); //returns 0
try {
$records = $csv->getRecords(); //throws a SyntaxError exception
} catch (SyntaxError $exception) {
$duplicates = $exception->duplicateColumnNames(); //returns ['field1']
}
```
## Document records
To access the CSV records you will need to use the `getRecords` or the `getRecordsAsObjects` methods. The methods
returns an `Iterator` containing all CSV document records as `array` or as objects. It will extract the
records using the [CSV controls characters](/9.0/connections/controls/).
getRecords and getRecordsAsObjects are part of the TabularDataReader API.
```php
use League\Csv\Reader;
$reader = Reader::createFromPath('/path/to/my/file.csv', 'r');
$records = $reader->getRecords();
foreach ($records as $offset => $record) {
//$offset : represents the record offset
//var_export($record) returns something like
// array(
// 'john',
// 'doe',
// 'john.doe@example.com'
// );
}
```
### Records selection with Reader::setHeaderOffset
Just like the `getHeader` method, the method output depends on the header record selected using `setHeaderOffset`.
```php
use League\Csv\Reader;
$reader = Reader::createFromPath('/path/to/my/file.csv', 'r');
$reader->setHeaderOffset(0);
$records = $reader->getRecords();
foreach ($records as $offset => $record) {
//$offset : represents the record offset
//var_export($record) returns something like
// array(
// 'First Name' => 'jane',
// 'Last Name' => 'doe',
// 'E-mail' => 'jane.doe@example.com'
// );
}
```
The optional $header argument from the Reader::getRecords
takes precedence over the header offset property but its corresponding record will still be removed
from the returned Iterator.
```php
use League\Csv\Reader;
$reader = Reader::createFromPath('/path/to/my/file.csv', 'r');
$reader->setHeaderOffset(0);
$records = $reader->getRecords(['firstname', 'lastname', 'email']);
foreach ($records as $offset => $record) {
//$offset : represents the record offset
//var_export($record) returns something like
// array(
// 'firstname' => 'jane',
// 'lastname' => 'doe',
// 'email' => 'jane.doe@example.com'
// );
}
//the first record will still be skipped!!
```
## Selecting records
Please header over the [TabularDataReader documentation page](/9.0/reader/tabular-data-reader)
for more information on the class features. If you require a more advance record selection, you
should use a [Statement or a FragmentFinder](/9.0/reader/statement/) class to process the `Reader` object. The
found records are returned as a [ResultSet](/9.0/reader/resultset) object.
## Records conversion
### Json serialization
A dedicated JsonConverter class is added in version 9.17.0
to help converting CSV into proper JSON document without consuming
too much memory. It is the recommended way to convert to JSON.
The `Reader` class implements the `JsonSerializable` interface. As such you can use the `json_encode`
function directly on the instantiated object. The interface is implemented using PHP's
`iterator_array` on the `Reader::getRecords` method. As such, the returned `JSON`
string data depends on the presence or absence of a header.
```php
use League\Csv\Reader;
$records = [
['firstname', 'lastname', 'e-mail', 'phone'],
['john', 'doe', 'john.doe@example.com', '0123456789'],
];
$tmp = new SplTempFileObject();
foreach ($records as $record) {
$tmp->fputcsv($record);
}
$reader = Reader::createFromFileObject($tmp);
echo '', PHP_EOL;
echo json_encode($reader, JSON_PRETTY_PRINT), PHP_EOL;
//display
//[
// [
// "firstname",
// "lastname",
// "e-mail",
// "phone"
// ],
// [
// "john",
// "doe",
// "john.doe@example.com",
// "0123456789"
// ]
//]
$reader->setHeaderOffset(0);
echo '', PHP_EOL;
echo json_encode($reader, JSON_PRETTY_PRINT), PHP_EOL;
//display
//[
// {
// "firstname": "john",
// "lastname": "doe",
// "e-mail": "john.doe@example.com",
// "phone": "0123456789"
// }
//]
```
The record offset is not preserved on conversion
To convert your CSV to JSON you must be sure its content
is UTF-8 encoded, using, for instance, the library
CharsetConverter stream filter.
### Other conversions
If you wish to convert your CSV document in `XML` or `HTML` please refer to the [converters](/9.0/converter/) bundled
with this library.