Description
Feature Request
Q | A |
---|---|
Package | no |
New Feature | no |
BC Break | yes/no |
Introduction
League uri packages are made up of three (3) packages:
uri-interfaces
: contains contracts and utility classes to perform primitive process around URIuri
: contains concrete classes to handle complete URI and URI templates and depends onuri-interfaces
uri-components
: contains concrete classes to handle URI components and depends onuri
.
Having the contracts being defined on uri-interfaces
makes the dependency a bit too complex to decouple. For instance the uri
package does not depend nor does it requires uri-components
interfaces. Having those interface being loaded when requiring the uri
package make little sense.
Using the same argument the uri
package does not require the PSR-7
interfaces. The package provides a PSR-7 UriInterface
implementation. But that implementation is optional and is not a requirement for the package to work. So putting the PSR-7
and PSR-17
requirements in the suggest
section of the composer file seems reasonable. If compatibility with PSR
interfaces is a requirement explicitly requiring the extra package is a better option. It makes the dependency clearer and cleaner from a developer POV. The goal of this feature is to
- reduce the dependency tree
- makes it more clearer the goal of each separate packages.
We have two proposals:
Proposal 1:
- We remove all interfaces from the
uri-interfaces
packages which will only contains utility classes. - We move all the interfaces related to URI processing in the
uri
package. - We make the PSR-7/PSR-17 interfaces optional for the
uri
package. - We move all the interfaces related to URI component processing in the
uri-component
package. - We make the PSR-7/PSR-17 interfaces optional for the
uri-component
package.
The consequences:
- Introduce a BC to the
uri-interfaces
which will be bumped to v8. uri
dependencies stays as isuri-components
dependencies stays as isuri
anduri-components
will only be bump to a minor version v7.5.
Issues/Open questions:
- The current subsplit tool used in
uri-src
is unable to handle 2 major versions release at the same time. - The
UriAccess
interface uses the PSR-7UriInterface
in a union type for a return type. Is that affected by having PSR-7 classes optional inside theuri-package
?
Proposal 2:
- We create a new package
uri-helpers
which will only contains utility classes. - We move all the interfaces related to URI processing in the
uri
package. - We make the PSR-7/PSR-17 interfaces optional for the
uri
package. - We move all the interfaces related to URI component processing in the
uri-component
package. - We make the PSR-7/PSR-17 interfaces optional for the
uri-component
package.
The consequences:
uri
will now depend only onuri-helpers
uri-components
dependencies stays as is- the
uri-interfaces
package is deprecated (ie does not receive any updated and will still be requested and installed when using older version of uri version. - all packages are bumps to
7.5
(includinguri-helpers
)
Issues/Open questions:
- Should we remove from the monorepo
uri-interfaces
to be sure it has been deprecated and no longer received automatic update. We still need to keep it in line in case of security issue with the newuri-helpers
package. - Since we changed dependencies for
uri
in between version can this be considered as BC break for theuri
package or not ?
According to this issue it does not: Version after dependency changes? semver/semver#148 - The
UriAccess
interface uses the PSR-7UriInterface
in a union type for a return type. Is that affected by having PSR-7 classes optional inside theuri-package
? uri-helpers
will conflict withuri-interfaces
normally the conflict should be minimal on updateuri-interfaces
package should be replaced byuri-helpers
. A conflict can only arise if someone did require only theuri-interfaces
and then later on requires a version higher than 7.4 of any other package. But this can be solve by either removinguri-interfaces
or by installinguri-components
.
Future scope
Once the Interfaces have been moved to their appropriate package we should question their utilities
and if they should be removed/replace/split or if we should add more. Those changes should be examined in a context of a major BC break and for inclusion in the next major release for the library.
Activity
nyamsprod commentedon Jun 3, 2024
@wouterj @kelunik @shadowhand For context the packages were mentioned in regards to a PR in Symfony to include a new URI component. One of the blocker was the PSR-7 dependency of all the packages. IMHO this dependency is important but not crucial for the package to work. Hence I put together the following proposal. Your thoughts, remarks, suggestions are welcomed.
These are ideas no definitive solutions. The goal is to improve the situation without adding more headache to users of the packages.
Of note: regardless of Symfony decision I still believe this is still something we need to address whether the solution lands now or when developing the next major release whichever comes first.
shadowhand commentedon Jun 3, 2024
This is a pretty amazing opportunity to contribute years of work and knowledge to a foundational part of the PHP ecosystem, congrats!
My perfect solution for this situation would be:
For what it is worth, I think the current repository split is confusing and makes it harder to contribute to this package. I worry about trying to do too many things in one place, as opposed to a core package with dependents.
wouterj commentedon Jun 3, 2024
This is purely my personal opinion, but keeping
league/uri
in the PHP league organization and Symfony using it instead of creatingsymfony/uri
is a valid option as well (which is what we're currently discussing in Symfony).Does that change your perfection solution? (i.e. does that still make donating the package to Symfony the ideal scenario?)
shadowhand commentedon Jun 3, 2024
@wouterj yes, I still think donating the whole package is the ideal scenario.
nyamsprod commentedon Jun 9, 2024
@shadowhand before donating something one has to wonder what is the endgoal for Symfony. At the moment the developers from Symfony are not clear in their own intention and I still reserved the right to not donate the package but I think/hope I understand your argumentation for such action.
Having said that I am still open for a debate on what is best for the community at large where that solution is depend fully on us knowing if we can or not collaborate and meet half way in any given solution.
But it does not preclude the fact that some architectural changes are still needed in the package and those can be made gradually via a minor releases or more aggressively via a major release and that is the main reason for the ticket.
Making the package "more attractive" for anyone to work on it is a side effect of those decisions not the otherway around at least that is how I see it.
nyamsprod commentedon Sep 20, 2024
@shadowhand Symfony will no longer try to create its own package but will wait for the URL class implementation of PHP itself which is currently under development so donation is no longer on the table if it was ever considered.
nyamsprod commentedon Jan 1, 2025
I have a new proposal this is due to the following events happening in the community:
Following all these events I have been working on version
7.6.0
and in parallel laying down a path for the future of the package the following are my conclusions:League\Uri\Contracts\UriInterface
more and more optional and suboptimal.As such the new proposal is the following:
The URI toolkit will include only 2 packages:
uri-interfaces
containing, the parsers, the main exceptions and the helpers features (like theEncoder
and the IP related converters)uri
will merge the content of the currenturi
anduri-components
packagesIf and when a native RFC3986/87 URI class is released we may then either
uri-interfaces
uri-polyfill
Symfony
polyfill-uri package that will most probably be develop.Of note: I am tempted to remove if not all but most of the current interfaces that are, in most part. useless and adds complexity for little gains to the packages usability.
The URI toolkit will focus on RFC3986/87 and thus the current
BaseUri
class will be dropped as it expose partially some algorithms from the WHATWG specifications. Having say that the toolkit should still be able to provide such features in a more obvious manner.For instance in
v7.6.0
:BaseUri
class have been re-implemented into theUri
class which renders theBaseUri
class completely useless except for one feature.League\Uri\Modifier
class contains a new modifier method calledwhatWgHost
which normalizes the host name according to the WHATWG rules and constraints.** This is the only feature that was not back-ported to theUri
class**For
v8.0
We could also add aFragmentDirective
to complement the already presentURLSearchParams
class.The remaining question is why we are not going to develop a WHATWG URI ? The answer is that there's already a really good user land implementation of the WHATWG URI and creating a second implementation makes no sense from my POV. We could simply point to or refer to it in the
suggest
section of the toolkit. And if needed:Symfony
polyfill-uri package that will most probably be develop using that package as a starting point.so TL;DR: