Download the PHP package inwebo/csv without Composer

PHP CSV Reader & Writer

This library provides two classes — Inwebo\Csv\Reader and Inwebo\Csv\Writer — for reading and writing CSV files with a low memory footprint. Both extend PHP's SplFileObject, making all native file handling methods (like setCsvControl) available on each instance.

See the PHP documentation for SplFileObject for more details.

Key Features

• Column Name Mapping: Automatically maps each line's data to an associative array using the CSV header as keys, making your code more readable and maintainable.
• Data Normalization: Apply one or more callable functions to each line to clean and format the data before it's used.
• Data Filtering: Use callable functions to validate and filter out rows that don't meet your criteria.
• Generator-based Iteration: Process large files efficiently using a Generator to iterate over lines without consuming too much memory. Iteration always starts with a rewind().
• CSV Writing: Write rows one by one or from any iterable, including Generators, for memory-efficient ETL pipelines.
• Excel Compatibility: Optional UTF-8 BOM and configurable line endings (\r\n) for correct rendering in Excel on Windows.
• Inherits SplFileObject: Leverage all the native features and performance benefits of SplFileObject for file handling.

Installation

Tests

PhpStan

Level 10

Usage

Basic Reading

To get started, simply instantiate the Reader class with the path to your CSV file. By default, it assumes the first row contains column names, and data starts at index 1.

Disabling Column Names

If your CSV file does not have a header row, you can disable the column name mapping by setting the hasHeaders parameter to false. In this case, indices start at 0.

Manual Column Mapping

For files without a header, you can manually define column names using the setHeader() method. This allows you to treat the data as an associative array even without a header row. Indices start at 0.

Advanced Usage: Normalizers and Filters

You can add multiple normalizers and filters to your Reader instance. They are executed sequentially in the order they are added (FIFO).

Normalizers

Normalizers are used to modify the data. The callback receives the line array by reference, allowing you to directly alter its values. They are executed sequentially in the order they are added (FIFO).

Filters

Filters are used to validate and exclude entire rows. If a filter returns false, the line will be skipped and will not be yielded by the generator.

With both normalizers and filters in place, the processing loop becomes a clean, declarative statement of what you want to achieve.

Reading a Specific Range

You can also read a specific range of rows using the rows() method with from and to parameters. Both parameters must be provided together or both omitted.

[!IMPORTANT] When hasHeaders is true (default), the first data row is at index 1. When false, it starts at 0.

Reading a Specific Row

The rowAt() method allows you to retrieve a specific row by its index. If the row contains missing columns compared to the header, they will be returned as null.

Writer

Basic Writing

Instantiate Writer with the path to the output file. The default mode is 'w' (truncate or create). Use 'a' to append to an existing file.

All configuration methods return static for fluent chaining:

Writing Multiple Rows

rows() accepts any iterable — arrays or Generator objects:

Excel Compatibility

Enable the UTF-8 BOM to ensure correct character encoding when opening the file in Excel on Windows. Use \r\n as the line ending for RFC 4180 compliance.

The BOM is written automatically before the first row (header or data).

Custom Delimiter

CSV control (delimiter, enclosure, escape) is delegated to the inherited setCsvControl() method:

Filters and Normalizers

Filters and normalizers on the Writer follow the same FIFO pipeline as on the Reader. For each row, filters run first — if any returns false the row is skipped entirely — then normalizers transform the data before it is written.

Filters and normalizers do not apply to the header row written by setHeader().

Validating column count

A common use case is rejecting malformed rows whose column count does not match the header before writing them:

Normalizing data before writing

Normalizers receive the row array by reference, allowing direct modification:

Combining filters and normalizers

Filters and normalizers can be combined freely. The pipeline order is always: filter → normalize → write.

ETL: Reader to Writer

Because Writer::rows() accepts any iterable, you can pipe Reader::rows() directly into it without buffering the entire file in memory:

Filters and normalizers applied to the Reader are evaluated lazily during iteration, so the pipeline processes one row at a time regardless of file size.

Realistic Scenario: Customer Migration

This scenario reads a legacy customer CSV (tests/Fixtures/example.csv), cleans and filters the data, then writes two separate output files — one per segment — without ever loading the full file into memory.

We need to:

• Reject rows with a wrong column count.
• Clean up first and last names (trimming, casing).
• Format phone numbers.
• Formalize genders to 'M' or 'F'.
• Filter for valid email addresses.
• Output 1: Women with a salary < 10,000 → women.csv
• Output 2: Men with a salary > 22,500 → men.csv