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

From: Date: Sun, 22 Nov 2026 08:40:15 +0000
Subject: Re: [RFC] CSV Extension (ext/csv)
References: 1 2 3 4  Groups: php.internals 
Request: Send a blank email to internals+get-133180@lists.php.net to get a copy of this message
On Tue, Nov 10, 2026 at 12:07 PM Damian Jóźwiak < damian.jozwiak.lodz@gmail.com> wrote: > 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 >> > Hi Damian, After further testing and comparison between the json_encode rules for encoding and the upcoming query params RFC, to have a common baseline for conversion, the non finite float values INF, -INF and NAN should throw a ValueError on CSV conversion instead of being converted into their string name. This is already the case for json_encode where those values fail and the function return false or throw a JsonException that specifically say > Fatal error: Uncaught JsonException: Inf and NaN cannot be JSON encoded and it is also the case in the URI Query Parameters RFC: https://wiki.php.net/rfc/query_params#supported_types. where they will trigger a ValueError. Best regards, Ignace

« previous php.internals (#133180) next »