Merge pull request #32 from gsteel/url-helper-interface

[RFC] Introduce UrlHelperInterface and mark UrlHelper as `@final`
mezzio · Mar 2, 2023 · f22dff3 · f22dff3
2 parents 2937314 + 50ee404
commit f22dff3
Show file tree

Hide file tree

Showing 5 changed files with 93 additions and 70 deletions.
diff --git a/src/ConfigProvider.php b/src/ConfigProvider.php
@@ -6,13 +6,15 @@
 
 class ConfigProvider
 {
+    /** @return array<string, mixed> */
     public function __invoke(): array
     {
         return [
             'dependencies' => $this->getDependencies(),
         ];
     }
 
+    /** @return array<string, mixed> */
     public function getDependencies(): array
     {
         return [
@@ -26,6 +28,9 @@ public function getDependencies(): array
                 UrlHelper::class           => UrlHelperFactory::class,
                 UrlHelperMiddleware::class => UrlHelperMiddlewareFactory::class,
             ],
+            'aliases'    => [
+                UrlHelperInterface::class => UrlHelper::class,
+            ],
         ];
     }
 }
diff --git a/src/UrlHelper.php b/src/UrlHelper.php
@@ -19,13 +19,10 @@
 use function sprintf;
 
 /**
- * @psalm-type UrlGeneratorOptions = array{
- *     router?: array<array-key, mixed>,
- *     reuse_result_params?: bool,
- *     reuse_query_params?: bool,
- * }
+ * @psalm-import-type UrlGeneratorOptions from UrlHelperInterface
+ * @final
  */
-class UrlHelper
+class UrlHelper implements UrlHelperInterface
 {
     /**
      * Regular expression used to validate fragment identifiers.
@@ -44,21 +41,7 @@ public function __construct(private RouterInterface $router)
     {
     }
 
-    /**
-     * Generate a URL based on a given route.
-     *
-     * @param array<string, mixed> $routeParams
-     * @param array<string, mixed> $queryParams
-     * @param UrlGeneratorOptions $options Can have the following keys:
-     *     - router (array): contains options to be passed to the router
-     *     - reuse_result_params (bool): indicates if the current RouteResult
-     *       parameters will be used, defaults to true
-     * @throws Exception\RuntimeException For attempts to use the currently matched
-     *     route but routing failed.
-     * @throws Exception\RuntimeException For attempts to use a matched result
-     *     when none has been previously injected in the instance.
-     * @throws InvalidArgumentException For malformed fragment identifiers.
-     */
+    /** @inheritDoc */
     public function __invoke(
         ?string $routeName = null,
         array $routeParams = [],
@@ -112,17 +95,7 @@ public function __invoke(
         return $path;
     }
 
-    /**
-     * Generate a URL based on a given route.
-     *
-     * Proxies to __invoke().
-     *
-     * @see UrlHelper::__invoke()
-     *
-     * @param array<string, mixed> $routeParams
-     * @param array<string, mixed> $queryParams
-     * @param UrlGeneratorOptions $options
-     */
+    /** @inheritDoc */
     public function generate(
         ?string $routeName = null,
         array $routeParams = [],

diff --git a/src/UrlHelperInterface.php b/src/UrlHelperInterface.php
@@ -0,0 +1,75 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Mezzio\Helper;
+
+use InvalidArgumentException;
+use Mezzio\Router\RouteResult;
+use Psr\Http\Message\ServerRequestInterface;
+
+/**
+ * @psalm-type UrlGeneratorOptions = array{
+ *     router?: array<array-key, mixed>,
+ *     reuse_result_params?: bool,
+ *     reuse_query_params?: bool,
+ * }
+ */
+interface UrlHelperInterface
+{
+    /**
+     * Generate a URL based on a given route.
+     *
+     * @param non-empty-string|null $routeName
+     * @param array<string, mixed> $routeParams
+     * @param array<string, mixed> $queryParams
+     * @param UrlGeneratorOptions $options Can have the following keys:
+     *     - router (array): contains options to be passed to the router
+     *     - reuse_result_params (bool): indicates if the current RouteResult parameters will be used, defaults to true
+     *     - reuse_query_params (bool): indicates if the current query parameters will be used, defaults to false
+     * @throws Exception\RuntimeException For attempts to use the currently matched route but routing failed.
+     * @throws Exception\RuntimeException For attempts to use a matched result
+     *     when none has been previously injected in the instance.
+     * @throws InvalidArgumentException For malformed fragment identifiers.
+     */
+    public function __invoke(
+        ?string $routeName = null,
+        array $routeParams = [],
+        array $queryParams = [],
+        ?string $fragmentIdentifier = null,
+        array $options = []
+    ): string;
+
+    /**
+     * Generate a URL based on a given route.
+     *
+     * @param non-empty-string|null $routeName
+     * @param array<string, mixed> $routeParams
+     * @param array<string, mixed> $queryParams
+     * @param UrlGeneratorOptions $options Can have the following keys:
+     *     - router (array): contains options to be passed to the router
+     *     - reuse_result_params (bool): indicates if the current RouteResult parameters will be used, defaults to true
+     *     - reuse_query_params (bool): indicates if the current query parameters will be used, defaults to false
+     * @throws Exception\RuntimeException For attempts to use the currently matched route but routing failed.
+     * @throws Exception\RuntimeException For attempts to use a matched result
+     *     when none has been previously injected in the instance.
+     * @throws InvalidArgumentException For malformed fragment identifiers.
+     */
+    public function generate(
+        ?string $routeName = null,
+        array $routeParams = [],
+        array $queryParams = [],
+        ?string $fragmentIdentifier = null,
+        array $options = []
+    ): string;
+
+    /**
+     * Make the current request available to the helper so that it can re-use query parameters if desired
+     */
+    public function setRequest(ServerRequestInterface $request): void;
+
+    /**
+     * Make the current routing result available to the helper so that it can re-use matched parameters if desired
+     */
+    public function setRouteResult(RouteResult $result): void;
+}
diff --git a/test/ConfigProviderTest.php b/test/ConfigProviderTest.php
@@ -11,6 +11,7 @@
 use Mezzio\Helper\Template\TemplateVariableContainerMiddleware;
 use Mezzio\Helper\UrlHelper;
 use Mezzio\Helper\UrlHelperFactory;
+use Mezzio\Helper\UrlHelperInterface;
 use Mezzio\Helper\UrlHelperMiddleware;
 use Mezzio\Helper\UrlHelperMiddlewareFactory;
 use PHPUnit\Framework\TestCase;
@@ -34,6 +35,9 @@ public function testReturnedArrayContainsDependencies(): void
                     UrlHelper::class           => UrlHelperFactory::class,
                     UrlHelperMiddleware::class => UrlHelperMiddlewareFactory::class,
                 ],
+                'aliases'    => [
+                    UrlHelperInterface::class => UrlHelper::class,
+                ],
             ],
         ], $config);
     }

