[RFC] [Discussion] Followup Improvements for ext/uri

Hi Larry,

• Url::isSpecial() Could we come up with a better name here? "Special"

could mean anything unless you know the RFC; it feels like "real escape
string" all over again.

This comes from the WHATWG specification the isSpecial is how it is named
there

It really feels like there's an interface to extract here from the

Url/UriBuilder classes. There's literally only one type-specific method
(build()).

Yes but the return type is not always the same object (Uri and Url are
different so I would be incline not adding a useless interface they are
similar yet different)

There's a count() method, so shouldn't Ur{i|l]QueryParams implement

Countable?

I tend to agree Countable and IteratoAggregate should be implemented IMHO

• The fromArray() logic is... totally weird and unexpected and I hate it.

:-) Why can't you support repeated query parameters using nested arrays
rather than gumming up all calls with a wonky format?

I also do not like the fromArray there are 2 ways to represents query
parameters either you use the WHATWG spec in which case they are pairs or
you use PHP own algorithm (with it's own caveat and have something
resemble the result of parse_str which is destructive by essence. I would
prefer the named constructor to reflect that.

• The sort() method... should it take an optional user callback, or do we

lock people in to lexical ordering?

This is also derived from the WHATWG spec. Adding a callback might be
useful but it really then depends on how you represent each query
parameter/pairs.

• Why both Uri getRawQueryParams() and getQueryParams()? It looks like

they would return the same value, no? (If not, that should be explained.)

Because Uri\Rfc3986\Uri already exposes Uri::getQuery and Uri::getRawQuery.

• It would be quite convenient of set() and append() returned $this,

allowing them to be chained.

+1

I believe that the structure for the query string is the thing that will
need more explaining. Once it is correctly settled on the rest can easily
be derived from.
my 2 cents.

On Mon, Dec 1, 2025 at 11:22 PM Larry Garfield larry@garfieldtech.com
wrote:

Hi Everyone,

I'd like to introduce my latest RFC that I've been working on for a
while now: https://wiki.php.net/rfc/uri_followup.

It proposes 5 followup improvements for ext/uri in the following areas:

• URI Building
• Query Parameter Manipulation
• Accessing Path Segments as an Array
• Host Type Detection
• URI Type Detection
• Percent-Encoding and Decoding Support

I did my best to write an RFC that was at least as extensive as
https://wiki.php.net/rfc/url_parsing_api had become by the end. Despite
my efforts,
there are still a couple things which need a final decision, or which
need to be polished/improved. Some examples:

• How to support array/object values for constructing query strings?
  (https://wiki.php.net/rfc/uri_followup#type_support)
• How to make the UriQueryParams and UrlQueryParams classes more
  interoperable with the query string component (mainly with respect to
  percent-encoding)?
  (https://wiki.php.net/rfc/uri_followup#percent-encoding_and_decoding)
• Exactly how the advanced percent-decoding capabilities should work?
  Does it make sense to support all the possible modes
  (UriPercentEncodingMode) for percent-decoding as well
  (
  https://wiki.php.net/rfc/uri_followup#percent-encoding_and_decoding_support
  )
• etc.

Regards,
Máté

Thanks, Máté.

Notes as I read through:

• I really, really hate the "set" prefix on all the methods. It's a
  builder object, surely the "set" is implied?

$builder->scheme('https')->host('example.com')->path('/foo/bar')->build();

That's nice and easy to read.

• It really feels like there's an interface to extract here from the
  Url/UriBuilder classes. There's literally only one type-specific method
  (build()).

• UriQueryParams::hasWithValue(), could that be just hasValue()? You
  still need to specify the key anyway, and that's self-evident from the
  signature.

• There's a count() method, so shouldn't Ur{i|l]QueryParams implement
  Countable?

• As above, there really is an interface lurking in UriQueryParams...

• Why both Uri getRawQueryParams() and getQueryParams()? It looks like
  they would return the same value, no? (If not, that should be explained.)

• The sort() method... should it take an optional user callback, or do we
  lock people in to lexical ordering?

• It would be quite convenient of set() and append() returned $this,
  allowing them to be chained.

• The fromArray() logic is... totally weird and unexpected and I hate it.
  :-) Why can't you support repeated query parameters using nested arrays
  rather than gumming up all calls with a wonky format?

• It's not clear how one would start a new query from scratch, with the
  private constructor. There doesn't seem to be a justification for the
  private. I can't see why new UriQueryParams()->set('foo', 'bar') is a bad
  thing.

• Type support: Looks reasonable to me.

• The HostType logic seems reasonable to me.

• Url::isSpecial() Could we come up with a better name here? "Special"
  could mean anything unless you know the RFC; it feels like "real escape
  string" all over again.

Some parts of this are over my head as I've not read the relevant RFCs,
but overall I do like the direction.

--Larry Garfield

Hi Larry,

• I really, really hate the "set" prefix on all the methods. It's a

builder object, surely the "set" is implied?

I like that the "set" prefix makes all setters grouped together. For
example, should we have to add some extra methods (like authority()),
the build() method would appear between authority() and fragment() in IDE
autocomplete lists without the set() prefix.

• It really feels like there's an interface to extract here from the
  Url/UriBuilder classes. There's literally only one type-specific method
  (build()).

It's the very same thing that we discussed for a very long time last
time... What would be the purpose of the interface? To make the two builders
interchangeable? But they produce fundamentally different URIs. Even if we
don't include build(), then we still have some differences between
the two implementations:

• components are different: even though most components match, RFC 3986 and
  WHATWG URL still have a difference; notably, the userinfo
  component is only acknowledged by RFC 3986, on the other hand, the username
  and password components are only modifiable in case of WHATWG URL
• validation rules are different: each implementation has their own
  validation rules for each component. I'll need to clarify this in the RFC,
  but some purely
  syntax based validations should be performed during the setter/wither calls
  (e.g. scheme cannot contain "%"), but the ones which rely on the "global
  state" (e.g.
  the host is required when the userinfo is set) should be performed by the
  build() method in order to avoid the temporal coupling I mentioned in the
  RFC.

• UriQueryParams::hasWithValue(), could that be just hasValue()? You
  still need to specify the key anyway, and that's self-evident from the
  signature.

Yes, I was already considering updating this name, but I was sure that
someone (with 99% confidence of you) will point this out and suggest a
better one.
I agree that hasValue() is probably the right choice, although
hasNameAndValue() would be the most technically correct name...

• There's a count() method, so shouldn't Ur{i|l]QueryParams implement

Countable?

Yes, it can. I thought that implementing Countable on its own (without
IteratorAggregate) was less useful, so I omitted it. Ignace suggested
another approach that
would allow implementing IteratorAggregate: if it happens then I'm totally
fine with also implementing Countable.

• As above, there really is an interface lurking in UriQueryParams...

I have the same comment as for the builder with one small caveat: as far as
I know the implementations, the biggest differences between
UriQueryíParams and UrlQueryParams are how they parse the input, and how
they percent-encode them during recomposition. The rest is fairly similar
for
now at least.

I even had a brief moment when I thought that merging the two
implementations into one is a good idea, but I came to the conclusion that
it isn't so that the two
classes have the possibility to evolve separately, if needed. So I'd follow
the path of the original URI/URL debate and would not try to make the two
implementations
interoperable. They are only interoperable on the surface. :)

