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

From: Date: Tue, 10 Nov 2026 15:54:00 +0000
Subject: Re: [RFC] CSV Extension (ext/csv)
References: 1 2 3 4 5 6  Groups: php.internals 
Request: Send a blank email to internals+get-133061@lists.php.net to get a copy of this message
On Tue, Nov 10, 2026 at 2:45 PM Damian Jóźwiak < damian.jozwiak.lodz@gmail.com> wrote: > > 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 >> > Hi Damien, The interface could be introduced later on, but removing __toString automatic conversion should be done now. so It may look like a BC break or a regression vs the current conversion rules but IMHO it would be beneficial in the long run. I would put the change in the same category as removing resource to string conversion as you did. Best, Ignace

« previous php.internals (#133061) next »