Re: [RFC] CSV Extension (ext/csv)
| From: | Damian Jóźwiak | Date: | Tue, 10 Nov 2026 11:07:38 +0000 |
| Subject: | Re: [RFC] CSV Extension (ext/csv) | ||
| References: | 1 2 3 | Groups: | php.internals |
| Request: | Send a blank email to internals+get-133051@lists.php.net to get a copy of this message | ||
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
>