• Why both Uri getRawQueryParams() and getQueryParams()? It looks like
  they would return the same value, no? (If not, that should be explained.)

This is actually already briefly explained in the RFC (but thanks to Ignace
how also described this part):

The difference between Uri\Rfc3986\Uri::getRawQueryParams() and

Uri\Rfc3986\Uri::getQueryParams() is that the former one passes the “raw”
(non-normalized)

query string as an input when instantiating Uri\Rfc3986\Uri\UriQueryParams.

• The sort() method... should it take an optional user callback, or do we
  lock people in to lexical ordering?

Only WHATWG URL specifies its behavior, and it uses basic alphanumeric
sorting. Even though there's nothing that could stop us from implementing
fancier
sorting ways, I think it's already fine as-is. Sort() can be used to
guarantee that the query components are in deterministic order, and I think
that's all that we need.

• It would be quite convenient of set() and append() returned $this,
  allowing them to be chained.

That's fine for me. WHATWG URL specifies their return type as void, so I
went with this, but there's nothing wrong with returning $this.

• The fromArray() logic is... totally weird and unexpected and I hate it.
  :-) Why can't you support repeated query parameters using nested arrays
  rather than

gumming up all calls with a wonky format?

Do you mean something like ["foo" => [0, 1, 2, 3]])"? I think it is indeed
possible to implement what you suggested. Whenever the basic structure of
the proposal settles a little bit,
I'll update the implementation, and I'll try to find out a sensible
behavior for arrays/objects.

• It's not clear how one would start a new query from scratch, with the

private constructor. There doesn't seem to be a justification for the
private.

I can't see why new UriQueryParams()->set('foo', 'bar') is a bad thing.

Yes, starting from scratch is only possible by using
UriQueryParams::fromArray([]) or UriQueryParams::parse(""). But I don't
have any fundamental issue with
adding support for the empty constructor variant.

