Everything

php

[DISCUSS] Should RFCs for new functions include a userland polyfill/reference implementation?

php.internals

سپهر محمودی

7 days ago

Hi internals,

While reviewing various RFCs that introduce new functions, I noticed an
inconsistency: some authors include a userland polyfill (reference
implementation) in their RFCs, while others do not.

I wanted to open a discussion on whether we should strongly encourage RFC
authors to provide a PHP userland implementation when proposing new
standard library functions, **where technically feasible**.

Of course, I understand that this isn't possible for every new
function—especially those that interact with low-level OS APIs, memory
management, or internal engine features. However, for functions dealing
with arrays, strings, math, or general logic, I believe this has a couple
of major benefits:

1. It clarifies the exact intended behavior, including edge cases and type
coercions, making the proposal easier to understand without diving into the
C implementation.
2. It immensely helps the community (e.g., the Symfony polyfill team) to
quickly and accurately port the function to older PHP versions once the RFC
is accepted.

Should we consider adding this as a standard recommendation (e.g.,
"Reference Implementation") in the official RFC template for applicable
functions?

I would love to hear your thoughts on this.

Best regards,
Sepehr

Larry Garfield

7 days ago

On Tue, Aug 25, 2026, at 6:18 AM, سپهر محمودی wrote:

> Hi internals,
>
> While reviewing various RFCs that introduce new functions, I noticed an
> inconsistency: some authors include a userland polyfill (reference
> implementation) in their RFCs, while others do not.
>
> I wanted to open a discussion on whether we should strongly encourage
> RFC authors to provide a PHP userland implementation when proposing new
> standard library functions, **where technically feasible**.
>
> Of course, I understand that this isn't possible for every new
> function—especially those that interact with low-level OS APIs, memory
> management, or internal engine features. However, for functions dealing
> with arrays, strings, math, or general logic, I believe this has a
> couple of major benefits:
>
> 1. It clarifies the exact intended behavior, including edge cases and
> type coercions, making the proposal easier to understand without diving
> into the C implementation.
> 2. It immensely helps the community (e.g., the Symfony polyfill team)
> to quickly and accurately port the function to older PHP versions once
> the RFC is accepted.
>
> Should we consider adding this as a standard recommendation (e.g.,
> "Reference Implementation") in the official RFC template for applicable
> functions?
>
> I would love to hear your thoughts on this.
>
> Best regards,
> Sepehr

Interesting idea.  I think "recommended where relevant, but not required" is a reasonable policy to have.  As noted, many RFCs don't have polyfillable features.  For those where it is feasible, I think the "make it clear what the logic is" angle is the most compelling.  (I often do that in the non-polyfill RFCs to help clarify the behavior.)  And it would also give us a target to benchmark against to see if putting it in C really has a performance benefit.

--Larry Garfield

سپهر محمودی

7 days ago

در تاریخ سه‌شنبه ۲۵ اوت ۲۰۲۶، ۱۹:۰۸ Larry Garfield <larry@garfieldtech.com>
نوشت:

> On Tue, Aug 25, 2026, at 6:18 AM, سپهر محمودی wrote:
> > Hi internals,
> >
> > While reviewing various RFCs that introduce new functions, I noticed an
> > inconsistency: some authors include a userland polyfill (reference
> > implementation) in their RFCs, while others do not.
> >
> > I wanted to open a discussion on whether we should strongly encourage
> > RFC authors to provide a PHP userland implementation when proposing new
> > standard library functions, **where technically feasible**.
> >
> > Of course, I understand that this isn't possible for every new
> > function—especially those that interact with low-level OS APIs, memory
> > management, or internal engine features. However, for functions dealing
> > with arrays, strings, math, or general logic, I believe this has a
> > couple of major benefits:
> >
> > 1. It clarifies the exact intended behavior, including edge cases and
> > type coercions, making the proposal easier to understand without diving
> > into the C implementation.
> > 2. It immensely helps the community (e.g., the Symfony polyfill team)
> > to quickly and accurately port the function to older PHP versions once
> > the RFC is accepted.
> >
> > Should we consider adding this as a standard recommendation (e.g.,
> > "Reference Implementation") in the official RFC template for applicable
> > functions?
> >
> > I would love to hear your thoughts on this.
> >
> > Best regards,
> > Sepehr
>
> Interesting idea.  I think "recommended where relevant, but not required"
> is a reasonable policy to have.  As noted, many RFCs don't have
> polyfillable features.  For those where it is feasible, I think the "make
> it clear what the logic is" angle is the most compelling.  (I often do that
> in the non-polyfill RFCs to help clarify the behavior.)  And it would also
> give us a target to benchmark against to see if putting it in C really has
> a performance benefit.
>
> --Larry Garfield
>

----------

I'm really glad to see Larry's positive feedback. Looking forward to
hearing more thoughts from everyone else on this.

Best,
Sepehr

سپهر محمودی

6 days ago

Hi Larry,

Thanks for the feedback!

I completely agree with the "recommended where relevant, but not required"
approach. Making it a strict requirement would be an unnecessary blocker
for features that simply can't be polyfilled.

Your point about benchmarking is spot on. Having a userland implementation
gives us a clear baseline to prove that the C implementation actually
offers a tangible performance benefit, which is often a key argument in
many RFCs. And as you mentioned, it acts as a perfect executable
specification to clarify the expected behavior.

