PHP: rfc:csv_extension

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== PHP RFC: CSV Extension (ext/csv) ======
  * Version: 1.1
  * Date: 2026-10-09
  * Author: Damian Jóźwiak, damian.jozwiak.lodz@gmail.com
  * Based on: the [[https://gitlab.com/Girgias/csv-php-extension|girgias/csv]] extension by Gina Peter Banyard (BSD-3-Clause)
  * Status: Under Discussion
  * Implementation: https://github.com/php/php-src/pull/24199
  * Discussion thread: tbd
  * Voting thread: tbd

This proposal builds on Gina Peter Banyard's ''girgias/csv'' extension. Gina has not reviewed this RFC, and it should not be read as her endorsement.

===== Introduction =====
PHP 8.6 deprecated the CSV methods of ''SplFileObject'' without providing a replacement. This RFC proposes a small CSV extension that follows RFC 4180 conventions by default in the ''Csv\'' namespace that fills that gap and, unlike the existing CSV functions, is locale-independent, has no proprietary escape character and supports multibyte delimiters and enclosures.

<PHP>
<?php

function rows(): Generator {
    yield ['id', 'value'];
    for ($i = 1; $i <= 3; $i++) {
        yield [(string) $i, "row $i"];
    }
}

$file = sys_get_temp_dir() . '/example.csv';
Csv\collection_to_file($file, rows());

foreach (Csv\LazyLaxCollection::createFromFile($file) as $row) {
    echo implode(' | ', $row), "\n";
}
// id | value
// 1 | row 1
// 2 | row 2
// 3 | row 3

?>
</PHP>

PHP's built-in CSV tooling (''fgetcsv()'', ''fputcsv()'', ''str_getcsv()'' and the CSV methods of ''SplFileObject'') predates RFC 4180 adoption in the wider ecosystem and carries behaviour that cannot be fixed without breaking compatibility:

  * A proprietary ''$escape'' mechanism incompatible with every other CSV implementation. Relying on its default was deprecated in PHP 8.4 ("Kill proprietary CSV escaping mechanism") and the default becomes ''%%""%%'' in PHP 9.0.
  * Locale-dependent parsing: the parser consults ''LC_CTYPE'' through ''mblen()''/''isspace()'', so the same file can parse differently depending on ''setlocale()''.
  * Single-byte delimiters and enclosures only.
  * An empty line parses as ''[null]''; whitespace before an opening enclosure is silently dropped (''%% "a" ,b%%'' parses as ''["a ", "b"]''); fields containing a space are enclosed on output although RFC 4180 does not require it.
  * There is no inverse of ''str_getcsv()''; writing a CSV string requires a ''php://memory'' stream.

PHP 8.6 deprecated ''SplFileObject::fgetcsv()'', ''SplFileObject::fputcsv()'', ''SplFileObject::setCsvControl()'' and ''SplFileObject::getCsvControl()'' ([[rfc:deprecations_php_8_6|Deprecations for PHP 8.6]]) **without providing a replacement**. Two gaps were raised on the mailing list during that discussion and remain open:

  - ''SplFileObject::fputcsv()'' has no drop-in replacement: the procedural ''fputcsv()'' requires a stream resource, and ''SplFileObject'' does not expose its underlying stream.
  - ''SplFileObject::READ_CSV'' was not deprecated, yet ''setCsvControl()'', the only way to configure the dialect it uses, was.

This RFC proposes to close those gaps by adding a small, RFC 4180 compliant CSV extension to the core, based on the existing ''girgias/csv'' extension, extended with file/stream support.

===== Proposal =====
Add a new, always-enabled extension ''ext/csv'' providing six functions and one class in the ''Csv\'' namespace. With the default dialect, they follow RFC 4180 conventions: fields containing the delimiter, the enclosure, CR, LF or the EOL sequence are enclosed; enclosures inside enclosed fields are escaped by doubling; there is **no escape character**. Delimiters, enclosures and EOL sequences may be multibyte, and parsing is binary safe and locale-independent.

==== Strict parsing ====
Whatever the dialect, the parser applies the record grammar of RFC 4180 section 2 strictly and throws a ''ValueError'' instead of guessing on input that does not follow it:

  * an enclosure inside a non-enclosed field (''%%a"b%%'', or whitespace or a BOM before the opening enclosure);
  * data between a closing enclosure and the next delimiter or EOL sequence (''%%"a"b%%'', ''%%"a" ,b%%'');
  * an enclosure that is never closed;
  * a CR or LF in a non-enclosed field that is not part of the EOL sequence. This is also what reports input using a different line ending than the one expected: an LF-only file read with the default ''"\r\n"'' is an error rather than one long row, and is read by passing ''"\n"''.

When a proper prefix of a multibyte enclosure is also its suffix (e.g. ''%%''%%'' or ''--''), an enclosed field ending with that prefix is written as bytes where the enclosure also occurs just before the closing one; the closing enclosure is the one followed by the delimiter, the EOL sequence or the end of the input, so every field written by ''array_to_row()''/''collection_to_buffer()'' reads back unchanged.

==== String and row conversion ====

<PHP>
<?php

namespace Csv;

function array_to_row(array $fields, string $delimiter = ',', string $enclosure = '"', string $eolSequence = "\r\n"): string {}

function row_to_array(string $row, string $delimiter = ',', string $enclosure = '"', string $eolSequence = "\r\n"): array {}

?>
</PHP>

''array_to_row()'' formats one row (the inverse of ''str_getcsv()'', which PHP currently lacks); ''row_to_array()'' parses exactly one row: a trailing EOL sequence is accepted, any data after it is a ''ValueError''.

==== Collection conversion ====

<PHP>
<?php

namespace Csv;

function collection_to_buffer(iterable $collection, string $delimiter = ',', string $enclosure = '"', string $eolSequence = "\r\n"): string {}

function buffer_to_collection(string $buffer, string $delimiter = ',', string $enclosure = '"', string $eolSequence = "\r\n"): array {}

function buffer_to_collection_lax(string $buffer, string $delimiter = ',', string $enclosure = '"', string $eolSequence = "\r\n"): array {}

?>
</PHP>

''collection_to_buffer()'' accepts any ''iterable'' of arrays (including generators) and checks that every row has the same number of fields, throwing a ''ValueError'' otherwise, as does ''buffer_to_collection()'' when parsing. The ''_lax'' variant permits rows of varying width.

==== File and stream handling ====

<PHP>
<?php

namespace Csv;

function collection_to_file(string $file, iterable $collection, string $delimiter = ',', string $enclosure = '"', string $eolSequence = "\r\n"): void {}

?>
</PHP>

''collection_to_file()'' writes rows one at a time through the streams layer, so a generator-backed collection of any size is written in constant memory. ''$file'' accepts anything the streams layer accepts (paths, ''php://'', ''compress.zlib://'', user wrappers) and is opened with the default stream context (''stream_context_set_default()''). Failures to open, write or finish writing (e.g. a failing flush of a compressed stream on close) throw; a failure to open carries the reason reported by the wrapper. A row is held for the whole time it is formatted, so a field's ''%%__toString()%%'' that advances the generator producing the rows is safe.

<PHP>
<?php

namespace Csv;

/**
 * @not-serializable
 * @strict-properties
 */
final class LazyLaxCollection implements \IteratorAggregate
{
    private function __construct() {}

    public function getIterator(): \InternalIterator {}

    public static function createFromBuffer(string $buffer, string $delimiter = ',', string $enclosure = '"', string $eolSequence = "\r\n"): LazyLaxCollection {}

    public static function createFromFile(string $file, string $delimiter = ',', string $enclosure = '"', string $eolSequence = "\r\n"): LazyLaxCollection {}
}

?>
</PHP>

''LazyLaxCollection'' iterates rows lazily. ''createFromFile()'' opens a stream with the default stream context and holds it: rows are read in chunks with an enclosure-aware scanner (an EOL sequence inside an enclosed field does not terminate a row) that resumes where it stopped after each read, so a row is found in linear time however long it is, and the internal window buffer is compacted as rows are consumed, so memory usage is proportional to the longest row rather than to the file. The stream is owned by the object: like the stream of ''SplFileObject'', it remains visible as a resource but ''fclose()'' refuses to close it, and it is closed when the object is destroyed (for an object alive until the end of the request, while destructors run, so a user wrapper's ''stream_close()'' is still called).

The iteration state belongs to the iterator, not to the collection. Loops over a collection created from a buffer are independent of each other, so nested loops over the same collection see every pair of rows. A collection created from a file reads one stream, so only one loop may iterate it at a time; starting a second one while the first is active throws an ''Error''. Iteration can be restarted (''foreach'' twice), including after an early ''break'', as long as the underlying stream is seekable.

==== Error handling ====

  * ''ValueError'' for invalid dialect arguments (empty delimiter/enclosure/EOL, delimiter identical to enclosure or to the EOL sequence), for input that does not follow RFC 4180 (see [[#strict_parsing|Strict parsing]]), for more than one row passed to ''row_to_array()'', and for inconsistent row widths in the strict functions.
  * ''TypeError'' when a collection element is not an array (a reference to an array is accepted), or a field is not stringable.
  * ''Error'' for I/O failures (open, read, write, flush-on-close; the open failure carries the wrapper's reason, e.g. "Failed to open stream: No such file or directory"), for rewinding a non-seekable stream, and for a second concurrent loop over a collection created from a file.
  * No function returns ''false''; end of iteration is expressed by the iterator protocol.

==== Migration from the deprecated SplFileObject API ====

^ Deprecated (8.6) ^ Replacement ^
| ''new SplFileObject($f)'' + ''READ_CSV'' + flags | ''Csv\LazyLaxCollection::createFromFile($f, ...)'' |
| ''SplFileObject::fgetcsv()'' in a loop | ''foreach (Csv\LazyLaxCollection::createFromFile(...))'' |
| ''SplFileObject::fputcsv()'' in a loop | ''Csv\collection_to_file($f, $rows, ...)'' |
| ''SplFileObject::setCsvControl()'' | dialect arguments of the calls above |
| ''str_getcsv()'' (no inverse) | ''Csv\row_to_array()'' / ''Csv\array_to_row()'' |

Note the deliberate semantic differences from the legacy API: no escape character (in line with the PHP 9.0 default), no ''[null]'' for empty lines, no locale dependence, an enclosure inside a non-enclosed field, data after a closing enclosure and an unterminated enclosure are errors rather than literal data, whitespace before an enclosure is not silently dropped, exceptions instead of ''false'', and ''"\r\n"'' as the default EOL sequence as specified by RFC 4180. ''fgetcsv()'' accepts both CRLF and LF line endings; with ext/csv the EOL sequence is explicit, so files with LF line endings are read by passing ''"\n"''.

==== Examples ====

Round trip through a string, with enclosed fields containing the enclosure and a line break:

<PHP>
<?php

$rows = [
    ['id', 'name', 'note'],
    ['1', 'Alice', 'says "hi"'],
    ['2', 'Bob', "multi\nline"],
];

$csv = Csv\collection_to_buffer($rows);
echo $csv;
// id,name,note
// 1,Alice,"says ""hi"""
// 2,Bob,"multi
// line"

var_dump(Csv\buffer_to_collection($csv) === $rows); // bool(true)

?>
</PHP>

Multibyte delimiter, enclosure and EOL sequence:

<PHP>
<?php

$row = Csv\array_to_row(['a', 'b;;c', 'd'], ';;', "''", "\n");
var_dump($row);                                  // string(15) "a;;''b;;c'';;d\n"
var_dump(Csv\row_to_array($row, ';;', "''", "\n")); // ['a', 'b;;c', 'd']

?>
</PHP>

Edge cases: strict and lax row widths, and errors:

<PHP>
<?php

try {
    Csv\buffer_to_collection("a,b\r\nc\r\n");
} catch (ValueError $e) {
    echo $e->getMessage(), "\n";
    // Buffer row 2 contains 1 fields compared to 2 fields on previous rows
}

var_dump(Csv\buffer_to_collection_lax("a,b\r\nc\r\n")); // [['a', 'b'], ['c']]

var_dump(str_getcsv('', escape: '')); // [null]
var_dump(Csv\row_to_array(''));       // ['']

try {
    Csv\LazyLaxCollection::createFromFile('/nonexistent/file.csv');
} catch (Error $e) {
    echo $e->getMessage(), "\n";
    // Csv\LazyLaxCollection::createFromFile(): Failed to open stream: No such file or directory
}

?>
</PHP>

Input that does not follow RFC 4180 is rejected instead of guessed:

<PHP>
<?php

try {
    Csv\buffer_to_collection("\"a\"b,c\r\n");
} catch (ValueError $e) {
    echo $e->getMessage(), "\n";
    // Closing enclosure sequence must be followed by the delimiter or the EOL sequence
}

try {
    Csv\buffer_to_collection("a,b\nc,d\n"); // LF line endings, default EOL "\r\n"
} catch (ValueError $e) {
    echo $e->getMessage(), "\n";
    // A non escaped field must not contain CR or LF characters that are not part of the EOL sequence
}

var_dump(Csv\buffer_to_collection("a,b\nc,d\n", eolSequence: "\n")); // [['a', 'b'], ['c', 'd']]

?>
</PHP>

===== Backward Incompatible Changes =====
No existing built-in function, class or constant is changed. However, the ''Csv\'' top-level namespace would become reserved for this extension, following the [[rfc:namespaces_in_bundled_extensions|policy on namespaces in bundled extensions]]; userland code declaring symbols in ''Csv\'' may conflict, as with the ''Random\'' and ''Uri\'' namespaces before it.

===== Proposed PHP Version(s) =====
Next minor PHP version (the release after PHP 8.6).

===== RFC Impact =====
==== To the Ecosystem ====
No new syntax. IDEs, language servers and static analysers need stubs for the new functions and class, which can be taken from ''ext/csv/csv.stub.php''. Userland CSV libraries are unaffected.

==== To Existing Extensions ====
None. ''ext/standard'' and ''ext/spl'' are unchanged.

==== To SAPIs ====
None beyond a new always-enabled extension.

==== New Constants ====
None.

==== php.ini Defaults ====
None.

===== Open Issues =====
  * Whether the extension should be disableable at build time. The implementation currently supports ''--disable-csv''; the proposal is to make it always enabled, like ''ext/random'' and ''ext/uri'', since a migration target for a deprecated core API must be reliably present.
  * Naming of ''LazyLaxCollection'' and whether a strict lazy variant should ship in the first version.
  * Dialects in which one token is a prefix of another (e.g. delimiter ''::'', enclosure '':-'', EOL '':'') are inherently ambiguous: some collections written with them cannot be read back. They could be rejected during argument validation, at the cost of rejecting some dialects that work for the data at hand.

===== Unaffected PHP Functionality =====
''fgetcsv()'', ''fputcsv()'', ''str_getcsv()'' and the deprecated ''SplFileObject'' CSV methods keep their current behaviour. This RFC neither changes nor deprecates them.

===== Future Scope =====
  * A deprecation timeline for the non-compliant ''str_getcsv()'', ''fputcsv()'' and ''fgetcsv()'' functions, as previously outlined by the ''girgias/csv'' project. Deliberately **not** part of this RFC.
  * Deprecation of ''SplFileObject::READ_CSV'' in a separate follow-up RFC once this replacement exists, resolving the inconsistency left by the 8.6 deprecations.
  * Header handling (mapping rows to associative arrays), encoding/BOM handling, and further convenience APIs, which can be built in userland on top of the provided primitives.
  * **Object-oriented Reader/Writer API.** A separate future RFC may introduce dedicated Csv\Reader and Csv\Writer classes with capability-oriented interfaces (such as Csv\Readable and Csv\Writable) to support dependency injection, testability, and alternative implementations. The exact contracts and naming would be decided in that future RFC. The current proposal deliberately limits its scope to procedural functions and the stateful iterator; it does not reject object-oriented design.

===== Voting Choices =====
Please consult [[https://github.com/php/policies/blob/main/feature-proposals.rst#voting-phase|the php/policies repository]] for the current voting guidelines.

Voting has not started. If the RFC proceeds to a vote after the required discussion period, the proposed primary question is:

  * Add the CSV extension (''ext/csv'') to PHP core as described in this RFC? (Yes/No; 2/3 majority required.)

The voting widget and dates will be added when voting is formally announced.

===== Patches and Tests =====
Implementation targeting php-src ''master'': ''ext/csv'', a port of ''girgias/csv'' 0.6.0 (BSD-3-Clause, copyright Gina Peter Banyard and Contributors) with the new ''collection_to_file()'' and ''LazyLaxCollection::createFromFile()'' APIs.

  * Branch: https://github.com/damek24/php-src/tree/rfc-csv
  * 90 phpt tests, including regression tests for sparse collections, multibyte dialect tokens at read-chunk boundaries, iterator cleanup on error paths, strict RFC 4180 parsing, nested iteration, and stream lifecycle (resource references retained by userland, ''fclose()'' refused, closing at shutdown, flush-on-close failures).
  * Six bugs present in ''girgias/csv'' 0.6.0 were found and fixed during the port; they will be reported upstream.
  * A review of the pull request by [[https://github.com/ArtUkrainskiy|ArtUkrainskiy]] ([[https://github.com/ArtUkrainskiy/php-src-bench/tree/main/reports/csv-pr-24199|report]]) found a use-after-free (also present in ''girgias/csv'' 0.6.0), a quadratic rescan of long rows in ''createFromFile()'' and several smaller issues; all are fixed and covered by tests, verified with AddressSanitizer and a differential fuzzer comparing file and buffer parsing ([[https://github.com/damek24/php-csv-rfc/tree/main/reports/csv-pr-24199-fixes|report]]).
  * Performance is not a goal of this RFC, but the parser is not slower than the built-ins: on the reviewer's benchmark, reading a file with ''createFromFile()'' takes 363/446/1,539 ns per row (plain/quoted/50 fields) against 402/586/1,742 for ''fgetcsv()'' with the ''php_mblen()'' fast path of [[https://github.com/php/php-src/pull/24207|#24207]], and 3,008/3,572/14,526 without it. Writing is 10–20% slower than ''fputcsv()''.

Disclosure: parts of the implementation were written with the assistance of an LLM. The author has reviewed all of it and takes full responsibility for it.

===== Implementation =====
  * Pull request: https://github.com/php/php-src/pull/24199
  * Development branch: https://github.com/damek24/php-src/tree/rfc-csv

===== References =====
  * RFC 4180: https://www.rfc-editor.org/rfc/rfc4180
  * ''girgias/csv'' extension: https://gitlab.com/Girgias/csv-php-extension (PECL/PIE: ''girgias/csv'')
  * [[rfc:deprecations_php_8_6|Deprecations for PHP 8.6]] (SplFileObject CSV methods)
  * [[rfc:deprecations_php_8_4|Deprecations for PHP 8.4]] (proprietary CSV escaping)
  * Mailing list discussion of the 8.6 deprecation and its migration gaps: https://discourse.thephp.foundation/t/re-php-dev-rfc-deprecations-for-php-8-6/5636 and https://discourse.thephp.foundation/t/php-dev-re-fwd-rfc-deprecations-for-php-8-6/5939

===== Rejected Features =====
  * **An object-oriented Reader/Writer API in this RFC.** A comprehensive OO API, including instance-based readers/writers and possible interfaces, deserves separate design and review. Adding it here would expand the scope and public API before those contracts have been discussed. The ''LazyLaxCollection'' class is included now because lazy iteration requires holding state; OO APIs remain possible future work.
  * **Compatibility with the legacy ''fgetcsv()'' dialect** (escape character, ''[null]'' rows, locale dependence). Migrating code is expected to adopt the standard-compliant behaviour rather than carry the legacy quirks forward.

===== Changelog =====
  * 1.0 (2026-10-08): Initial draft prepared for publication; discussion and voting have not started.
  * 1.1 (2026-10-09): Updated after the review of the implementation: strict parsing section (data after a closing enclosure, unterminated enclosures and CR/LF outside enclosed fields are errors), ''row_to_array()'' accepts exactly one row, per-iterator iteration state, stream ownership like ''SplFileObject'' and the default stream context, performance notes, open issue on ambiguous dialects.
Page Tools