• Url::isSpecial() Could we come up with a better name here? "Special"
  could mean anything unless you know the RFC; it feels like "real escape
  string" all over again.

The "special URL" is indeed the technicus terminus that WHATWG URL uses.
The RFC explains the concept briefly:

The WHATWG URL specification defines some special schemes (http, https,

ftp, file, ws, wss), which have distinct parsing and serialization rules.

I don't have any issues with the current name, but the only alternative I
could imagine is Uri\WhatWg\Url::isSpecialScheme().

Regards,
Máté

Hi Ignace,

After quickly checking the proposed API for Percent-Encoding and Decoding

Support I wonder if the following would not
be more appropriate ?

namespace Uri\Rfc3986 {
    enum UriPercentEncoding
    {
        case UserInfo;
        case Host;
        case RelativeReferencePath;
        case RelativeReferenceFirstPathSegment;
        case Path;
        case PathSegment;
        case Query;
        case FormQuery;
        case Fragment;
        case AllReservedCharacters;
        case All;

        public function encode(string $input): string {}
        public function decode(string $input): string {}
    }
}

With the same logic being applied in the Uri\Whatwg namespace. This would make for a better encapsulated feature. So we can

have a clear distinction between the Value Object, its builder and the Encoding mechanism ? What do you think?

Yes, I was also wondering whether the URI/URL classes are really the best
places for the percentEncode() and percentDecode() methods, because
they are not only relevant for URIs/URLs but e.g. also for QueryParams.. So
overall, I'm also fine with moving the percent-encoding/decoding
capabilities to a separate place. Honestly, the enums themselves didn't
come to my mind... I think it's a good candidate. So I'll definitely
consider it.

Probably my only concern is the name, specifically, the "ing" suffix: it
suggests that it can only keep data, and cannot do any operation. The
latter would
rather have an "er" suffix (e.g. UriPercentEncoder). But I'm happy to get
feedback/suggestions about the options.

Máté

Hi Ignace,

