Complement UriTemplate expand with a method to return PSR7 Uri objects

Author: nyamsprod

docs/uri/7.0/uri-template.md

@@ -23,17 +23,18 @@ $template = 'https://example.com/hotels/{hotel}/bookings/{booking}';
 $params = ['booking' => '42', 'hotel' => 'Rest & Relax'];
 
 $uriTemplate = new UriTemplate($template);
-$uri = $uriTemplate->expand($params);             // instance of League\Uri\Uri
-$rfc3986Uri = $uriTemplate->expandToUri($params); // instance of Uri\Rfc3986\Uri
-$whatWgUrl = $uriTemplate->expandToUrl($params);  // instance of Uri\Whatwg\Url
+$uri = $uriTemplate->expand($params);              // instance of League\Uri\Uri
+$rfc3986Uri = $uriTemplate->expandToUri($params);  // instance of Uri\Rfc3986\Uri
+$whatWgUrl = $uriTemplate->expandToUrl($params);   // instance of Uri\Whatwg\Url
+$psr7Uri = $uriTemplate->expandToPsr7Uri($params); // instance of Psr7 UriInterface
 
 echo $uri; //display https://example.com/hotels/Rest%20%26%20Relax/bookings/42"
 ~~~
 
-<p class="message-notice"><code>expandToUri()</code> and <code>expandToUrl()</code> are available since
+<p class="message-notice"><code>expandToUri()</code>, <code>expandToUrl()</code> and <code>expandToPsr7Uri()</code> are available since
 version <code>7.6.0</code></p>
 
-<p class="message-info">Since version <code>7.6</code> the method takes a second optional parameter
+<p class="message-info">Since version <code>7.6</code> the <code>expand()</code> method takes a second optional parameter
 which serves as a base URI. The generated URI is resolved against the Base URI.</p>
 
 ~~~php
@@ -48,6 +49,7 @@ $uriTemplate = new UriTemplate($template);
 $uri = $uriTemplate->expand($params, 'https://example.com');             // instance of League\Uri\Uri
 $rfc3986Uri = $uriTemplate->expandToUri($params, 'https://example.com'); // instance of Uri\Rfc3986\Uri
 $whatWgUrl = $uriTemplate->expandToUrl($params, 'https://example.com');  // instance of Uri\Whatwg\Url
+$whatWgUrl = $uriTemplate->expandToPsr7Uri($params, 'https://example.com');  // instance of League\Uri\Http
 
 echo $uri; //display https://example.com/hotels/Rest%20%26%20Relax/bookings/42"
 ~~~
@@ -97,8 +99,8 @@ echo $uriTemplate->expand($params), PHP_EOL;
 //displays https://api.twitter.com/2.0/search/j/john/?q=a&q=b&limit=10
 ~~~
 
-The `expandToUri()` and the `expandToUrl()` methods will act exactly like the `expand()` method
-but will instead return a `Uri\Rfc3986\Uri` and a `Uri\Whatwg\Url` object respectively.
+The `expandToUri()`, `expandToUrl()` and `expandToPsr7Uri()` methods will act exactly like the `expand()` method
+but will instead return a `Uri\Rfc3986\Uri`, a `Uri\Whatwg\Url` or a `Psr7\Http\Message\UriInterface` object respectively.
 
 <p class="message-warning">a WHATWG URL must always be absolute if the URI template is not you
 MUST provide a base URL to <code>expandToUrl()</code> otherwise an <code>Uri\WhatWg\InvalidUrlException</code>
@@ -121,6 +123,31 @@ echo $uriTemplate->expandToUrl($params, 'https://api.twitter.com')->toAsciiStrin
 echo $uriTemplate->expandToUrl($params); //will throw
 ~~~
 
