htmlburger / carbon-csv
Simple CSV file parser
Installs: 40 009
Dependents: 0
Suggesters: 0
Security: 0
Stars: 6
Watchers: 8
Forks: 4
Open Issues: 5
Requires
- php: ^5.4.0 || ^7.0
Requires (Dev)
- illuminate/support: ^5.4
- phpunit/phpunit: ^6.1
- symfony/var-dumper: ^3.3
This package is auto-updated.
Last update: 2024-12-08 15:23:19 UTC
README
Carbon CSV is a PHP library aimed at simplifying CSV parsing.
It provides simple interface to ease mapping columns via a header row, or custom column names.
Installation
composer require htmlburger/carbon-csv
Usage
Suppose that you have the following CSV:
Here is how you could iterate through the rows:
use \Carbon_CSV\CsvFile; use \Carbon_CSV\Exception as CsvException; try { $csv = new CsvFile('path-to-file/filename.csv'); $csv->use_first_row_as_header(); foreach ($csv as $row) { print_r($row); } } catch (CsvException $e) { exit("Couldn't parse CSV file: " . $e->getMessage()); }
Would produce the following output:
Array
(
[First Name] => Homer
[Last Name] => Simpson
[Company Name] => Springfield Nuclear Power Plant
[Address] => 742 Evergreen Terrace, Springfield
)
Array
(
[First Name] => Ned
[Last Name] => Flanders
[Company Name] => The Leftorium
[Address] => 744 Evergreen Terrace, Springfield
)
Alternatively, you could also provide your own column names:
use \Carbon_CSV\CsvFile; use \Carbon_CSV\Exception as CsvException; try { $csv = new CsvFile('path-to-file/filename.csv'); $csv->use_first_row_as_header(); $csv->set_column_names([ 'First Name' => 'fname', 'Last Name' => 'lname', 'Company Name' => 'company', 'Address' => 'address', ]); foreach ($csv as $row) { print_r($row); } } catch (CsvException $e) { exit("Couldn't parse CSV file: " . $e->getMessage()); }
Would produce the following output:
Array
(
[fname] => Homer
[lname] => Simpson
[company] => Springfield Nuclear Power Plant
[address] => 742 Evergreen Terrace, Springfield
)
Array
(
[fname] => Ned
[lname] => Flanders
[company] => The Leftorium
[address] => 744 Evergreen Terrace, Springfield
)
MacOS encoding
When working with files created on a Mac device, you should set the auto_detect_line_endings PHP variable to 1.
ini_set( 'auto_detect_line_endings', 1 );
Settings
To change the delimiter, enclosure and escape characters for the CSV file, simply pass them as arguments after the file path.
Example:
use \Carbon_CSV\CsvFile as CsvFile; use \Carbon_CSV\Exception; $csv = new CsvFile('path-to-file/filename.csv', ';', '|', '/'); $rows = $csv->to_array();
Methods
Methods for skipping rows or columns work with zero based indexes.
skip_to_row(int $row_index)
To skip to a specific row, simply pass the index of the row.
This will tell the parser to start reading from that row until the end of the file.
use \Carbon_CSV\CsvFile as CsvFile; use \Carbon_CSV\Exception; $csv = new CsvFile('path-to-file/filename.csv'); $csv->skip_to_row(1); $rows = $csv->to_array();
Contents before skipping to a specific row:
Array
(
[0] => Array
(
[0] => John
[1] => Doe
[2] => Simple Company Name
[3] => Street Name, 1234, City Name, Country Name
)
[1] => Array
(
[0] => Jane
[1] => Doe
[2] => Nice Company Name
[3] => Street Name, 5678, City Name, Country Name
)
)
Contents after skipping to a specific row:
Array
(
[0] => Array
(
[0] => Jane
[1] => Doe
[2] => Nice Company Name
[3] => Street Name, 5678, City Name, Country Name
)
)
skip_to_column(int $col_index)
To skip to a specific column, simply pass the index of the column.
use \Carbon_CSV\CsvFile as CsvFile; use \Carbon_CSV\Exception; $csv = new CsvFile('path-to-file/filename.csv'); $csv->skip_to_column(2); $rows = $csv->to_array();
Contents before skipping to a specific column:
Array
(
[0] => Array
(
[0] => John
[1] => Doe
[2] => Simple Company Name
[3] => Street Name, 1234, City Name, Country Name
)
[1] => Array
(
[0] => Jane
[1] => Doe
[2] => Nice Company Name
[3] => Street Name, 5678, City Name, Country Name
)
)
Contents after skipping to a specific column:
Array
(
[0] => Array
(
[0] => Simple Company Name
[1] => Street Name, 1234, City Name, Country Name
)
[1] => Array
(
[0] => Nice Company Name
[1] => Street Name, 5678, City Name, Country Name
)
)
skip_columns(array $col_indexes)
To skip multiple columns, pass the indexes of those columns as an array.
use \Carbon_CSV\CsvFile as CsvFile; use \Carbon_CSV\Exception; $csv = new CsvFile('path-to-file/filename.csv'); $csv->skip_columns(array(0, 2, 3)); $rows = $csv->to_array();
Contents before skipping columns:
Array
(
[0] => Array
(
[0] => John
[1] => Doe
[2] => Simple Company Name
[3] => Street Name, 1234, City Name, Country Name
)
[1] => Array
(
[0] => Jane
[1] => Doe
[2] => Nice Company Name
[3] => Street Name, 5678, City Name, Country Name
)
)
Contents after skipping columns:
Array
(
[0] => Array
(
[0] => Doe
)
[1] => Array
(
[0] => Doe
)
)
use_first_row_as_header()
To use the first row from the CSV, simply call this method.
Note: if skip_to_row is called prior to calling use_first_row_as_header, the parser will use the new first row as a header.
use \Carbon_CSV\CsvFile as CsvFile; use \Carbon_CSV\Exception; $csv = new CsvFile('path-to-file/filename.csv'); $csv->use_first_row_as_header(); $rows = $csv->to_array();
Contents before assigning a header row:
Array
(
[0] => Array
(
[0] => First Name
[1] => Last Name
)
[1] => Array
(
[0] => John
[1] => Doe
)
[2] => Array
(
[0] => Jane
[1] => Dove
)
)
Contents after assigning a header row:
Array
(
[0] => Array
(
[First Name] => John
[Last Name] => Doe
)
[1] => Array
(
[First Name] => Jane
[Last Name] => Dove
)
)
Since we're telling the parser to use the first row as a header row, it is assigned and skipped.
set_column_names(array $columns_mapping)
If you wish to use your own indexes for the columns, pass them using an array.
Note: you can use set_column_names in conjunction with use_first_row_as_header, so you can set the names of the columns based on the header row.
Example without use_first_row_as_header (using a file without a head row):
use \Carbon_CSV\CsvFile as CsvFile; use \Carbon_CSV\Exception; $csv = new CsvFile('path-to-file/filename-no-head-rows.csv'); $csv->set_column_names([ 0 => 'first_name', 1 => 'last_name', 2 => 'company_name', 3 => 'address', ]); $rows = $csv->to_array();
Contents before setting custom column names:
Array
(
[0] => Array
(
[0] => John
[1] => Doe
[2] => Simple Company Name
[3] => Street Name, 1234, City Name, Country Name
)
[1] => Array
(
[0] => Jane
[1] => Doe
[2] => Nice Company Name
[3] => Street Name, 5678, City Name, Country Name
)
)
Contents after setting custom column names:
Array
(
[0] => Array
(
[first_name] => John
[last_name] => Doe
[company_name] => Simple Company Name
[address] => Street Name, 1234, City Name, Country Name
)
[1] => Array
(
[first_name] => Jane
[last_name] => Doe
[company_name] => Nice Company Name
[address] => Street Name, 5678, City Name, Country Name
)
)
Example with use_first_row_as_header (using a file with a head row):
use \Carbon_CSV\CsvFile as CsvFile; use \Carbon_CSV\Exception; $csv = new CsvFile('path-to-file/filename-no-head-rows.csv'); $csv->use_first_row_as_header(); $csv->set_column_names([ 'First Name' => 'first_name', 'Last Name' => 'last_name', 'Company Name' => 'company_name', 'Address' => 'address', ]); $rows = $csv->to_array();
Contents before setting custom column names:
Array
(
[0] => Array
(
[0] => First Name
[1] => Last Name
[2] => Company Name
[3] => Address
)
[1] => Array
(
[0] => John
[1] => Doe
[2] => Simple Company Name
[3] => Street Name, 1234, City Name, Country Name
)
[2] => Array
(
[0] => Jane
[1] => Doe
[2] => Nice Company Name
[3] => Street Name, 5678, City Name, Country Name
)
)
Contents after setting custom column names:
Array
(
[0] => Array
(
[first_name] => John
[last_name] => Doe
[company_name] => Simple Company Name
[address] => Street Name, 1234, City Name, Country Name
)
[1] => Array
(
[first_name] => Jane
[last_name] => Doe
[company_name] => Nice Company Name
[address] => Street Name, 5678, City Name, Country Name
)
)
set_encoding($encoding)
Set the encoding of the CSV file. This is needed, so it can be properly converted to utf-8
Example:
use \Carbon_CSV\CsvFile as CsvFile; use \Carbon_CSV\Exception; $csv = new CsvFile('path-to-file/filename.csv'); $csv->set_encoding('windows-1251'); $total_number_of_rows = $csv->count();
count()
Get the total number of rows in the CSV file (this skips the empty rows):
use \Carbon_CSV\CsvFile as CsvFile; use \Carbon_CSV\Exception; $csv = new CsvFile('path-to-file/filename.csv'); $total_number_of_rows = $csv->count();
$total_number_of_rows = $csv->count() is equivalent to count($csv->to_array()).