Update UriTemplate API to keep te method consistent

Author: nyamsprod

components/Modifier.php

@@ -58,9 +58,9 @@
 use function rtrim;
 use function str_ends_with;
 use function str_starts_with;
-
 use function strtolower;
 use function trim;
+
 use const FILTER_FLAG_IPV4;
 use const FILTER_VALIDATE_IP;
 

docs/uri/7.0/uri-template.md

@@ -102,6 +102,10 @@ echo $uriTemplate->expandToUrl($params, 'https://api.twitter.com')->toAsciiStrin
 echo $uriTemplate->expandToUrl($params); //will throw
 ~~~
 
+<p class="message-info">The same feature of adding a base URI is also supported for the
+other two methods <code>expand()</code> and <code>expandToUri</code> but only if the
+baseURI variable is not <code>null</code>.</p>
+
 ### Updating the default variables
 
 At any given time you may update your default variables but since the `UriTemplate`
@@ -124,7 +128,7 @@ $newUriTemplate = $uriTemplate->withDefaultVariables(['version' => '1.1']);
 $newUriTemplate->getDefaultVariables(); //returns  new VariableBag(['version' => '1.1'])
 ~~~
 
-<p class="message-warning">Following  RFC6570 requirements means not support for
+<p class="message-warning">Following RFC6570 requirements means not support for
 nested array like the one used with <code>http_build_query</code></p>
 
 ~~~php

uri/Uri.php

@@ -40,8 +40,8 @@
 use TypeError;
 use Uri\Rfc3986\Uri as Rfc3986Uri;
 use Uri\WhatWg\Url as WhatWgUrl;
-
 use ValueError;
+
 use function array_filter;
 use function array_key_last;
 use function array_map;
@@ -1201,8 +1201,12 @@ public function toString(): string
     public function toDisplayString(): string
     {
         $components = $this->toComponents();
+        $port = null;
+        if (isset($components['port'])) {
+            $port = (int) $components['port'];
+            unset($components['port']);
+        }
 
-        unset($components['port']);
         if (null !== $components['host']) {
             $components['host'] = IdnaConverter::toUnicode($components['host'])->domain();
         }
@@ -1218,12 +1222,12 @@ public function toDisplayString(): string
         $components['fragment'] = Encoder::decodeFragment($components['fragment']);
 
         return UriString::build([
-            ...array_map(fn (string|null $value) => match (true) {
+            ...array_map(fn (?string $value) => match (true) {
                 null === $value,
                 !str_contains($value, '%20') => $value,
                 default => str_replace('%20', ' ', $value),
             }, $components),
-            ...['port' => $this->port],
+            ...['port' => $port],
         ]);
     }
 

uri/UriTemplate.php

@@ -128,18 +128,21 @@ private function templateExpandedOrFail(iterable $variables = []): string
      * @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
+    public function expand(iterable $variables = [], Rfc3986Uri|WhatWgUrl|Stringable|string|null $baseUri = null): UriInterface
     {
-        return Uri::new($this->templateExpanded($variables));
+        $expanded = $this->templateExpanded($variables);
+
+        return null === $baseUri ? Uri::new($expanded) : Uri::fromBaseUri($expanded, $baseUri);
     }
 
     /**
      * @throws TemplateCanNotBeExpanded if the variables are invalid
+     * @throws InvalidUriException if the base URI cannot be converted to a Uri\Rfc3986\Uri instance
      * @throws InvalidUriException if the resulting expansion cannot be converted to a Uri\Rfc3986\Uri instance
      */
-    public function expandToUri(iterable $variables = []): Rfc3986Uri
+    public function expandToUri(iterable $variables = [], Rfc3986Uri|WhatWgUrl|Stringable|string|null $baseUri = null): Rfc3986Uri
     {
-        return new Rfc3986Uri($this->templateExpanded($variables));
+        return new Rfc3986Uri($this->templateExpanded($variables), $this->newRfc3986Uri($baseUri));
     }
 
     /**
@@ -156,39 +159,53 @@ public function expandToUrl(iterable $variables = [], WhatWgUrl|Stringable|strin
      * @throws TemplateCanNotBeExpanded if the variables are invalid or missing
      * @throws UriException if the resulting expansion cannot be converted to a UriInterface instance
      */
-    public function expandOrFail(iterable $variables = []): UriInterface
+    public function expandOrFail(iterable $variables = [], Rfc3986Uri|WhatWgUrl|Stringable|string|null $baseUri = null): UriInterface
     {
-        return Uri::new($this->templateExpandedOrFail($variables));
+        $expanded = $this->templateExpandedOrFail($variables);
+
+        return null === $baseUri ? Uri::new($expanded) : Uri::fromBaseUri($expanded, $baseUri);
     }
 
     /**
      * @throws TemplateCanNotBeExpanded if the variables are invalid
+     * @throws InvalidUriException if the base URI cannot be converted to a Uri\Rfc3986\Uri instance
      * @throws InvalidUriException if the resulting expansion cannot be converted to a Uri\Rfc3986\Uri instance
      */
-    public function expandToUriOrFail(iterable $variables = []): Rfc3986Uri
+    public function expandToUriOrFail(iterable $variables = [], Rfc3986Uri|WhatWgUrl|Stringable|string|null $baseUri = null): Rfc3986Uri
     {
-        return new Rfc3986Uri($this->templateExpandedOrFail($variables));
+        return new Rfc3986Uri($this->templateExpandedOrFail($variables), $this->newRfc3986Uri($baseUri));
     }
 
     /**
      * @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 $baseUrl = null): WhatWgUrl
+    public function expandToUrlOrFail(iterable $variables = [], Rfc3986Uri|WhatWgUrl|Stringable|string|null $baseUrl = null): WhatWgUrl
     {
         return new WhatWgUrl($this->templateExpandedOrFail($variables), $this->newWhatWgUrl($baseUrl));
     }
 
-    private function newWhatWgUrl(WhatWgUrl|Stringable|string|null $url = null): ?WhatWgUrl
+    private function newWhatWgUrl(Rfc3986Uri|WhatWgUrl|Stringable|string|null $url = null): ?WhatWgUrl
     {
         return match (true) {
             null === $url => null,
             $url instanceof WhatWgUrl => $url,
+            $url instanceof Rfc3986Uri => new WhatWgUrl($url->toRawString()),
             default => new WhatWgUrl((string) $url),
         };
     }
 
+    private function newRfc3986Uri(Rfc3986Uri|WhatWgUrl|Stringable|string|null $url = null): ?Rfc3986Uri
+    {
+        return match (true) {
+            null === $url => null,
+            $url instanceof Rfc3986Uri => $url,
+            $url instanceof WhatWgUrl => new Rfc3986Uri($url->toAsciiString()),
+            default => new Rfc3986Uri((string) $url),
+        };
+    }
+
     /**
      * DEPRECATION WARNING! This method will be removed in the next major point release.
      *