+<p class="message-info">You may return a different <code>Psr7\Http\Message\UriInterface</code> object if you
+provide to the <code>expandToPsr7Uri</code> your own <code>Psr\Http\Message\UriFactoryInterface</code> class
+as the third optional argument.</p>
+
+~~~php
+use League\Uri\UriTemplate;
+use Laminas\Diactoros\UriFactory;
+
+$template = '/{version}/search/{term:1}/{term}/{?q*,limit}';
+//the template represents a non-absolute URL
+
+$params = [
+    'term' => 'john',
+    'q' => ['a', 'b'],
+    'limit' => '10',
+    'version' => '2.0'
+];
+
+$uriTemplate = new UriTemplate($template, ['version' => '1.1']);
+$uri = $uriTemplate->expandToPsr7Uri($params, 'https://api.twitter.com', new UriFactory());
+$uri::class; // returns 'Laminas\Diactoros\Uri'
+~~~
+
+By default, if no factory is provided, the returned PSR-7 `UriInterface` object is a `League\Uri\Http` instance.
+
 ### Updating the default variables
 
 At any given time you may update your default variables but since the `UriTemplate`

uri/CHANGELOG.md

@@ -33,9 +33,10 @@ All Notable changes to `League\Uri` will be documented in this file
 - `Uri::withUsername` returns a new `Uri` instance with the updated username component.
 - `Uri::withPassword` returns a new `Uri` instance with the updated password component.
 - `UriTemplate` implements the `Stringable` interface
-- `UriTemplate::expandToUri` and `UriTemplate::expandToUrl`
-- `UriTemplate::expandToUriOrFail` and `UriTemplate::expandToUrlOrFail`
-- `UriTemplate::expand` takes a second optional parameter which represents a base URI to resolve the URI from.
+- `UriTemplate::expandToUri` and `UriTemplate::expandToUriOrFail`
+- `UriTemplate::expandToUrl` and `UriTemplate::expandToUrlOrFail`
+- `UriTemplate::expandToPsr7Uri` and `UriTemplate::expandToPsr7UriOrFail`
+- `UriTemplate::expand` and `UriTemplate::expandOrFail` take a second optional parameter which represents a base URI to resolve the URI from.
 - Dependency to `psr/http-factory` package which is required for the package.
 - Support for `Uri\Rfc3986\Uri` and `Uri\Whatwg\Url`
 

uri/UriTemplate.php

@@ -20,6 +20,8 @@
 use League\Uri\UriTemplate\Template;
 use League\Uri\UriTemplate\TemplateCanNotBeExpanded;
 use League\Uri\UriTemplate\VariableBag;
+use Psr\Http\Message\UriFactoryInterface;
+use Psr\Http\Message\UriInterface as Psr7UriInterface;
 use Stringable;
 use Uri\InvalidUriException;
 use Uri\Rfc3986\Uri as Rfc3986Uri;
