Re: [RFC] CSV Extension (ext/csv)

From: Date: Tue, 10 Nov 2026 11:07:38 +0000
Subject: Re: [RFC] CSV Extension (ext/csv)
References: 1 2 3  Groups: php.internals 
Request: Send a blank email to internals+get-133051@lists.php.net to get a copy of this message
Hi Ignace, Thank you, that's a good catch. Writing the section showed that The RFC also contained an inconsistency between the documented behaviour and the implementation: it said unsupported fields throw a TypeError, but the implementation just did a plain string cast, exactly like fputcsv(). So arrays became "Array" with a warning, resources became "Resource id #N" silently, and all enums threw a generic Error. I've added a "Supported types" section to the RFC and updated the implementation to match. When writing, fields are converted as follows: - string: as is - null: empty field - bool: "1" / "0" (false used to be written as an empty field, which could not be told apart from null) - int: decimal representation - float: formatted with serialize_precision, like json_encode(). fputcsv() uses precision, so 0.1 + 0.2 was silently truncated to 0.3. - backed enum: its backing value - object convertible to string: the result of the string conversion (__toString(), or the internal cast of classes such as GMP) - pure enum, any other object, array, resource: TypeError The error names the field and the row, e.g. Field "name" of element 3 of the collection must be of type null|bool|int|float|string|BackedEnum or an object convertible to string, resource given. When reading, every field is returned as a string, with no type inference.. The one place where I deliberately diverge from the Query Params RFC is objects convertible to string. They are accepted without an explicit cast because fputcsv() and SplFileObject::fputcsv() accept them today, and this extension is meant to be the migration target for the latter. Requiring (string) there seemed like friction without much benefit. If you see a strong reason to align fully, I'm open to changing it. On your PS: I agree it's worth doing, but I've kept it out of this RFC and listed it under Future Scope. Adding backed enum support to fputcsv() would not be a BC break, since enums currently throw there. Like the http_build_query() change in 8.4 (GH-15650, fixed via GH-15704 without an RFC), it could be a small standalone PR for 8.7. Rejecting resources and arrays in the legacy functions, on the other hand, would be a BC break and would need a deprecation first. Best regards, Damian On Tue, Nov 10, 2026 at 9:36 AM ignace nyamagana butera <nyamsprod@gmail.com> wrote: > > On Thu, Oct 29, 2026 at 4:30 PM ignace nyamagana butera < > nyamsprod@gmail.com> wrote: > >> >> On Fri, Oct 9, 2026 at 8:22 AM Damian Jóźwiak < >> damian.jozwiak.lodz@gmail.com> wrote: >> >>> >>> Hi internals, >>> >>> I'd like to open the discussion on an RFC proposing a dedicated CSV >>> extension (ext/csv) for PHP core. >>> >>> RFC: https://wiki.php.net/rfc/csv_extension >>> >>> Implementation: >>> https://github.com/php/php-src/pull/24199 >>> >>> The proposal builds upon Gina Peter Banyard's girgias/csv extension >>> (BSD-3-Clause), with additional functionality for file and stream handling. >>> >>> The motivation includes the deprecation of the SplFileObject CSV >>> methods in PHP 8.6, which leaves certain use cases without a direct >>> replacement. >>> >>> The proposed extension provides: >>> >>> - >>> >>> Six functions and one class in the Csv\ namespace. >>> - >>> >>> RFC 4180-compatible parsing and serialization by default. >>> - >>> >>> Locale-independent processing without the proprietary escape >>> mechanism. >>> - >>> >>> Multibyte delimiters, enclosures, and EOL sequences. >>> - >>> >>> Strict and lax collection parsing. >>> - >>> >>> Lazy iteration over CSV files and streaming output. >>> >>> The implementation includes PHPT tests covering parsing, serialization, >>> stream handling, resource lifetime, and various edge cases. >>> >>> The pull request's CI checks are currently passing across the tested >>> platforms, including debug, ZTS, and AddressSanitizer configurations. >>> >>> The initial API is deliberately kept small. A more comprehensive >>> object-oriented Reader/Writer API, including capability-oriented >>> interfaces, is left for potential future discussion. >>> >>> I'd particularly appreciate feedback on the public API design, the >>> naming of LazyLaxCollection, and whether the extension should be always >>> enabled or optional at build time. >>> >>> For transparency, Gina has not reviewed or endorsed this RFC. Parts of >>> the implementation were developed with LLM assistance; I have reviewed the >>> code and take full responsibility for the contribution. >>> >>> This is an invitation for discussion, not a call for votes. >>> >>> Thanks in advance for your feedback. >>> >>> Best regards, >>> Damian Jóźwiak >>> >> >> Hi Damien, >> thanks for the proposal, indeed with the deprecation of SplFileObject CSV >> feature an object oriented alternative is welcomed having said that.I have >> a couple of remarks/suggestions >> >> >> - Following Tim's thought, I wonder if a CSV top namespace is >> mandatory or if we should not just have a Serialization "namespace" name >> that can be improved when such classes and functions are defined. >> - >> >> *RFC 4180-compatible parsing and serialization by default. *As much >> as I am a proponent of backing RFC whenever they exist in this case it >> should be stressed out that RFC4180 is not an accepted RFC like for >> instance RFC3986 for URI specification as such it is totally possible to >> have a valid CSV which does not comply with the refer draft specification. >> I believe this should be noted and explained in the RFC to avoid pushing >> forward something which is not a real specification as anyone would expect >> even though it is widely accepted as the "default" implementation, >> - >> >> Hence why I believe that using terms like *lax* and *strict* is >> counter productive; probably other names "to be defined" should be used >> instead. Maybe adding an Enum With RFC4180 and something else (?) would be >> a better take. Which would reduce the number of function/methods introduced >> ? >> - >> >> Also while it is common to talk about CSV, this feature would be >> perhaps better called *Character Separated Value* than Comma >> Separated Value since the delimiter can be changed. And covers TSV and >> other exotic formats which separates values per single character. >> >> 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). >> >> >> Does it mean that the LazyLaxCollection will expose the stream metadata ? >> If I receive in my method/function a LazyLaxCollection is it possible >> for me to get access to the underlying resource metadata ? To know how it >> is open, its pathname , and so forth ? Can I easily detect if >> >> Being able to configure the context or to apply stream filter is also >> something I find useful with the current set of csv function even with >> SplFileObject (even though it is tricky with that one) I would expect any >> API which aim at replacing the current CSV API to offer at most the same >> extensibility or to allow it in any other shape or form. >> >> >> function collection_to_file(string $file, iterable $collection, string $delimiter = >> ',', string $enclosure = '"', string $eolSequence = "\r\n"): void >> {} >> >> Why? can't we have access to the written bytes as returned value. >> Otherwise it means we need to re-access the resource afterward if we want >> to get access to that value. For example if we want to generate the >> Content-Length header or something else ? >> >> Overall, I like the direction of the RFC but I believe some major >> discussion points remain unsolved before going to a vote >> >> Best regards, >> Ignace >> > > Hi Damien, > > It just occurred to me that I forgot to mention one point: the RFC is > missing a section defining the supported types, similar to the one included > in the URI Query Parameters RFC: > https://wiki.php.net/rfc/query_params#supported_types. > > I believe such a section is important to avoid surprising behaviour when > generating CSV data. > > For instance, the current CSV implementation in PHP does not support > converting objects of any kind. However, since the introduction of enums, > both JSON serialization and http_build_query() support backed enums as > values that can be converted. I would therefore expect backed enums to be > supported by your proposal, or at the very least for this to be explicitly > addressed in the RFC. > > Conversely, resources are currently accepted during CSV conversion which > we all agree is an unfamiliar behaviour. This RFC could therefore be a good > opportunity to align CSV conversion with the new Query Params RFC (pending > its acceptance) and the existing JSON conversion rules, establishing a > common baseline for type conversion and serialization across PHP. > > *PS:* I realise this is not really the focus of your RFC, but it also > raises the question of whether support for backed enums should be added to > PHP's existing CSV functionality in PHP 8.7. After all, support for backed > enums in http_build_query() was introduced in PHP 8.4, rather than being > included when enums were first introduced. > > Best regards, > Ignace >

« previous php.internals (#133051) next »