From 5e43ea443e761a111f84a18abc1da818a5c7c6f2 Mon Sep 17 00:00:00 2001
From: ignace nyamagana butera <nyamsprod@gmail.com>
Date: Sat, 25 Jan 2025 07:54:23 +0100
Subject: [PATCH] Improve UriTemplate interoperability with PSR-13

---
 docs/uri/7.0/uri-template.md | 25 ++++++++++++++++++++++++-
 uri/CHANGELOG.md             |  1 +
 uri/UriTemplate.php          | 30 ++++++++++++++++++++++++++++--
 uri/UriTemplateTest.php      |  4 +---
 4 files changed, 54 insertions(+), 6 deletions(-)

diff --git a/docs/uri/7.0/uri-template.md b/docs/uri/7.0/uri-template.md
index b2a88100..8a976423 100644
--- a/docs/uri/7.0/uri-template.md
+++ b/docs/uri/7.0/uri-template.md
@@ -9,7 +9,6 @@ URI Template
 The `League\Uri\UriTemplate` class enables expanding a URI object based on a URI template and its 
 submitted parameters following [RFC 6570 URI Template](http://tools.ietf.org/html/rfc6570).
 
-
 ## Template expansion
 
 The `UriTemplate::expand` public method expands a URI template to generate a valid URI conforming
@@ -187,3 +186,27 @@ $uriTemplate = new UriTemplate($template);
 echo $uriTemplate->expand($params), PHP_EOL;
 // https://example.com/hotels/%7B/Rest%20%26%20Relax
 ~~~
+
+## Interoperability
+
+<p class="message-info">Available since <code>version 7.0</code></p>
+
+To allow easier integration with other PHP packages and especially [PSR-13](https://www.php-fig.org/psr/psr-13/)
+the `UriTemplate` class implements the `Stringable` interface.
+
+~~~php
+use League\Uri\UriTemplate;
+use Symfony\Component\WebLink\Link;
+
+$uriTemplate = new UriTemplate('https://google.com/search{?q*}');
+
+$link = (new Link())
+    ->withHref($uriTemplate)
+    ->withRel('next')
+    ->withAttribute('me', 'you');
+
+// Once serialized will return
+// '<https://google.com/search{?q*}>; rel="next"; me="you"'
+~~~
+
+The `Symfony\Component\WebLink\Link` package implements `PSR-13` interfaces.
diff --git a/uri/CHANGELOG.md b/uri/CHANGELOG.md
index 616e696e..dde7475a 100644
--- a/uri/CHANGELOG.md
+++ b/uri/CHANGELOG.md
@@ -16,6 +16,7 @@ All Notable changes to `League\Uri` will be documented in this file
 - `Uri::getUser` returns the encoded user component of the URI an alias for `Uri::getUsername`
 - `Uri::fromMarkdownAnchor`
 - `Uri::fromHtmlAnchor`
+- `UriTemplate` implements the `Stringable` interface
 
 ### Fixed
 
diff --git a/uri/UriTemplate.php b/uri/UriTemplate.php
index 882a7b51..c714b733 100644
--- a/uri/UriTemplate.php
+++ b/uri/UriTemplate.php
@@ -13,6 +13,7 @@
 
 namespace League\Uri;
 
+use Deprecated;
 use League\Uri\Contracts\UriException;
 use League\Uri\Contracts\UriInterface;
 use League\Uri\Exceptions\SyntaxError;
@@ -31,8 +32,10 @@
  * @package League\Uri
  * @author  Ignace Nyamagana Butera <nyamsprod@gmail.com>
  * @since   6.1.0
+ *
+ * @phpstan-import-type InputValue from VariableBag
  */
-final class UriTemplate
+final class UriTemplate implements Stringable
 {
     private readonly Template $template;
     private readonly VariableBag $defaultVariables;
@@ -60,12 +63,17 @@ private function filterVariables(iterable $variables): VariableBag
             ));
     }
 
-    public function getTemplate(): string
+    /**
+     * Returns the string representation of the UriTemplate.
+     */
+    public function __toString(): string
     {
         return $this->template->value;
     }
 
     /**
+     * Returns the distinct variables placeholders used in the template.
+     *
      * @return array<string>
      */
     public function getVariableNames(): array
@@ -73,6 +81,9 @@ public function getVariableNames(): array
         return $this->template->variableNames;
     }
 
+    /**
+     * @return array<string, InputValue>
+     */
     public function getDefaultVariables(): array
     {
         return iterator_to_array($this->defaultVariables);
@@ -120,4 +131,19 @@ public function expandOrFail(iterable $variables = []): UriInterface
             $this->filterVariables($variables)->replace($this->defaultVariables)
         ));
     }
+
+    /**
+     * DEPRECATION WARNING! This method will be removed in the next major point release.
+     *
+     * @deprecated Since version 7.6.0
+     * @codeCoverageIgnore
+     * @see UriTemplate::toString()
+     *
+     * Create a new instance from the environment.
+     */
+    #[Deprecated(message:'use League\Uri\UriTemplate::__toString() instead', since:'league/uri:7.6.0')]
+    public function getTemplate(): string
+    {
+        return $this->__toString();
+    }
 }
diff --git a/uri/UriTemplateTest.php b/uri/UriTemplateTest.php
index 2d55944a..14c36ca4 100644
--- a/uri/UriTemplateTest.php
+++ b/uri/UriTemplateTest.php
@@ -33,9 +33,7 @@ public function testGetTemplate(): void
             'foo[]' => ['fizz', 'buzz'],
         ];
 
-        $uriTemplate = new UriTemplate($template, $variables);
-
-        self::assertSame($template, $uriTemplate->getTemplate());
+        self::assertSame($template, (string) new UriTemplate($template, $variables));
     }
 
     public function testGetDefaultVariables(): void