@@ -150,11 +152,33 @@ public function expandToUri(iterable $variables = [], Rfc3986Uri|WhatWgUrl|Strin
      * @throws InvalidUrlException if the base URI cannot be converted to a Uri\Whatwg\Url instance
      * @throws InvalidUrlException if the resulting expansion cannot be converted to a Uri\Whatwg\Url instance
      */
-    public function expandToUrl(iterable $variables = [], WhatWgUrl|Stringable|string|null $baseUrl = null): WhatWgUrl
+    public function expandToUrl(iterable $variables = [], Rfc3986Uri|WhatWgUrl|Stringable|string|null $baseUrl = null): WhatWgUrl
     {
         return new WhatWgUrl($this->templateExpanded($variables), $this->newWhatWgUrl($baseUrl));
     }
 
+    /**
+     * @throws TemplateCanNotBeExpanded if the variables are invalid
+     * @throws UriException if the resulting expansion cannot be converted to a UriInterface instance
+     */
+    public function expandToPsr7Uri(
+        iterable $variables = [],
+        Rfc3986Uri|WhatWgUrl|Stringable|string|null $baseUrl = null,
+        UriFactoryInterface $uriFactory = new HttpFactory()
+    ): Psr7UriInterface {
+        $uriString = $this->templateExpandedOrFail($variables);
+
+        return $uriFactory->createUri(
+            null === $baseUrl
+            ? $uriString
+            : UriString::resolve($uriString, match (true) {
+                $baseUrl instanceof Rfc3986Uri => $baseUrl->toRawString(),
+                $baseUrl instanceof WhatWgUrl => $baseUrl->toUnicodeString(),
+                default => $baseUrl,
+            })
+        );
+    }
+
     /**
      * @throws TemplateCanNotBeExpanded if the variables are invalid or missing
      * @throws UriException if the resulting expansion cannot be converted to a UriInterface instance
@@ -178,14 +202,39 @@ public function expandToUriOrFail(iterable $variables = [], Rfc3986Uri|WhatWgUrl
 
     /**
      * @throws TemplateCanNotBeExpanded if the variables are invalid
-     * @throws InvalidUriException if the base URI cannot be converted to a Uri\Whatwg\Url instance
-     * @throws InvalidUriException if the resulting expansion cannot be converted to a Uri\Whatwg\Url instance
+     * @throws InvalidUrlException if the base URI cannot be converted to a Uri\Whatwg\Url instance
+     * @throws InvalidUrlException if the resulting expansion cannot be converted to a Uri\Whatwg\Url instance
      */
     public function expandToUrlOrFail(iterable $variables = [], Rfc3986Uri|WhatWgUrl|Stringable|string|null $baseUrl = null): WhatWgUrl
     {
         return new WhatWgUrl($this->templateExpandedOrFail($variables), $this->newWhatWgUrl($baseUrl));
     }
 
+    /**
+     * @throws TemplateCanNotBeExpanded if the variables are invalid
+     * @throws UriException if the resulting expansion cannot be converted to a UriInterface instance
+     */
+    public function expandToPsr7UriOrFail(
+        iterable $variables = [],
+        Rfc3986Uri|WhatWgUrl|Stringable|string|null $baseUrl = null,
+        UriFactoryInterface $uriFactory = new HttpFactory()
+    ): Psr7UriInterface {
+        $uriString = $this->templateExpandedOrFail($variables);
+
+        return $uriFactory->createUri(
+            null === $baseUrl
+            ? $uriString
+            : UriString::resolve($uriString, match (true) {
+                $baseUrl instanceof Rfc3986Uri => $baseUrl->toRawString(),
+                $baseUrl instanceof WhatWgUrl => $baseUrl->toUnicodeString(),
+                default => $baseUrl,
+            })
+        );
+    }
+
+    /**
+     * @throws InvalidUrlException
+     */
     private function newWhatWgUrl(Rfc3986Uri|WhatWgUrl|Stringable|string|null $url = null): ?WhatWgUrl
     {
         return match (true) {
@@ -196,13 +245,16 @@ private function newWhatWgUrl(Rfc3986Uri|WhatWgUrl|Stringable|string|null $url =
         };
     }
 
-    private function newRfc3986Uri(Rfc3986Uri|WhatWgUrl|Stringable|string|null $url = null): ?Rfc3986Uri
+    /**
+     * @throws InvalidUriException
+     */
+    private function newRfc3986Uri(Rfc3986Uri|WhatWgUrl|Stringable|string|null $uri = null): ?Rfc3986Uri
     {
         return match (true) {
-            null === $url => null,
-            $url instanceof Rfc3986Uri => $url,
-            $url instanceof WhatWgUrl => new Rfc3986Uri($url->toAsciiString()),
-            default => new Rfc3986Uri((string) $url),
+            null === $uri => null,
+            $uri instanceof Rfc3986Uri => $uri,
+            $uri instanceof WhatWgUrl => new Rfc3986Uri($uri->toAsciiString()),
+            default => new Rfc3986Uri((string) $uri),
         };
     }