The getter methods return null if the path is empty (https://example.com),
an empty array when the path
consists of a single slash (https://example.com/), and a non-empty
array otherwise.

Yes, that's correct!

Instead, I would rather always get a single type, the array as return
value. The issue you are facing is that
you want to convey via your return type if the path is absolute or not.
But, we already have access to this
information via the UriType Enum, at least in the case of the
Uri\Rfc3986\Uri class.

The UriType enum in its current form is not really suitable, because it can
only distinguish relative and absolute
path references ("foo" vs "/foo"), but not absolute URIs ("
https://example.com" vs "https://example.com/").
"https://example.com" and "https://example.com/"; are both absolute URIs,
and the former one has an empty path.

In order to find out the correct behavior, I think we should first try to
dig deeper into the definition of path segments.

Also, in order to have some inspiration, I checked how similar
functionality works in other languages, C# notably:
https://learn.microsoft.com/en-us/dotnet/api/system.uri.segments?view=net-10.0#system-uri-segments
Making the leading "/" its own segment feels a little bit off at the first
sight (not to mention that the "/" characters
are part of the segments), because RFC 3986 specifies that path segments
start after the leading "/" due to the
following ABNF rule:

path-abempty = *( "/" segment )

That is, for URIs containing an authority component, the path is either
empty, or contains a "/" followed by a segment
one or multiple times. Then segments have the following syntax:

segment = *pchar

That is, segments are composed of zero or multiple characters in the
"pchar" charset (the exact values don't matter
in this case). So let's see some basic examples with absolute URIs:

"https://example.com" -> no path segments: []
"https://example.com/foo"; -> one path segment "foo": ["foo"]

Consequently:

"https://example.com/"; -> one path segment which is empty: [""]
"https://example.com/foo/"; -> two path segments: ["foo", ""]

Then the behavior of C# starts to make some sense - at least when the path
only consists of a "/" character (IMO it
doesn't make sense for other cases like "/foo").

Now let's see what to do with path references:

"" (empty string) -> no path segments: []
"/foo" -> one path segment "foo": ["foo"]
"foo" -> one path segment "foo": ["foo"]
"foo/" -> two path segments: ["foo", ""]
"/" -> one path segment which is empty: [""]

Unfortunately, this is not all, there are a few other special cases for
absolute URIs:

"https://" -> means that there's an authority, but it's empty, therefore
the path is also empty, therefore no path segments -> []
"https:/" -> means that there's no authority, and the path is "/",
therefore one path segment which is empty -> [""]
"https:" -> means that there's no authority, and the path is "", therefore
no path segments -> []

As far as I can see, this behavior is completely logical and satisfies the
definitions of RFC 3986. However, one case
may possibly need disambiguation in relation to the withPathSegments()
method: "/foo" vs "foo". (P.S. the uriparser library
had to use a special field for tracking exactly these cases.)

That being said, I agree with you that the currently suggested signatures
should be changed. However, accepting an
additional UriType parameter by the withPathSegments() method wouldn't be
correct, because I've just demonstrated
that the behavior doesn't depend on whether an URI is absolute or relative,
but whether the authority component is
defined or not.

So my alternative idea for disambiguating the above mentioned case is the
following: adding a 2nd parameter
$addLeadingSlashForNonEmptyRelativeUri to the withPathSegments() method (I
know this param name is insanely long,
so I'm happy to get recommendations), and then a leading slash would be
added to the path if and only if all the 3
criteria are satisfied:

• the $addLeadingSlashForNonEmptyRelativeUri boolean parameter is true
• the first item in the $pathSegments array parameter is non-empty
• the target URI is relative

This means that calling $uri->withPathSegments(["", "foo"], false) and
$uri->withPathSegments(["foo"], true) would result
in the same path reference ("/foo") when $uri doesn't have an authority.
I'm fine with bikeshedding/fine-tuning these rules,
but I do think we should go with something along the lines of this.

For the Uri\WhatWg\Uri the information is less crucial as the validation

and normalization rules of the WHATWG

specifications will autocorrect the path if needed.

Yes, true.

Máté

Hi,

1. Query setters and types of their parameter. Quote from the builder
   example:

    ->setQuery*(*"a=1&b=2"*])*

    ->setQueryParams*([*"a" => 1, "b" => 2*])* *// Has the same effect as
the setQuery() call above*

I’d expect the setQueryParams to set the particular params that I
specified instead of overriding all the query (which I’d expect setQuery
to do).

I'm happy that you raised this concern because I wouldn't ever have thought
the behavior was unclear. My expectation with setters is that they
completely override the related property.
If they were intended to add/append the query params then something like
addQueryParams() should be used instead. And I think this question has just
highlighted why
it's a bad idea to remove the set prefix from the Builder methods: because
it would also remove some additional context about what the method exactly
does (which is
apparently not even entirely clear with the set prefix included, but
without the set prefix, one would have zero clue if it's an append or set
operation).

Maybe it would be possible for setQuery to accept string, array and
instances of *QueryParams? And setQueryParams could either be left out
or override just the selected params? As far as I see, there is no
equivalent withQueryParams so there’s no precedent on how such a method
should work, right?

Good call, I've already updated the RFC so that setQueryParams() accepts a
UriQueryParams/UrlQueryParams instance. It was just an oversight on my part.
But I don't really like to use union types (mainly because the method
behavior needs extra explanation), that's why I chose to add two
distinct methods for the query handling.

Btw I wasn’t able to find docs on the existing Uri classes (had to look it
up in the prev RFC). Is the search broken or are the docs just not there
yet?

Yes, unfortunately, the docs are not there yet :( I usually prioritize my
work in favor of php-src, and since I apparently chose a massive
undertaking yet again, I have very limited time
for anything else. But I'll try to find time to add the missing stuff to
the documentation.

2. Regarding the interface extraction, is there any difference between the
   internal states of Uri\WhatWg\UrlQueryParams and
   Uri\Rfc3986\UriQueryParams objects? I would naively expect not only a
   common interface, but a common class. A QueryParams that could be
   supplied to any of the withers/setters and that would be able to
   ->toRfc3986QueryString() or ->toWhatWgQueryString() on use not on
   instantiation.

I have already been thinking a lot about this question for a while, and I
agree that the two QueryParams implementations are very similar: the only
difference between them is how
they parse the query string into query params and how they recompose the
query params to a query string. So I would be happy to be able to unify the
two implementations, that would be a huge
simplification. However, there are two reasons why I'm very hesitant to do
so:

• We should be absolutely sure that an unified implementation cannot cause
  parsing confusion vulnerability. E.g. when the query params are parsed
  according to one specification, and then
  they are recomposed according to the other one. For example, one difference
  (this is also mentioned in the RFC) is that WHATWG URL removes the leading
  "?" character during parsing,
  while RFC 3986 leaves it as-is. These differences must be considered very
  carefully.
• If we have two dedicated classes, then they can evolve separately with
  specification-specific behavior. If it turns out that we want to add
  support for some specification-specific feature, then
  a specification-specific class is better suited for the purpose. I can't
  really come up with many examples, but maybe additional percent-encoding
  capabilities could be needed (e.g. getFirstPercentEncoded()).

Similarly with the builders I fail to see why do I need to decide on
Uri\Rfc3986\UriBuilder and Uri\WhatWg\UrlBuilder at the start instead
of having Uri\Builder that could be consumed via ->buildRfc3986Url() or
`->buildWhatWgUri(). Is that UserInfo thing the whole dealbreaker? To me
all the other parts like specifying host, port and so on seem spec-agnostic
until serialization.

Yes, the userinfo is just one of the deal breakers. Not too long ago, I
modified the RFC text, and added more info about how validation exactly
works. According to my plans,
the individual setters would also make some basic validation (formatting of
the component), while the build() methods would make sure that some global
rules are also satisfied
(there's a bit more info in the RFC about this). And this is only possible
to implement if there are two different builders.

Máté

Hi Ignace,

Currently, in your proposal you have 2 Query objects. This will give
the developper a lot of work to understand where, when and which
object to choose and why. Is that complexity really needed? IMHO we
may end up with a correct API ... that no-one will use.

Just to reiterate what I wrote to Juris a few days ago: I'm open to
unifying the two classes, but I'm just hesitant because of security and
evolvability reasons (but the main one is security).

With all that in mind I believe a single Uri\Query should be used.
Its goal should be:

• to be immutable
• to store the query in its decoded form.
• to manipulate and change the data in a consistent way.

So far, I imagined the two QueryParams classes to be mutable because one of
their main goals is to be able to build (~ mutate) query param list...
But otherwise an immutable implementation would be useful for sure.

Decoding/encoding should happen at the object boundaries but
everything inside the object should

be done on decoded data.

Yes, that's what I also had to find out based on my experience with
implementing the POC, so I completely agree here.

On a bonus side, it would be nice to have a mechanism in PHP that
allows the application to switch

from the current parse_str usage to the new improved parsing provided by the new class when
populating the _GET array. (So that deprecating parse_str can be initiated in some distant future.)
This last observation/remark is not mandatory but nice to have.

This is a very interesting remark, and I have not thought about this
possibility yet. Generally, I agree with
the idea, but my long-term goal (or wish) is to move away from using $_GET
and $_POST to access request
data in favor of using objects... So I most probably won't deal with trying
to implement this idea. However,
I'm willing to add a UriQueryParams::fromCurrentQueryString(), maybe even a
UriQueryParams::fromCurrentBody()
or similar factory methods if people like it.

• in respect to parse_str, no mangled data should occur on parsing:

Uh, I completely forgot about this behavior of parse_str(), and I
definitely agree that mangling shouldn't happen.

• Only accept scalar values, null, and array. If an object or a
  resource is detected a ValueError error

should be thrown.

I wasn't sure what to do with objects, but I'm happy to skip their
support, especially if they would cause issues.
The rest of the suggestions align with my initial plans (maybe with the
exception of throwing ValueError -- I wrote
TypeError in the related section).

• Remove the addition of indices if the array is a list.

Yes, this also aligns with my initial plans.

Best regards,
Máté

Hi Derick,

Would it make sense to have an interface for the set*() methods? Besides
build(), they all seem to have the same API.

I've just answered this to Juris, but TLDR: IMO it is not possible if we go
with the currently suggested behavior.
The set*() method pairs would have completely different validation rules
based on the specification they implement.

• Query Parameter Manipulation

I see this adds NoDiscard:
#[\NoDiscard(message: "as Uri\Rfc3986\Uri::withQueryParams() does not
modify the object itself")]

But the original methods on the classes don't have these NoDiscards, and
it doesn't seem that this RFC is suggesting to add them. It should at
least be consistent.

Thanks for noticing these; I wanted to add #[NoDiscard] to Uri/Url wither
methods just before the final PHP 8.5 release,
but it was a bit controversial, so I didn't do it at last. Then I thought
that at least the newly proposed methods could
have it, that's why I included these attributes into this RFC. But now I
realized that I'm not ready to fight for them,
so I've just removed them all from the proposal.

• Accessing Path Segments as an Array

Compare:

"especially considering the fact that Uri\Rfc3986\Uri internally stores
the path as a list of segments."

And:

Uri\Rfc3986\Uri::withPathSegments() … internally concatenate the input
segments separated by a / character, and then trigger
Uri\Rfc3986\Uri::withPath() …

Why does it need to do this concattenation, and then call withPath() for
Rfc3986\Uri then?

The path setter of the uriparser library (uriSetPathMmA) takes a string
first,
then reparses it as an URI (setters for the other components work much
simpler),
and finally, does a few other checks/modifications. If everything went well,
the path is stored as a list of segments indeed. That's why concatenating
the
segments is needed, otherwise validation wouldn't work properly.

Cheers,
Máté