Return object from URI generation

This provides a richer API, allowing users to also retrieve the
substitutions that were sent but aren't part of the route (either as a
map or by generating a PSR-7 URI object).

Signed-off-by: Luís Cobucci <[email protected]>

Author: lcobucci

composer.json

@@ -14,10 +14,12 @@
     ],
     "require": {
         "php": ">=8.1.0",
+        "psr/http-message": "^2.0",
         "psr/simple-cache": "^2.0 || ^3.0"
     },
     "require-dev": {
         "lcobucci/coding-standard": "^11.1",
+        "nyholm/psr7": "^1.8",
         "phpbench/phpbench": "^1.2",
         "phpstan/extension-installer": "^1.1",
         "phpstan/phpstan": "^1.10",

composer.lock

@@ -3,6 +3,7 @@
 
 namespace FastRoute;
 
+use FastRoute\GenerateUri\GeneratedUri;
 use FastRoute\GenerateUri\UriCouldNotBeGenerated;
 
 /**
@@ -17,5 +18,5 @@ interface GenerateUri
      *
      * @throws UriCouldNotBeGenerated
      */
-    public function forRoute(string $name, array $substitutions = []): string;
+    public function forRoute(string $name, array $substitutions = []): GeneratedUri;
 }

src/GenerateUri.php

@@ -26,7 +26,7 @@ public function __construct(private readonly array $processedConfiguration)
     }
 
     /** @inheritDoc */
-    public function forRoute(string $name, array $substitutions = []): string
+    public function forRoute(string $name, array $substitutions = []): GeneratedUri
     {
         if (! array_key_exists($name, $this->processedConfiguration)) {
             throw UriCouldNotBeGenerated::routeIsUndefined($name);
@@ -79,7 +79,7 @@ private function missingParameters(array $parts, array $substitutions): array
      * @param ParsedRoute      $parsedRoute
      * @param UriSubstitutions $substitutions
      */
-    private function generatePath(string $route, array $parsedRoute, array $substitutions): string
+    private function generatePath(string $route, array $parsedRoute, array $substitutions): GeneratedUri
     {
         $path = '';
 
@@ -97,8 +97,11 @@ private function generatePath(string $route, array $parsedRoute, array $substitu
             }
 
             $path .= $substitutions[$parameterName];
+            unset($substitutions[$parameterName]);
         }
 
-        return $path;
+        assert($path !== '');
+
+        return new GeneratedUri($path, $substitutions);
     }
 }

src/GenerateUri/FromProcessedConfiguration.php

@@ -0,0 +1,36 @@
+<?php
+declare(strict_types=1);
+
+namespace FastRoute\GenerateUri;
+
+use FastRoute\GenerateUri;
+use Psr\Http\Message\UriInterface;
+use Stringable;
+
+use function http_build_query;
+
+/** @phpstan-import-type UriSubstitutions from GenerateUri */
+final class GeneratedUri implements Stringable
+{
+    /**
+     * @param non-empty-string $path
+     * @param UriSubstitutions $unmatchedSubstitutions
+     */
+    public function __construct(
+        public readonly string $path,
+        public readonly array $unmatchedSubstitutions,
+    ) {
+    }
+
+    public function asUri(UriInterface $baseUri): UriInterface
+    {
+        return $baseUri
+            ->withPath($this->path)
+            ->withQuery(http_build_query($this->unmatchedSubstitutions));
+    }
+
+    public function __toString(): string
+    {
+        return $this->path;
+    }
+}

src/GenerateUri/GeneratedUri.php

@@ -8,6 +8,7 @@
 use FastRoute\Dispatcher;
 use FastRoute\FastRoute;
 use FastRoute\GenerateUri;
+use Nyholm\Psr7\Uri;
 use PHPUnit\Framework\Attributes as PHPUnit;
 use PHPUnit\Framework\TestCase;
 use RuntimeException;
@@ -115,9 +116,9 @@ public function uriGeneratorCanBeOverridden(): void
     {
         $generator = new class () implements GenerateUri {
             /** @inheritDoc */
-            public function forRoute(string $name, array $substitutions = []): string
+            public function forRoute(string $name, array $substitutions = []): GenerateUri\GeneratedUri
             {
-                return '';
+                return new GenerateUri\GeneratedUri('/', $substitutions);
             }
         };
 
@@ -159,10 +160,11 @@ public function processedDataShouldOnlyBeBuiltOnce(): void
         self::assertInstanceOf(Dispatcher\Result\Matched::class, $dispatcher->dispatch('POST', '/users/lcobucci'));
         self::assertInstanceOf(Dispatcher\Result\Matched::class, $dispatcher->dispatch('GET', '/posts/1234'));
 
-        self::assertSame('/users/lcobucci', $uriGenerator->forRoute('users', ['name' => 'lcobucci']));
-        self::assertSame('/posts/1234', $uriGenerator->forRoute('posts.fetch', ['id' => '1234']));
-        self::assertSame('/articles/2024', $uriGenerator->forRoute('articles.fetch', ['year' => '2024']));
-        self::assertSame('/articles/2024/02', $uriGenerator->forRoute('articles.fetch', ['year' => '2024', 'month' => '02']));
-        self::assertSame('/articles/2024/02/15', $uriGenerator->forRoute('articles.fetch', ['year' => '2024', 'month' => '02', 'day' => '15']));
+        self::assertEquals('/users/lcobucci', $uriGenerator->forRoute('users', ['name' => 'lcobucci']));
+        self::assertEquals('/posts/1234', $uriGenerator->forRoute('posts.fetch', ['id' => '1234']));
+        self::assertEquals('/articles/2024', $uriGenerator->forRoute('articles.fetch', ['year' => '2024']));
+        self::assertEquals('/articles/2024/02', $uriGenerator->forRoute('articles.fetch', ['year' => '2024', 'month' => '02']));
+        self::assertEquals('/articles/2024/02/15', $uriGenerator->forRoute('articles.fetch', ['year' => '2024', 'month' => '02', 'day' => '15']));
+        self::assertSame('/articles/2024/02/15?extra=value', (string) $uriGenerator->forRoute('articles.fetch', ['year' => '2024', 'month' => '02', 'day' => '15', 'extra' => 'value'])->asUri(new Uri()));
     }
 }