Given this, do you think it would be worth adding a short note or
recommendation to the RFC HOWTO document? Just as a gentle encouragement
for future RFC authors to include a userland polyfill (or equivalent PHP
logic) when feasible.

Best regards,
Sepehr


در تاریخ سه‌شنبه ۲۵ اوت ۲۰۲۶، ۱۹:۴۴ سپهر محمودی <sepehrphpr@gmail.com> نوشت:

Tim Düsterhus

1 day ago

Hi

On 2026-08-25 17:34, Larry Garfield wrote:

> And it would also give us a target to benchmark against to see if
> putting it in C really has a performance benefit.

I believe performance should not be a factor in deciding what should be
part of the stdlib and what should not: Performance is a moving target
and what might be true today might no longer be true tomorrow - with
folks generally having wildly incorrect assumptions about what actually
is “slow”.

Once we add something to the stdlib we need to maintain it for the next
15+ years. (Broad) usefulness and good API design must be the deciding
factors for whether something should be in the stdlib or not [1].

With PIE it has become easier than ever to build a custom extension for
one’s personal use cases to improve performance there.

Best regards
Tim Düsterhus

[1] It is debatable if the non-required bundled extensions are part of
the stdlib or not, for some of the more obscure ones like ext/tidy there
likely is a little more leeway in “just do it”.

Nicolas Grekas

5 days ago

Hi  Sepehr

‪Le mar. 25 août 2026 à 13:21, ‫سپهر محمودی‬‎ <sepehrphpr@gmail.com> a
écrit :‬

> Hi internals,
>
> While reviewing various RFCs that introduce new functions, I noticed an
> inconsistency: some authors include a userland polyfill (reference
> implementation) in their RFCs, while others do not.
>
> I wanted to open a discussion on whether we should strongly encourage RFC
> authors to provide a PHP userland implementation when proposing new
> standard library functions, **where technically feasible**.
>
> Of course, I understand that this isn't possible for every new
> function—especially those that interact with low-level OS APIs, memory
> management, or internal engine features. However, for functions dealing
> with arrays, strings, math, or general logic, I believe this has a couple
> of major benefits:
>
> 1. It clarifies the exact intended behavior, including edge cases and type
> coercions, making the proposal easier to understand without diving into the
> C implementation.
> 2. It immensely helps the community (e.g., the Symfony polyfill team) to
> quickly and accurately port the function to older PHP versions once the RFC
> is accepted.
>
> Should we consider adding this as a standard recommendation (e.g.,
> "Reference Implementation") in the official RFC template for applicable
> functions?
>
> I would love to hear your thoughts on this.
>
> Best regards,
> Sepehr
>
>

In case you didn't know, every polyfill-able feature ends up eventually in
one of the symfony/polyfill-* packages, all centralized in the
https://github.com/symfony/polyfill monorepo.

In my experience, this works quite well and I wouldn't require RFCs to ship
a polyfill: authors should be focused on the C implementation. The PHP
polyfill is not always trivial to achieve, and polyfills proposed in RFCs
don't necessarily end up being the ones shipped via symfony/polyfill, eg
because edge cases or perf improvements.
Polyfill needs a separate workflow.

Cheers,
Nicolas

سپهر محمودی

5 days ago

در تاریخ پنجشنبه ۲۷ اوت ۲۰۲۶، ۲۰:۰۲ Nicolas Grekas <
nicolas.grekas+php@gmail.com> نوشت:

> Hi  Sepehr
>
> ‪Le mar. 25 août 2026 à 13:21, ‫سپهر محمودی‬‎ <sepehrphpr@gmail.com> a
> écrit :‬
>
>> Hi internals,
>>
>> While reviewing various RFCs that introduce new functions, I noticed an
>> inconsistency: some authors include a userland polyfill (reference
>> implementation) in their RFCs, while others do not.
>>
>> I wanted to open a discussion on whether we should strongly encourage RFC
>> authors to provide a PHP userland implementation when proposing new
>> standard library functions, **where technically feasible**.
>>
>> Of course, I understand that this isn't possible for every new
>> function—especially those that interact with low-level OS APIs, memory
>> management, or internal engine features. However, for functions dealing
>> with arrays, strings, math, or general logic, I believe this has a couple
>> of major benefits:
>>
>> 1. It clarifies the exact intended behavior, including edge cases and
>> type coercions, making the proposal easier to understand without diving
>> into the C implementation.
>> 2. It immensely helps the community (e.g., the Symfony polyfill team) to
>> quickly and accurately port the function to older PHP versions once the RFC
>> is accepted.
>>
>> Should we consider adding this as a standard recommendation (e.g.,
>> "Reference Implementation") in the official RFC template for applicable
>> functions?
>>
>> I would love to hear your thoughts on this.
>>
>> Best regards,
>> Sepehr
>>
>>
>
> In case you didn't know, every polyfill-able feature ends up eventually in
> one of the symfony/polyfill-* packages, all centralized in the
> https://github.com/symfony/polyfill monorepo.
>
> In my experience, this works quite well and I wouldn't require RFCs to
> ship a polyfill: authors should be focused on the C implementation. The PHP
> polyfill is not always trivial to achieve, and polyfills proposed in RFCs
> don't necessarily end up being the ones shipped via symfony/polyfill, eg
> because edge cases or perf improvements.
> Polyfill needs a separate workflow.
>
> Cheers,
> Nicolas
>

-----

Thanks Nicolas, that makes total sense. I will focus entirely on the C
implementation.