FEATURE: introduce `Neos\Flow\Http\UriHelper` to work with query parameters

[mhsdesign]

While working on https://github.com/neos/flow-development-collection/pull/2744 and also https://github.com/neos/neos-development-collection/issues/4552 we always came to the conclusion that the $queryParameters merging of the psr uri is limited.

This introduces a utility to do this:

UriHelper::withAdditionalQueryParameters($this->someUriBuilder->uriFor(...), ['q' => 'search term']);

and allows us to remove any $queryParam logic from the uribuilder(s)

Upgrade instructions

Review instructions

Checklist

• [ ] Code follows the PSR-2 coding style
• [ ] Tests have been created, run and adjusted as needed
• [ ] The PR is created against the lowest maintained branch
• [ ] Reviewer - PR Title is brief but complete and starts with FEATURE|TASK|BUGFIX
• [ ] Reviewer - The first section explains the change briefly for change-logs
• [ ] Reviewer - Breaking Changes are marked with !!! and have upgrade-instructions

[mficzel]

Very nice idea ... how about using named variadic arguments instead of an array to

$this->someUriBuilder->uriFor(...)->withQueryParameters(q: 'search term');

The only downside of extending the psr uri imho would be that a future psr-version might define the same method with a different signature. Bit theoretical and we would find a way (migration) around that.

[mficzel]

Also:

1. The \Neos\Http\Factories\UriFactory should return the Neos Uri in that case and it might make more sense to
2. Why not extend \GuzzleHttp\Psr7\Uri as those guzzle classes are used in the UriFactory curently anyways

[mficzel]

Bastian is right ... even though i really like variadics

[kitsunet]

Yeeeeeah, but then how do we deal with interface compatibility, because suddenly every place we use this we shouldn't / can't rightfully annotate UriInterface anymore. I would rather prefer to go the guzzle route and implement static methods for this. It's a simple enough operation.

[bwaidelich]

I would rather prefer to go the guzzle route and implement static methods for this

@kitsunet Is your suggestion to not re-add the Uri implementation but instead provide some static method like

SomeClass {
  public static function addQueryParameters(UriInterface $uri, array $queryParameters): UriInterface;
}

?

I don't think that's a bad idea.. For the regular use cases (i.e. Fusion, ...) we can add corresponding helpers

[kitsunet]

Yes! Exctly, guzzle psr7 has a couple of helpers that do similar things (nothing for GET params though) but I find that super fine for such syntactic sugar.

[bwaidelich]

guzzle psr7 has a couple of helpers that do similar things (nothing for GET params though)

btw: It does https://github.com/guzzle/psr7/blob/2.6/src/Query.php#L71 but I prefer the suggested signature for brevity (SomeHelper::addQueryParameters($uri, ['foo' => 'bar']) instead of $uri->withQuery(Query::build(array_merge(Query::parse($uri->getQuery(), ['foo' => 'bar'])))

[mhsdesign]

Id be find also with a utility, even though its not that easily usable, but less pain on our end. Also we can simply document in the uribuilders that this utility exists and how to use it ;)

UriHelper::withAdditionalQueryParameters($this->someUriBuilder->uriFor(...), ['q' => 'search term']);

will implement this accordingly ;) And thanks for your extensive feedback!

[mhsdesign]

Okay added a UriHelper and removed also the old Uri tests, as we dont have an own implementation, and can assume that guzzle tests its stuff :D

[mhsdesign]

Lol i just found out we already have a \Neos\Flow\Http\Helper\UriHelper :D Have to reevaluate where to put this then :D And also \Neos\Flow\Mvc\Routing\Dto\UriConstraints::withAddedQueryValues seems to do something similar :D

[mhsdesign]

Wait a second i think i wanted to add the method to https://github.com/neos/flow-development-collection/blob/d8bed81a3b4229120c3084b78d5bcc0cb7cb2816/Neos.Flow/Classes/Http/Helper/UriHelper.php#L19

as otherwise we would have two UriHelper's 😂 lol (see https://github.com/neos/flow-development-collection/pull/3316#issuecomment-1948719515)

thanks for the plenty +1 but i prefer to merge my own prs :D

[mhsdesign]

The followup which was due since some time but i was to scared to jump into another rabbit hole: https://github.com/neos/flow-development-collection/pull/3336