{"id":28825659,"url":"https://github.com/htmlburger/carbon-csv","last_synced_at":"2025-07-15T16:05:34.565Z","repository":{"id":24950898,"uuid":"102733705","full_name":"htmlburger/carbon-csv","owner":"htmlburger","description":"Simple CSV file parser","archived":false,"fork":false,"pushed_at":"2023-08-08T12:27:27.000Z","size":19,"stargazers_count":7,"open_issues_count":5,"forks_count":5,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-06-19T02:04:44.769Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/htmlburger.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-09-07T12:21:31.000Z","updated_at":"2024-12-25T13:15:39.000Z","dependencies_parsed_at":"2022-07-27T05:02:08.903Z","dependency_job_id":null,"html_url":"https://github.com/htmlburger/carbon-csv","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/htmlburger/carbon-csv","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/htmlburger%2Fcarbon-csv","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/htmlburger%2Fcarbon-csv/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/htmlburger%2Fcarbon-csv/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/htmlburger%2Fcarbon-csv/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/htmlburger","download_url":"https://codeload.github.com/htmlburger/carbon-csv/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/htmlburger%2Fcarbon-csv/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265444397,"owners_count":23766429,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-19T02:05:12.763Z","updated_at":"2025-07-15T16:05:34.557Z","avatar_url":"https://github.com/htmlburger.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"Carbon CSV\n==========\n\nCarbon CSV is a PHP library aimed at simplifying CSV parsing.\n\nIt provides simple interface to ease mapping columns via a header row, or custom column names. \n\n## Installation\n\n```bash\ncomposer require htmlburger/carbon-csv\n```\n\n## Usage\n\nSuppose that you have the following CSV:\n\n| First Name | Last Name | Company Name                    | Address                             |\n|------------|-----------|---------------------------------|-------------------------------------|\n| Homer      | Simpson   | Springfield Nuclear Power Plant |  742 Evergreen Terrace, Springfield |\n| Ned        | Flanders  | The Leftorium                   | 744 Evergreen Terrace, Springfield  |\n\nHere is how you could iterate through the rows:\n\n```php\nuse \\Carbon_CSV\\CsvFile;\nuse \\Carbon_CSV\\Exception as CsvException;\n\ntry {\n    $csv = new CsvFile('path-to-file/filename.csv');\n    $csv-\u003euse_first_row_as_header();\n\n    foreach ($csv as $row) {\n        print_r($row);\n    }\n} catch (CsvException $e) {\n    exit(\"Couldn't parse CSV file: \" . $e-\u003egetMessage()); \n}\n```\n\nWould produce the following output: \n\n```\nArray\n(\n    [First Name] =\u003e Homer\n    [Last Name] =\u003e Simpson\n    [Company Name] =\u003e Springfield Nuclear Power Plant\n    [Address] =\u003e 742 Evergreen Terrace, Springfield\n)\nArray\n(\n    [First Name] =\u003e Ned\n    [Last Name] =\u003e Flanders\n    [Company Name] =\u003e The Leftorium\n    [Address] =\u003e 744 Evergreen Terrace, Springfield\n)\n```\n\nAlternatively, you could also provide your own column names:\n\n```php\nuse \\Carbon_CSV\\CsvFile;\nuse \\Carbon_CSV\\Exception as CsvException;\n\ntry {\n    $csv = new CsvFile('path-to-file/filename.csv');\n    $csv-\u003euse_first_row_as_header();\n    $csv-\u003eset_column_names([\n        'First Name'   =\u003e 'fname',\n        'Last Name'    =\u003e 'lname',\n        'Company Name' =\u003e 'company',\n        'Address'      =\u003e 'address',\n    ]);\n\n    foreach ($csv as $row) {\n        print_r($row);\n    }\n} catch (CsvException $e) {\n    exit(\"Couldn't parse CSV file: \" . $e-\u003egetMessage()); \n}\n```\n\nWould produce the following output: \n\n```\nArray\n(\n    [fname] =\u003e Homer\n    [lname] =\u003e Simpson\n    [company] =\u003e Springfield Nuclear Power Plant\n    [address] =\u003e 742 Evergreen Terrace, Springfield\n)\nArray\n(\n    [fname] =\u003e Ned\n    [lname] =\u003e Flanders\n    [company] =\u003e The Leftorium\n    [address] =\u003e 744 Evergreen Terrace, Springfield\n)\n```\n\n**MacOS encoding**\n\nWhen working with files created on a Mac device, you should set the `auto_detect_line_endings` PHP variable to `1`.\n\n```\nini_set( 'auto_detect_line_endings', 1 );\n```\n\n### Settings\n\nTo change the delimiter, enclosure and escape characters for the CSV file, simply pass them as arguments after the file path.\n\nExample:\n\n```php\nuse \\Carbon_CSV\\CsvFile as CsvFile;\nuse \\Carbon_CSV\\Exception;\n\n$csv = new CsvFile('path-to-file/filename.csv', ';', '|', '/');\n$rows = $csv-\u003eto_array();\n```\n\n### Methods\n\nMethods for skipping rows or columns work with zero based indexes.\n\n#### `skip_to_row(int $row_index)`\n\nTo skip to a specific row, simply pass the index of the row.\n\nThis will tell the parser to start reading from that row until the end of the file.\n\n```php\nuse \\Carbon_CSV\\CsvFile as CsvFile;\nuse \\Carbon_CSV\\Exception;\n\n$csv = new CsvFile('path-to-file/filename.csv');\n$csv-\u003eskip_to_row(1);\n$rows = $csv-\u003eto_array();\n```\n\nContents before skipping to a specific row:\n\n```\nArray\n(\n    [0] =\u003e Array\n        (\n            [0] =\u003e John\n            [1] =\u003e Doe\n            [2] =\u003e Simple Company Name\n            [3] =\u003e Street Name, 1234, City Name, Country Name\n        )\n    [1] =\u003e Array\n        (\n            [0] =\u003e Jane\n            [1] =\u003e Doe\n            [2] =\u003e Nice Company Name\n            [3] =\u003e Street Name, 5678, City Name, Country Name\n        )\n)\n```\n\nContents after skipping to a specific row:\n\n```\nArray\n(\n    [0] =\u003e Array\n        (\n            [0] =\u003e Jane\n            [1] =\u003e Doe\n            [2] =\u003e Nice Company Name\n            [3] =\u003e Street Name, 5678, City Name, Country Name\n        )\n)\n\n```\n\n#### `skip_to_column(int $col_index)`\n\nTo skip to a specific column, simply pass the index of the column.\n\n```php\nuse \\Carbon_CSV\\CsvFile as CsvFile;\nuse \\Carbon_CSV\\Exception;\n\n$csv = new CsvFile('path-to-file/filename.csv');\n$csv-\u003eskip_to_column(2);\n$rows = $csv-\u003eto_array();\n```\n\nContents before skipping to a specific column:\n\n```\nArray\n(\n    [0] =\u003e Array\n        (\n            [0] =\u003e John\n            [1] =\u003e Doe\n            [2] =\u003e Simple Company Name\n            [3] =\u003e Street Name, 1234, City Name, Country Name\n        )\n    [1] =\u003e Array\n        (\n            [0] =\u003e Jane\n            [1] =\u003e Doe\n            [2] =\u003e Nice Company Name\n            [3] =\u003e Street Name, 5678, City Name, Country Name\n        )\n)\n```\n\nContents after skipping to a specific column:\n\n```\nArray\n(\n    [0] =\u003e Array\n        (\n            [0] =\u003e Simple Company Name\n            [1] =\u003e Street Name, 1234, City Name, Country Name\n        )\n    [1] =\u003e Array\n        (\n            [0] =\u003e Nice Company Name\n            [1] =\u003e Street Name, 5678, City Name, Country Name\n        )\n)\n\n```\n\n#### `skip_columns(array $col_indexes)`\n\nTo skip multiple columns, pass the indexes of those columns as an array.\n\n```php\nuse \\Carbon_CSV\\CsvFile as CsvFile;\nuse \\Carbon_CSV\\Exception;\n\n$csv = new CsvFile('path-to-file/filename.csv');\n$csv-\u003eskip_columns(array(0, 2, 3));\n$rows = $csv-\u003eto_array();\n```\n\nContents before skipping columns:\n\n```\nArray\n(\n    [0] =\u003e Array\n        (\n            [0] =\u003e John\n            [1] =\u003e Doe\n            [2] =\u003e Simple Company Name\n            [3] =\u003e Street Name, 1234, City Name, Country Name\n        )\n    [1] =\u003e Array\n        (\n            [0] =\u003e Jane\n            [1] =\u003e Doe\n            [2] =\u003e Nice Company Name\n            [3] =\u003e Street Name, 5678, City Name, Country Name\n        )\n)\n```\n\nContents after skipping columns:\n\n```\nArray\n(\n    [0] =\u003e Array\n        (\n            [0] =\u003e Doe\n        )\n    [1] =\u003e Array\n        (\n            [0] =\u003e Doe\n        )\n)\n\n```\n\n#### `use_first_row_as_header()`\n\nTo use the first row from the CSV, simply call this method.\n\n**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. \n\n```php\nuse \\Carbon_CSV\\CsvFile as CsvFile;\nuse \\Carbon_CSV\\Exception;\n\n$csv = new CsvFile('path-to-file/filename.csv');\n$csv-\u003euse_first_row_as_header();\n$rows = $csv-\u003eto_array();\n```\n\nContents before assigning a header row:\n\n```\nArray\n(\n    [0] =\u003e Array\n        (\n            [0] =\u003e First Name\n            [1] =\u003e Last Name\n        )\n    [1] =\u003e Array\n        (\n            [0] =\u003e John\n            [1] =\u003e Doe\n        )\n    [2] =\u003e Array\n        (\n            [0] =\u003e Jane\n            [1] =\u003e Dove\n        )\n)\n```\n\nContents after assigning a header row:\n\n```\nArray\n(\n    [0] =\u003e Array\n        (\n            [First Name] =\u003e John\n            [Last Name] =\u003e Doe\n        )\n    [1] =\u003e Array\n        (\n            [First Name] =\u003e Jane\n            [Last Name] =\u003e Dove\n        )\n)\n```\n\nSince we're telling the parser to use the first row as a header row, it is assigned and skipped.\n\n#### `set_column_names(array $columns_mapping)`\n\nIf you wish to use your own indexes for the columns, pass them using an array.\n\n**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.\n\nExample without `use_first_row_as_header` (using a file without a head row):\n\n```php\nuse \\Carbon_CSV\\CsvFile as CsvFile;\nuse \\Carbon_CSV\\Exception;\n\n$csv = new CsvFile('path-to-file/filename-no-head-rows.csv');\n$csv-\u003eset_column_names([\n    0 =\u003e 'first_name',\n    1 =\u003e 'last_name',\n    2 =\u003e 'company_name',\n    3 =\u003e 'address',\n]);\n$rows = $csv-\u003eto_array();\n```\n\nContents before setting custom column names:\n\n```\nArray\n(\n    [0] =\u003e Array\n        (\n            [0] =\u003e John\n            [1] =\u003e Doe\n            [2] =\u003e Simple Company Name\n            [3] =\u003e Street Name, 1234, City Name, Country Name\n        )\n    [1] =\u003e Array\n        (\n            [0] =\u003e Jane\n            [1] =\u003e Doe\n            [2] =\u003e Nice Company Name\n            [3] =\u003e Street Name, 5678, City Name, Country Name\n        )\n)\n```\n\nContents after setting custom column names:\n\n```\nArray\n(\n    [0] =\u003e Array\n        (\n            [first_name] =\u003e John\n            [last_name] =\u003e Doe\n            [company_name] =\u003e Simple Company Name\n            [address] =\u003e Street Name, 1234, City Name, Country Name\n        )\n    [1] =\u003e Array\n        (\n            [first_name] =\u003e Jane\n            [last_name] =\u003e Doe\n            [company_name] =\u003e Nice Company Name\n            [address] =\u003e Street Name, 5678, City Name, Country Name\n        )\n)\n```\n\n----\n\nExample with `use_first_row_as_header` (using a file with a head row):\n\n```php\nuse \\Carbon_CSV\\CsvFile as CsvFile;\nuse \\Carbon_CSV\\Exception;\n\n$csv = new CsvFile('path-to-file/filename-no-head-rows.csv');\n$csv-\u003euse_first_row_as_header();\n$csv-\u003eset_column_names([\n    'First Name' =\u003e 'first_name',\n    'Last Name' =\u003e 'last_name',\n    'Company Name' =\u003e 'company_name',\n    'Address' =\u003e 'address',\n]);\n$rows = $csv-\u003eto_array();\n```\n\nContents before setting custom column names:\n\n```\nArray\n(\n    [0] =\u003e Array\n        (\n            [0] =\u003e First Name\n            [1] =\u003e Last Name\n            [2] =\u003e Company Name\n            [3] =\u003e Address\n        )\n    [1] =\u003e Array\n        (\n            [0] =\u003e John\n            [1] =\u003e Doe\n            [2] =\u003e Simple Company Name\n            [3] =\u003e Street Name, 1234, City Name, Country Name\n        )\n    [2] =\u003e Array\n        (\n            [0] =\u003e Jane\n            [1] =\u003e Doe\n            [2] =\u003e Nice Company Name\n            [3] =\u003e Street Name, 5678, City Name, Country Name\n        )\n)\n```\n\nContents after setting custom column names:\n\n```\nArray\n(\n    [0] =\u003e Array\n        (\n            [first_name] =\u003e John\n            [last_name] =\u003e Doe\n            [company_name] =\u003e Simple Company Name\n            [address] =\u003e Street Name, 1234, City Name, Country Name\n        )\n    [1] =\u003e Array\n        (\n            [first_name] =\u003e Jane\n            [last_name] =\u003e Doe\n            [company_name] =\u003e Nice Company Name\n            [address] =\u003e Street Name, 5678, City Name, Country Name\n        )\n)\n```\n\n#### `set_encoding($encoding)`\n\nSet the encoding of the CSV file.\nThis is needed, so it can be properly converted to utf-8\n\nExample:\n\n```php\nuse \\Carbon_CSV\\CsvFile as CsvFile;\nuse \\Carbon_CSV\\Exception;\n\n$csv = new CsvFile('path-to-file/filename.csv');\n$csv-\u003eset_encoding('windows-1251');\n$total_number_of_rows = $csv-\u003ecount();\n```\n\n#### `count()`\n\nGet the total number of rows in the CSV file (this skips the empty rows):\n\n```php\nuse \\Carbon_CSV\\CsvFile as CsvFile;\nuse \\Carbon_CSV\\Exception;\n\n$csv = new CsvFile('path-to-file/filename.csv');\n$total_number_of_rows = $csv-\u003ecount();\n```\n\n`$total_number_of_rows = $csv-\u003ecount()` is equivalent to `count($csv-\u003eto_array())`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhtmlburger%2Fcarbon-csv","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhtmlburger%2Fcarbon-csv","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhtmlburger%2Fcarbon-csv/lists"}