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

From: Date: Tue, 10 Nov 2026 13:44:59 +0000
Subject: Re: [RFC] CSV Extension (ext/csv)
References: 1 2 3 4 5  Groups: php.internals 
Request: Send a blank email to internals+get-133059@lists.php.net to get a copy of this message
Hi Ignace, Thanks for the suggestion. I agree that a dedicated interface for converting objects into CSV fields could be useful. I'd prefer to avoid the term "serialization", as I've deliberately used "conversion" throughout the RFC. Something like Csv\FieldConvertible with a toCsvField() method would be more consistent with that terminology. There is one thing I'd like to consider before introducing it, though. The last item in the RFC's Future Scope section already mentions the possibility of an object-oriented API. I think a dedicated conversion interface would fit quite naturally into such an API. With the current function-based API, callers can already explicitly invoke their own conversion methods before passing values to the CSV functions: Csv\array_to_row([ $object->toCsvField(), ]); This provides explicit control over the CSV representation without requiring a new interface in the initial API. So the question, in my view, is whether we really need to introduce a dedicated interface now, or whether it would be better to revisit it alongside the potential object-oriented API, where its role and integration could be considered more broadly. I'm not opposed to the interface itself. I'd just prefer to avoid expanding the initial scope unless there's a compelling use case that the existing functions cannot reasonably accommodate. Best regards, Damian On Tue, Nov 10, 2026 at 1:38 PM ignace nyamagana butera <nyamsprod@gmail.com> wrote: > 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 Damien, > > Thanks for adding the conversion rules. I have had a look at them, and > there is one point I would like to raise. > > I am not entirely convinced that allowing any object implementing > Stringable to be implicitly cast to a string is the right approach. > > In my opinion, this is somewhat of an anti-pattern because it relies on a > generic string representation of an object rather than an explicit > serialization contract. An object's __toString() method is not > necessarily intended to provide a suitable representation for CSV output. > > I would suggest introducing a CSV-specific serialization interface > instead, with a single dedicated method that explicitly defines how an > object should be converted into a CSV field. > > Something along the lines of PHP's JsonSerializable interface: > > interface CsvSerializable > { > public function csvSerialize(): BackerEnum|string|int|float|bool|null; > } > > Names can be changed/improved. The return type would be restricted to the > types already supported by the CSV conversion rules. This would make the > conversion explicit, predictable and consistent with the rest of the > proposed serialization behaviour. > > It would also give objects the opportunity to provide a CSV-specific > representation without having to overload their general string > representation for that purpose. > > I believe this would be a cleaner and more extensible approach than > relying on Stringable. > > Best regards, > Ignace >

« previous php.internals (#133059) next »