diff --git a/README.md b/README.md index 7e3db8d..2cb674b 100644 --- a/README.md +++ b/README.md @@ -1,83 +1,108 @@ Carbon CSV ========== -Carbon CSV is a PHP library, that helps you easily parse CSV files. -Parse any CSV file to an easy to use associative array. +Carbon CSV is a PHP library aimed at simplifying CSV parsing. -## Features - -There are a number of helpful features that include: - -* reduced memory usage and size, thanks to the [`SplFileObject`](http://php.net/manual/en/class.splfileobject.php) PHP class; -* skip row until (by index); -* skip specific columns (by index); -* column removal from parsed output (by index - single or multiple columns). If you wish to remove columns you don't need to work with; -* set custom column names, which will help you when using the parsed output. +It provides simple interface to ease mapping columns via a header row, or custom column names. ## Installation -It is recommended to install the library through [Composer](https://getcomposer.org/). - ```bash composer require htmlburger/carbon-csv ``` ## Usage -To parse a simple CSV file, use the following code: +Suppose that you have the following CSV: -```php -use \Carbon_CSV\CsvFile as CsvFile; -use \Carbon_CSV\Exception; +| First Name | Last Name | Company Name | Address | +|------------|-----------|---------------------------------|-------------------------------------| +| Homer | Simpson | Springfield Nuclear Power Plant | 742 Evergreen Terrace, Springfield | +| Ned | Flanders | The Leftorium | 744 Evergreen Terrace, Springfield | -$csv = new CsvFile('path-to-file/filename.csv'); -foreach ($csv as $row) { - /* do something with $row*/ +Here is how you could iterate through the rows: + +```php +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()); } ``` -You can iterate the `$csv` object directly, or get all the rows using the `to_array` method. +Would produce the following output: -**Important:** the above approach is preferred, as it's less taxing - memory wise (it only works with one row at a time, and doesn't hold all of them, like `to_array` does). +``` +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 +) +``` -Here's an example with the `to_array` method. +Alternatively, you could also provide your own column names: ```php -use \Carbon_CSV\CsvFile as CsvFile; -use \Carbon_CSV\Exception; - -$csv = new CsvFile('path-to-file/filename.csv'); -$rows = $csv->to_array(); +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()); +} ``` -This will parse the file and assign the result to the `$rows` variable. - -Output: +Would produce the following output: ``` 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 - ) + [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, it's advised to set the `auto_detect_line_endings` PHP variable to `1`. +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 ); @@ -99,11 +124,9 @@ $rows = $csv->to_array(); ### Methods -``` -Please note, that skipping methods work with zero based indexes. -``` +Methods for skipping rows or columns work with zero based indexes. -#### skip_to_row +#### `skip_to_row(int $row_index)` To skip to a specific row, simply pass the index of the row. @@ -156,7 +179,7 @@ Array ``` -#### skip_to_column +#### `skip_to_column(int $col_index)` To skip to a specific column, simply pass the index of the column. @@ -210,12 +233,10 @@ Array ``` -#### skip_columns +#### `skip_columns(array $col_indexes)` To skip multiple columns, pass the indexes of those columns as an array. -**Important:** when skipping, indexes are reset to start from 0, so you don't need to remember which indexes are available. - ```php use \Carbon_CSV\CsvFile as CsvFile; use \Carbon_CSV\Exception; @@ -264,11 +285,11 @@ Array ``` -#### use_first_row_as_header +#### `use_first_row_as_header()` To use the first row from the CSV, simply call this method. -**Important:** if the `skip_to_row` is called prior to calling this method, the parser will use the row it's set to skip to, as the header row. +**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. ```php use \Carbon_CSV\CsvFile as CsvFile; @@ -322,11 +343,11 @@ Array Since we're telling the parser to use the first row as a header row, it is assigned and skipped. -#### set_column_names +#### `set_column_names(array $columns_mapping)` If you wish to use your own indexes for the columns, pass them using an array. -**Important:** you can use this method with `use_first_row_as_header`, so you can set the names of the columns based on the header row. +**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): @@ -458,9 +479,9 @@ Array ) ``` -#### count +#### `count()` -Get the total number of rows in the CSV file (please note, that this skips the empty rows); +Get the total number of rows in the CSV file (this skips the empty rows): ```php use \Carbon_CSV\CsvFile as CsvFile;