Re: [RFC] CSV Extension (ext/csv)
| From: | ignace nyamagana butera | 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