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

Hi Màté, As always I tried to implement a polyfill for the Percent-Encoding and Decoding Support RFC. Turns out while doing so I was able to refactor the enum. Of note, the case names are the one used in the text and *NOT* in the Enum example provided as they differ. I will update the names once you have updated them. Here's my alternate proposal for Uri\Rfc3986. Keep in mind that the same reasoning would apply for the Uri\Whatwg counterpart. namespace Uri\Rfc3986 { enum UriComponent { case UserInfo; case Host; case Path; case PathSegment; case AbsolutePathReferenceFirstSegment; case RelativePathReferenceFirstSegment; case Query; case FormQuery; case Fragment; case AllReservedCharacters; case AllButUnreservedCharacters; /** * @throws InvalidUriException */ public function encode(string $input): string; /** * @throws InvalidUriException */ public function decode(string $input): string; } } As previously stated, I added the encode/decode method in the Enum this way the feature is fully handled by the Enum and no direct reference to the Uri class via a static method is done. The Enum is renamed *UriComponent* instead of the current *UriPercentEncodingMode *the name change highlights the intent of the Enum encoding and decoding URI component, where each enum case represents a defined component context. Both methods may trigger an exception (I do not know if specific exceptions like UnableToEncodeException and/or UnableToDecodeException should be added but, for now, the generic InvalidUriException is used. This rewrite also greatly simplifies the Enum usage. Below you will see your examples from the RFC rewritten - Decoding the fragment $uri = new Uri\Rfc3986\Uri("https://example.com#_%40%2F"); $fragment = $uri->getFragment(); // returns "_%40%2F" echo Uri\Rfc3986\UriComponent::Fragment->decode($fragment); //returns "_%40/" - Decoding the query //with the query component $uri = new Uri\Rfc3986\Uri("https://example.com/?q=%3A%29"); $query = $uri->getQuery(); // returns "q=%3A%29" echo Uri\Rfc3986\UriComponent::Query->decode($query); //returns "q=:)" - Usage with the new Uri::withPathSegments method $uri = new Uri\Rfc3986\Uri("https://example.com"); $uri = $uri->withPathSegments([ "foo", Uri\Rfc3986\UriComponent::PathSegment->decode("bar/baz") ]); $uri->toRawString(); // https://example.com/foo/bar%2Fbaz Let me know what you think, regards, Ignace On Tue, Mar 3, 2026 at 10:24 AM ignace nyamagana butera <nyamsprod@gmail.com> wrote: > Hi Máté, > > I just re-read the RFC and I like the updates and precision you've brought > to it here's my review: > For the builders I have nothing more design wise to add this is already > solid. I may nitpick on the *Builder::clear() method name I would have gone > with *Builder::reset() but I presume other developers would go with clear.. > Other than that the public API is spot on. > > For the Enum, my only concern is that they serve just as flags and their > usage is tightly coupled to the Uri classes. I would add 2 static named > constructors fromUrl and tryFromUrl just for completeness. I believe the > maintenance cost is negligible but the developer DX is improved and allows > for a broader usage of the Enum. > > In regards to the path segments usage and constructor I see you already > integrate my Enum suggestions and you have explained why a fully > fledged class is not the right approach. So the current design is already > solid. > > Last but not least, The Percent encoding feature should be IMHO improved > by moving the encode/decode methods from being static methods on the URI > classes to becoming public API on the Enum. This would indeed imply > renaming the enum from Uri\Rfc3986\UriPercentEncodingMode to > Uri\Rfc3986\UriPercentEncoder with two methods encode/decode. Again it > makes for a more self-contained feature and adds to the DX. Developer will > not have to always statically call the URI classes for encoding/decoding > strings as the Enums and their cases already convey the information > correctly. > > Overall I believe this is going into the right direction > > Regards, > Ignace > > > On Sun, Mar 1, 2026 at 11:09 PM Máté Kocsis <kocsismate90@gmail.com> > wrote: > >> Hey Ignace et al, >> >> I have updated the RFC in the past few weeks with a lot of extra info, >> mostly related to path segment handling: I investigated WHATWG URL's >> behavior more thoroughly, and it turned out that path segments are >> handled very interestingly, so there was a significant difference compared >> to RFC 3986 yet again. >> >> Please give the RFC another read, if possible. >> >> Regards, >> Máté >> >>