test/FastRouteTest.php

@@ -5,6 +5,7 @@
 
 use FastRoute\GenerateUri;
 use FastRoute\RouteParser;
+use Nyholm\Psr7\Uri;
 use PHPUnit\Framework\Attributes as PHPUnit;
 use PHPUnit\Framework\TestCase;
 
@@ -63,22 +64,22 @@ public function routesWithOptionalSegmentsCanBeGenerated(): void
     {
         $generator = self::routeGeneratorFor(['archive.fetch' => '/archive/{username}[/{year}[/{month}[/{day}]]]']);
 
-        self::assertSame(
+        self::assertEquals(
             '/archive/test',
             $generator->forRoute('archive.fetch', ['username' => 'test']),
         );
 
-        self::assertSame(
+        self::assertEquals(
             '/archive/test/2024',
             $generator->forRoute('archive.fetch', ['username' => 'test', 'year' => '2024']),
         );
 
-        self::assertSame(
+        self::assertEquals(
             '/archive/test/2024/02',
             $generator->forRoute('archive.fetch', ['username' => 'test', 'year' => '2024', 'month' => '02']),
         );
 
-        self::assertSame(
+        self::assertEquals(
             '/archive/test/2024/02/01',
             $generator->forRoute(
                 'archive.fetch',
@@ -92,15 +93,15 @@ public function staticRoutesCanAlsoBeGenerated(): void
     {
         $generator = self::routeGeneratorFor(['post.fetch-special' => '/post/a-special-post']);
 
-        self::assertSame('/post/a-special-post', $generator->forRoute('post.fetch-special'));
+        self::assertEquals('/post/a-special-post', $generator->forRoute('post.fetch-special'));
     }
 
     #[PHPUnit\Test]
     public function resultingUriMustNotHaveUrlEncodedParameters(): void
     {
         $generator = self::routeGeneratorFor(['post.fetch' => '/post/{id}']);
 
-        self::assertSame(
+        self::assertEquals(
             '/post/@something-that needs to be encoded 😁',
             $generator->forRoute('post.fetch', ['id' => '@something-that needs to be encoded 😁']),
         );
@@ -111,18 +112,37 @@ public function urlEncodedParametersShouldNotBeManipulated(): void
     {
         $generator = self::routeGeneratorFor(['post.fetch' => '/post/{id}']);
 
-        self::assertSame(
+        self::assertEquals(
             '/post/%40something%20that%20needs%20to%20be%20encoded%20%F0%9F%98%81',
             $generator->forRoute('post.fetch', ['id' => '%40something%20that%20needs%20to%20be%20encoded%20%F0%9F%98%81']),
         );
     }
 
+    #[PHPUnit\Test]
+    public function nonProcessedParametersAreRetrievable(): void
+    {
+        $generator = self::routeGeneratorFor(['post.fetch' => '/post/{id}']);
+        $generatedUri = $generator->forRoute('post.fetch', ['id' => 'testing', 'foo' => 'bar', 'baz' => 'foo']);
+
+        self::assertSame('/post/testing', $generatedUri->path);
+        self::assertSame(['foo' => 'bar', 'baz' => 'foo'], $generatedUri->unmatchedSubstitutions);
+        self::assertSame(
+            'https://api.my-company.dev:8080/post/testing?foo=bar&baz=foo',
+            (string) $generatedUri->asUri(
+                (new Uri())
+                    ->withScheme('https')
+                    ->withHost('api.my-company.dev')
+                    ->withPort(8080),
+            ),
+        );
+    }
+
     #[PHPUnit\Test]
     public function unicodeParametersAreAlsoAccepted(): void
     {
         $generator = self::routeGeneratorFor(['post.fetch' => '/post/{id:[\w\-\%]+}']);
 
-        self::assertSame('/post/bar-測試', $generator->forRoute('post.fetch', ['id' => 'bar-測試']));
+        self::assertEquals('/post/bar-測試', $generator->forRoute('post.fetch', ['id' => 'bar-測試']));
     }
 
     /** @param non-empty-array<non-empty-string, non-empty-string> $routeMap */