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