UriTemplate can now returns PHP Uri objects

Author: nyamsprod

docs/uri/7.0/uri-template.md

@@ -23,10 +23,16 @@ $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
+$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
+
 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
+version <code>7.6.0</code></p>
+
 ## Template variables
 
 <p class="message-notice">For maximum interoperability you should make sure your variables are 
@@ -72,6 +78,30 @@ 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.
+
+<p class="message-warning">a WHATWG URL must always be absolute if the URI template is not you
+should provide to <code>expandToUrl()</code> a base URL otherwise an <code>Uri\WhatWg\InvalidUrlException</code>
+exception will be thrown.</p>
+
+~~~php
+$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']);
+
+echo $uriTemplate->expandToUrl($params, 'https://api.twitter.com')->toAsciiString(); //works
+echo $uriTemplate->expandToUrl($params); //will throw
+~~~
+
 ### Updating the default variables
 
 At any given time you may update your default variables but since the `UriTemplate`

uri/CHANGELOG.md

@@ -33,6 +33,8 @@ 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`
 - Dependency to `psr/http-factory` package which is required for the package.
 - Support for `Uri\Rfc3986\Uri` and `Uri\Whatwg\Url`
 

uri/UriTemplate.php

@@ -21,6 +21,9 @@
 use League\Uri\UriTemplate\TemplateCanNotBeExpanded;
 use League\Uri\UriTemplate\VariableBag;
 use Stringable;
+use Uri\InvalidUriException;
+use Uri\Rfc3986\Uri as Rfc3986Uri;
+use Uri\WhatWg\Url as WhatWgUrl;
 
 use function array_fill_keys;
 use function array_key_exists;
@@ -110,15 +113,46 @@ public function withDefaultVariables(iterable $defaultVariables): self
         return new self($this->template, $defaultVariables);
     }
 
+    private function templateExpanded(iterable $variables = []): string
+    {
+        return $this->template->expand($this->filterVariables($variables)->replace($this->defaultVariables));
+    }
+
+    private function templateExpandedOrFail(iterable $variables = []): string
+    {
+        return $this->template->expandOrFail($this->filterVariables($variables)->replace($this->defaultVariables));
+    }
+
     /**
      * @throws TemplateCanNotBeExpanded if the variables are invalid
      * @throws UriException if the resulting expansion cannot be converted to a UriInterface instance
      */
     public function expand(iterable $variables = []): UriInterface
     {
-        return Uri::new($this->template->expand(
-            $this->filterVariables($variables)->replace($this->defaultVariables)
-        ));
+        return Uri::new($this->templateExpanded($variables));
+    }
+
+    /**
+     * @throws TemplateCanNotBeExpanded if the variables are invalid
+     * @throws InvalidUriException if the resulting expansion cannot be converted to a Uri\Rfc3986\Uri instance
+     */
+    public function expandToUri(iterable $variables = []): Rfc3986Uri
+    {
+        return new Rfc3986Uri($this->template->expand($variables));
+    }
+
+    /**
+     * @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
+     */
+    public function expandToUrl(iterable $variables = [], WhatWgUrl|Stringable|string|null $baseUri = null): WhatWgUrl
+    {
+        return new WhatWgUrl($this->templateExpanded($variables), match (true) {
+            null === $baseUri => null,
+            $baseUri instanceof WhatWgUrl => $baseUri,
+            default => new WhatWgUrl((string) $baseUri),
+        });
     }
 
     /**
@@ -127,9 +161,30 @@ public function expand(iterable $variables = []): UriInterface
      */
     public function expandOrFail(iterable $variables = []): UriInterface
     {
-        return Uri::new($this->template->expandOrFail(
-            $this->filterVariables($variables)->replace($this->defaultVariables)
-        ));
+        return Uri::new($this->templateExpandedOrFail($variables));
+    }
+
+    /**
+     * @throws TemplateCanNotBeExpanded if the variables are invalid
+     * @throws InvalidUriException if the resulting expansion cannot be converted to a Uri\Rfc3986\Uri instance
+     */
+    public function expandToUriOrFail(iterable $variables = []): Rfc3986Uri
+    {
+        return new Rfc3986Uri($this->template->expandOrFail($variables));
+    }
+
+    /**
+     * @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
+     */
+    public function expandToUrlOrFail(iterable $variables = [], WhatWgUrl|Stringable|string|null $baseUri = null): WhatWgUrl
+    {
+        return new WhatWgUrl($this->templateExpandedOrFail($variables), match (true) {
+            null === $baseUri => null,
+            $baseUri instanceof WhatWgUrl => $baseUri,
+            default => new WhatWgUrl((string) $baseUri),
+        });
     }
 
     /**