Download the PHP package popphp/pop-csv without Composer

pop-csv

• Overview
• Install
• Quickstart
• Loading Shortcuts
• Options
• Output CSV
• Blank Templates
• Append Data
• Read Large Files
• Validating a CSV String
• Errors

Overview

pop-csv provides a streamlined way to work with PHP data and the CSV format.

It is a component of the Pop PHP Framework.

Install

Install pop-csv using Composer.

composer require popphp/pop-csv

Or, require it in your composer.json file

"require": {
    "popphp/pop-csv" : "^5.0.0"
}

Top

Quickstart

Create a CSV string

The $csvString variable now contains:

first_name,last_name
Bob,Smith
Jane,Smith

Create data from a CSV string

You can either pass the data object a direct string of serialized data or a file containing a string of serialized data. It will detect which one it is and parse it accordingly.

How the constructor's first argument is interpreted:

• A non-string value (an array, ArrayObject, etc.) is treated as PHP data.
• A string is treated as a file path only if it contains .csv or .tsv (case-insensitive) and a file actually exists at that path — its contents are read in immediately.
• Any other string is treated as raw CSV/TSV text to be parsed later.

Accessors and state

A Csv object holds two properties: the PHP array (data) and the CSV text (string). You can read or set either directly, and check which one(s) have been populated:

writeToFile(), outputToHttp(), and casting the object to a string all auto-serialize $data into $string if it hasn't happened yet, so echo-ing a Csv object built from data works without an explicit serialize() call:

Top

Loading Shortcuts

Static methods are available for the common "load and immediately use" and "build and immediately output" patterns, so you don't need to instantiate a Csv object and call a second method yourself:

All of these accept the same ?array $options as the constructor.

Top

Options

Where serializing or unserializing CSV data, there are a set of options available to tailor the process:

Map/Columns Example

Pass the options array to constructor method:

The above will output the following CSV data:

Guard Against Formula Injection

If any of the data being serialized may have originated from user input, opening the resulting CSV in a spreadsheet application (Excel, Google Sheets, LibreOffice) can execute formulas hidden in cells that start with =, +, - or @. Set the escapeFormulas option to true to neutralize this by prefixing any non-numeric cell that starts with one of those characters with a single quote:

This is disabled by default to preserve existing output for data that isn't user-controlled.

TSV (and Other Delimiters)

Set delimiter to "\t" to work with tab-separated data instead of comma-separated. A file path ending in .tsv is auto-detected by the constructor exactly like .csv is:

The delimiter option isn't limited to , and \t — any single-character delimiter works the same way.

Top

Output CSV

Write to File

Output to HTTP

Force download of file

$forceDownload defaults to true, which sends attachment in the Content-Disposition header so the browser downloads the file instead of trying to display it. Pass false to disable that and let the browser handle it inline instead:

Additional HTTP headers

Additional HTTP headers can be passed to the third parameter:

Top

Blank Templates

If you need to hand someone a blank CSV containing only the header row (e.g. as a template they'll fill in and re-upload), use the *Blank*/*Template* methods instead of the regular output methods. The header row is derived from the keys of the first data row, so you still need at least one row of representative data — you can't generate a template purely from a list of column names.

All four accept the same trailing $delimiter, $exclude, and $include parameters as their regular counterparts. Calling writeBlankFile()/outputBlankFileToHttp() before any data has been set throws Pop\Csv\Exception — see Errors.

Top

Append Data

In the case of working with large data sets, you can append CSV data to an existing file on disk. This prevents loading large amounts of data into memory that may exceed the PHP environment's limits. The target file must already exist — appending is for adding to a file you've already created, not creating one from scratch.

Append multiple rows

Append a single row

Both are also available as instance methods (appendData()/appendRow()), which use the Csv object's own options instead of a fresh $options array:

Column validation

By default, every append call re-reads the target file's header row and compares it against the new row's keys (array_keys($row)), throwing Pop\Csv\Exception on a mismatch (including order). Pass false as the last argument to skip this check — for example, if you're confident the shape matches and want to avoid the extra read per row, or the file has no header row at all:

Top

Read Large Files

Reading a CSV file with Csv::getDataFromFile(), loadFile() or unserialize() loads the entire result into memory as a PHP array. For very large files, use Csv::readRowsFromFile() instead, which returns a generator and yields one row at a time without ever holding the full file in memory:

It accepts the same options as the other read methods (delimiter, enclosure, escape, fields, etc.), and throws Pop\Csv\Exception if the file doesn't exist.

Counting rows without loading the file

If you just need a row count (e.g. for a progress bar before an import), Csv::getRowCountFromFile() streams the file the same way, without building any array of the data at all:

Options: headers (bool, subtract 1 from the count if the file has a header row, default false), skip_blank (bool, skip blank lines, default true), plus delimiter/enclosure/escape/length.

Top

Validating a CSV String

Csv::isValid() is a lightweight sanity check for a string you suspect might be CSV data — useful before attempting to parse something from an untrusted or unknown source:

It returns false for an empty string or for a string where the data rows don't all have the same number of columns as the first row. It does not validate character encoding or confirm the actual delimiter/ enclosure characters in use — it's a quick structural check, not a full CSV parser/validator.

Top

Errors

All of the following throw Pop\Csv\Exception (which extends PHP's built-in \Exception):

• writeBlankFile() / outputBlankFileToHttp() (and the static equivalents writeTemplateToFile() / outputTemplateToHttp()) — called before any data has been set on the Csv object.
• appendDataToFile() / appendRowToFile() (and the instance equivalents appendData()/appendRow()) — the target file doesn't exist.
• appendRowToFile() / appendRow() — $validate is true (the default) and the row's keys don't match the target file's existing header row.
• readRowsFromFile() — the target file doesn't exist.

Top