diff --git a/test/UrlHelperTest.php b/test/UrlHelperTest.php
@@ -359,52 +359,18 @@ public function testBasePathIsPrependedToGeneratedPathWhenUsingRouteResult(): vo
         self::assertSame('/prefix/foo/baz', $helper());
     }
 
-    public function testGenerateProxiesToInvokeMethod(): void
+    public function testGenerateAndInvokeMethodProduceTheSameResult(): void
     {
         $routeName          = 'foo';
         $routeParams        = ['route' => 'bar'];
         $queryParams        = ['foo' => 'bar'];
         $fragmentIdentifier = 'foobar';
         $options            = ['router' => ['foobar' => 'baz'], 'reuse_result_params' => false];
 
-        $helper = new class ($this->router) extends UrlHelper
-        {
-            public bool $invoked = false;
-
-            /** {@inheritDoc} */
-            public function __invoke(
-                ?string $routeName = null,
-                array $routeParams = [],
-                array $queryParams = [],
-                ?string $fragmentIdentifier = null,
-                array $options = []
-            ): string {
-                $this->invoked = true;
-
-                return 'it worked';
-            }
-
-            /** {@inheritDoc} */
-            public function generate(
-                ?string $routeName = null,
-                array $routeParams = [],
-                array $queryParams = [],
-                ?string $fragmentIdentifier = null,
-                array $options = []
-            ): string {
-                return parent::generate($routeName, $routeParams, $queryParams, $fragmentIdentifier, $options);
-            }
-        };
-
-        self::assertFalse($helper->invoked);
-
-        $generatedPath = $helper->generate($routeName, $routeParams, $queryParams, $fragmentIdentifier, $options);
-
-        self::assertTrue($helper->invoked);
-        self::assertSame('it worked', $generatedPath);
+        $helper = $this->createHelper();
         self::assertSame(
-            'it worked',
-            $helper->__invoke($routeName, $routeParams, $queryParams, $fragmentIdentifier, $options)
+            $helper->__invoke($routeName, $routeParams, $queryParams, $fragmentIdentifier, $options),
+            $helper->generate($routeName, $routeParams, $queryParams, $fragmentIdentifier, $options),
         );
     }