[PHP-DEV] [RFC] [Discussion] Followup Improvements for ext/uri

[Mate_Kocsis]

Hi Ignace, Tim et al.,

I’ve finished updating the RFC once again, after some private discussion with Tim:

It turned out that the percent-decoding feature as proposed would have led to confusing behavior
in some cases. In order to avoid this, I ultimately removed the percent-decoding support from the
proposal. In the same time, I pivoted from the "instance methods on an enum” based approach
to a simple namespaced function based solution, because the enums would only ever have a single
method (even if decoding support is added later, possibly not all the (Uri|Url)PercentEncoder enum cases
would be applicable for decoding). Let me know if this doesn’t work for you, TBH adding namespaced
functions was my least favorite solution, but I didn’t have any significantly better idea which would have had
the potential to gain traction.

I have called out one example in the RFC (https://wiki.php.net/rfc/uri_followup#percent-encoding_support) which
would be problematic if we had a Uri\Rfc3986\uri_percent_decode() function, so let me copy-paste it here for reference:

$uri = new Uri\Rfc3986\Uri(“https://example.com/?a=b%26c”); // The query is the percent-encoded form of “a=b&c=d”

echo Uri\Rfc3986\uri_percent_decode(
$uri->getQuery(),
Uri\Rfc3986\UriPercentEncodingMode::Query
); // a=b&c

The result is probably not what we expected, because percent-decoding changed the meaning of the query component:

• Originally, the query contained a parameter “a” with value “b%26c” (“b&c”)
• Now, there is a parameter “a” with value “b”, as well as a parameter “c” without value

And I’m now attempting once again to announce my intention to start the vote:
If no significant issue comes up this time, then I’ll start the vote next Tuesday evening (according to UTC).

Regards,
Máté

[nyamsprod_the_funky]

Hi Máté and all,

I have no issue with the usage of namespaced functions, on the contrary I think that they do give a better understanding of the intended API usage.
It is a self contained feature which is fully decoupled from the main URI classes with 0 side-effects.

My main goal has always been to provide a better UX over having static methods on the main URI classes.

As you pointed out, adding percent-decoding in a later stage seems reasonable to me, if we can find a way in the meantime to remove the mis-usage
or mis-understanding you highlighted then at that point adding a new function will then be a no-brainer. So there will be no pushed back from my part around
this change.

In the meantime, I have already updated my polyfill to be inline with your last changes. As I said earlier, the fact that the introduced Enums can not be instantiated
from an URI makes their presence in the polyfill required but incomplete as they can not be used before PHP8.6 since the URI classes are final and no named
constructors can be attached to them to allow their instantiation from an actual URI instance.

see https://github.com/thephpleague/uri-src/pull/170/changes

Looking forward to your call for voting and its outcome.

Regards,
Ignace

On Thu, Apr 30, 2026 at 9:19 PM Máté Kocsis <kocsismate90@gmail.com> wrote:

Hi Ignace, Tim et al.,

I’ve finished updating the RFC once again, after some private discussion with Tim:

It turned out that the percent-decoding feature as proposed would have led to confusing behavior
in some cases. In order to avoid this, I ultimately removed the percent-decoding support from the
proposal. In the same time, I pivoted from the "instance methods on an enum” based approach
to a simple namespaced function based solution, because the enums would only ever have a single
method (even if decoding support is added later, possibly not all the (Uri|Url)PercentEncoder enum cases
would be applicable for decoding). Let me know if this doesn’t work for you, TBH adding namespaced
functions was my least favorite solution, but I didn’t have any significantly better idea which would have had
the potential to gain traction.

I have called out one example in the RFC (https://wiki.php.net/rfc/uri_followup#percent-encoding_support) which
would be problematic if we had a Uri\Rfc3986\uri_percent_decode() function, so let me copy-paste it here for reference:

$uri = new Uri\Rfc3986\Uri(“https://example.com/?a=b%26c”); // The query is the percent-encoded form of “a=b&c=d”

echo Uri\Rfc3986\uri_percent_decode(
$uri->getQuery(),
Uri\Rfc3986\UriPercentEncodingMode::Query
); // a=b&c

The result is probably not what we expected, because percent-decoding changed the meaning of the query component:

• Originally, the query contained a parameter “a” with value “b%26c” (“b&c”)
• Now, there is a parameter “a” with value “b”, as well as a parameter “c” without value

And I’m now attempting once again to announce my intention to start the vote:
If no significant issue comes up this time, then I’ll start the vote next Tuesday evening (according to UTC).

Regards,
Máté