[RFC] [Discussion] Add WHATWG compliant URL parsing API

> > > > On 29 Jun 2024, at 04:48, Niels Dossche <dossche.niels@gmail.com> wrote: > > > > - It's a bit of a shame that the PSR interface treats queries as strings. > > In Javascript we have the URLSearchParams class that we can use as a key-value storage for query parameters. > > This Javascript class also handles escaping them nicely. > > Agreed this is a weird choice to me, but I'm also not surprised by weird choices via > php-fig (log level constants I'm looking at you) > > We hear all the time how userland is more flexible and can change quicker - and yet here we see a potential built in class having a worse api because it wants to be compatible with an existing userland interface with the same bad api.... > > Cheers > > Stephen

> > >> On 29 Jun 2024, at 04:48, Niels Dossche <dossche.niels@gmail.com> wrote: >> >> - It's a bit of a shame that the PSR interface treats queries as strings. >> In Javascript we have the URLSearchParams class that we can use as a key-value storage for query parameters. >> This Javascript class also handles escaping them nicely. > > Agreed this is a weird choice to me, but I'm also not surprised by weird choices via > php-fig (log level constants I'm looking at you) > > We hear all the time how userland is more flexible and can change quicker - and yet here we see a potential built in class having a worse api because it wants to be compatible with an existing userland interface with the same bad api.... > > Cheers > > Stephen

> Hi all, > > In earlier discussions on the Server-Side Request and Response objects RFC and the after-action sumamry, one of the common non-technical objections was that it would better be handled in userland. > > Seeing as there are at least two other WHATWG-URL projects in userland now ... > > - https://packagist.org/packages/rowbot/url > - https://packagist.org/packages/esperecyan/url > > ... does the same objection continue to hold?

> In earlier discussions on the [Server-Side Request and Response > objects](https://externals.io/message/108436) RFC and the [after-action > sumamry](https://externals.io/message/109563), one of the common > non-technical objections was that it would better be handled in > userland.

> My take on that is more that functionality in core needs to be > «perfect», or at least near unanimous.

> The type of functionality that is nowadays added to PHP’s standard > library is “building block” functionality: Functions that a userland > developer would commonly need in their custom library or application.

> The same is true for `UriOperationException`. The RFC says that it can > happen for memory issues. Can this actually happen? My understanding is > that the engine bails out when an allocation fails. In any case if a > more graceful handling is desired it should be some generic > `OutOfMemoryError` rather than an extension-specific exception. >

> > With regard to unserialization, let me refer to: > https://externals.io/message/118311. ext/random uses `\Exception` and I > suggest ext/uri to do the same. This should also be handled in a > consistent way across extensions, e.g. by reproposing > https://wiki.php.net/rfc/improve_unserialize_error_handling. >

> > And with “Theoretically, URI component reading may also trigger this > exception” being a theoretical issue only, the `UriOperationException` > is not actually necessary at all. >

> I'm sure that people will find their use-cases to subclass all these > new classes, including the WHATWG implementation. As Nicolas mentioned, > his main use-case is minly adding convenience and new factory methods > that don't specifically need all methods to be reimplemented. > > While I share your opinion that leaving the URI classes open for > extension is somewhat risky and it's difficult to assess its impacts > right now, I can also > sympathise with what Nicolas wrote in a later message > (https://externals.io/message/123997#126489): that we shouldn't close > the door for the public from > using interchangeable implementations. > > I know that going final without any interfaces is the most "convenient" > for the PHP project itself, because the solution has much less BC > surface to maintain, > so we are relatively free and safe to make future changes. This is > useful for an API in its early days that is huge like this. Besides the > interests of the maintainers, > we should also take two important things into account: > > - Heterogeneous use-cases: it's out of question that the current API > won't fit all use-cases, especially because we have already identified > some followup tasks > that should be implemented (see "Future Scope" section in the RFC). > - Interoperability: Since URI handling is a very widespread problem, > many people and libraries will start to use the new extension once it's > available. But because > of the above reason, many of them want to use their own abstraction, > and that's exactly why a common ground is needed: there's simply not a > single right possible > implementation - everyone has their own, given the complexity of the > topic. > > So we should try to be considerate about these factors by some way or > another. So far, we have four options: > > - Making the classes open for extension: this solution has acknowledged > technical challenges > (https://github.com/php/php-src/pull/14461#discussion_r1847316607), > and it limits our possibilities of adding changes the most, but users > can effectively add any behavior that they need. Of course, they are > free to introduce bugs and > spec-incompatible behavior into their own implementation, but none of > the other solutions could prevent such bugs either, since people will > write their custom code > wherever they can: if they can't have it in a child class, then they > will have in MyUri, or in UriHelper, or just in a 200 lines long > function. > > Being able to extend the built-in classes also means that child classes > can use the behavior of their parent by default - there's no need to > create wrapper > classes around the built-in ones (aka using composition), that is a > tedious task to implement, and also which would incur some performance > penalty because of the > extra method calls. > > - Making the classes open for extension, but making some methods final: > same benefits as above, without the said technical challenges - in > theory. I am currently > trying to figure out if there is a combination of methods that could be > made final so that the known challenges become impossible to be > triggered - although I haven't > managed to come up with a sensible solution yet. > > - Making the classes final: It avoids some edge-cases for the built-in > classes (the uninitialized state most prominently), while it leaves the > most room for making future > changes. Projects that may want to ship their own abstractions for the > two built-in classes can use composition to create their own URI > implementations. > They can instantiate these implementations however they want to (i.e. > $myUri = new MyUri($uri)). If they need to pass an URI to other > libraries then they could extract > the wrapped built-in class (i.e. $myUri->getUri()). > > On the flipside, backporting methods added in future PHP versions (aka > polyfills) will become impossible to implement for URIs according to my > knowledge, as well as mocking > in PHPUnit will also be a lost feature (I'm not sure if it's a good or > a bad thing, but it may be worth to point out). > > Also, the current built-in implementations may have alternative > implementations that couldn't be used instead of them. For example, the > ADA URL library (which is mentioned > in the RFC) also implements the WHATWG specification - possibly the > very same way as Lexbor, the currently used library - does. These > alternative implementations may have > different performance characteristics, platform requirements, or level > of maintenance/support, which may qualify them as more suitable for > some use-cases than what the built-in > ones can offer. If we make these classes final, there's no way to use > alternative implementations as a replacement for the default ones, > although they all implement the same > specification having mostly clear semantics. > > - Making the classes final, but adding a separate interface for each: > The impact of making the built-in classes final would be mitigated by > adding one interface > for each specification (I didn't like this idea in the past, but it now > looks much more useful in the perspective of the final vs non-final > debate). Because of the interfaces, > there would be a common denominator for the different possible > implementations. I'm sure that someone would suggest that the community > (aka PHP-FIG) > should come up with such an interface, but I think we shouldn't expect > someone else to do the work when *we* are in the position to do it the > best, as those interfaces > should be internal ones, since the built-in URI classes should also > implement them. > > If we had these interfaces, projects could use whatever abstraction > they want via composition, but they could more conveniently pass around > the same object everywhere. > > I intentionally don't try to draw a conclusion for now, first of all > because it already took me a lot of time to try to mostly objectively > compare the different possibilities, and > I hope that we can find more pros-cons (or fix my reasonings if I made > mistakes somewhere) in order to finally reach some kind of consensus.

> Hi Maté and all, > > > On May 5, 2025, at 16:36, Máté Kocsis kocsismate90@gmail.com wrote: > > > > Hello Internals, > > > > After more than a hundred emails refining even the tiniest details, we have reached a point where I'd like to call for a vote. > > I know that the new API still doesn't support many use-cases, it still has missing pieces, but now it includes a cohesive set > > of functionality that could be a very useful basic building block for most people. > > > > That said, I don't intend to change anything about the RFC anymore, unless there's still some factual error in it. There are a lot of > > possibilities how such a large API can look like, and this RFC approaches the problem the way it is currently described, > > and not in any other way. > > > > So unless some very serious issues arise, I'm going to start the vote on 8th May, possibly in the morning (according to UTC). > > > I am on record as wanting very much to see some decent web-centric objects in core PHP (Request, Response, Uri/Url, etc). > > To my chagrin, despite the fact that its goals are laudable, I do not think this RFC is in a ready state to provide such objects. > [...] > > -- pmj

> - is too broad in scope;

> - acknowledges it is incomplete, with work left undone;

> - admits to standards non-compliance; and,

> - has an uncertain API.