feature #46514 [HttpKernel] Add option to render Surrogate fragment with absolute URIs (Kern046)

This PR was merged into the 6.2 branch.

Discussion
----------

[HttpKernel] Add option to render Surrogate fragment with absolute URIs

| Q             | A
| ------------- | ---
| Branch?       | 6.2
| Bug fix?      | no
| New feature?  | yes
| Deprecations? | no
| Tickets       |
| License       | MIT
| Doc PR        |

Context
-------

Using ESI blocks with Cloudflare Workers we faced an issue with the `/_fragment` relative URIs, as Cloudflare didn't succeed to handle it. We needed the absolute URL to make it work.

Proposed solution
--------

In Symfony's codebase I noticed that `Symfony\Component\HttpKernel\Fragment\FragmentUriGenerator::generate` already supports a `$absolute` parameter to fit the needs of `fragment_uri` Twig function (I even wonder if this wasn't a previously supported feature when I see #8879), but this parameter couldn't be set through `render_esi`.

This PR adds the support of a new `absolute_uri` option in order to set this parameter and get an absolute URI for ESI and SSI fragments. It only applies when using a `ControllerReference` as the URI or `alt` option. It defaults to `false` to avoid causing any BC break.

### Naming

I am not that confident about the naming:

- I used `absolute_uri` for the option to keep it more self-descriptive than just `absolute`.
- I used `$absolute` to keep it more consistent with the existing parameters and usage in `HttpKernelRuntime::generateFragmentUri`.

I have doubts about the pertinence of such a diff between the option and the variable name. Let me know what you think about it !

Commits
-------

f9f3ed0 [HttpKernel] Add option to render Surrogate fragment with absolute URIs

Author: fabpot

src/Symfony/Component/HttpKernel/CHANGELOG.md

@@ -7,6 +7,7 @@ CHANGELOG
  * Add constructor argument `bool $catchThrowable` to `HttpKernel`
  * Add `ControllerEvent::getAttributes()` to handle attributes on controllers
  * Add `#[Cache]` to describe the default HTTP cache headers on controllers
+ * Add `absolute_uri` option to surrogate fragment renderers
 
 6.1
 ---

src/Symfony/Component/HttpKernel/Fragment/AbstractSurrogateFragmentRenderer.php

@@ -51,6 +51,7 @@ public function __construct(SurrogateInterface $surrogate = null, FragmentRender
      *
      *  * alt: an alternative URI to render in case of an error
      *  * comment: a comment to add when returning the surrogate tag
+     *  * absolute_uri: whether to generate an absolute URI or not. Default is false
      *
      * Note, that not all surrogate strategies support all options. For now
      * 'alt' and 'comment' are only supported by ESI.
@@ -67,23 +68,25 @@ public function render(string|ControllerReference $uri, Request $request, array
             return $this->inlineStrategy->render($uri, $request, $options);
         }
 
+        $absolute = $options['absolute_uri'] ?? false;
+
         if ($uri instanceof ControllerReference) {
-            $uri = $this->generateSignedFragmentUri($uri, $request);
+            $uri = $this->generateSignedFragmentUri($uri, $request, $absolute);
         }
 
         $alt = $options['alt'] ?? null;
         if ($alt instanceof ControllerReference) {
-            $alt = $this->generateSignedFragmentUri($alt, $request);
+            $alt = $this->generateSignedFragmentUri($alt, $request, $absolute);
         }
 
         $tag = $this->surrogate->renderIncludeTag($uri, $alt, $options['ignore_errors'] ?? false, $options['comment'] ?? '');
 
         return new Response($tag);
     }
 
-    private function generateSignedFragmentUri(ControllerReference $uri, Request $request): string
+    private function generateSignedFragmentUri(ControllerReference $uri, Request $request, bool $absolute): string
     {
-        return (new FragmentUriGenerator($this->fragmentPath, $this->signer))->generate($uri, $request);
+        return (new FragmentUriGenerator($this->fragmentPath, $this->signer))->generate($uri, $request, $absolute);
     }
 
     private function containsNonScalars(array $values): bool

src/Symfony/Component/HttpKernel/Tests/Fragment/EsiFragmentRendererTest.php

@@ -66,6 +66,24 @@ public function testRenderControllerReference()
         );
     }
 
+    public function testRenderControllerReferenceWithAbsoluteUri()
+    {
+        $signer = new UriSigner('foo');
+        $strategy = new EsiFragmentRenderer(new Esi(), $this->getInlineStrategy(), $signer);
+
+        $request = Request::create('http://localhost/');
+        $request->setLocale('fr');
+        $request->headers->set('Surrogate-Capability', 'ESI/1.0');
+
+        $reference = new ControllerReference('main_controller', [], []);
+        $altReference = new ControllerReference('alt_controller', [], []);
+
+        $this->assertSame(
+            '<esi:include src="http://localhost/_fragment?_hash=Jz1P8NErmhKTeI6onI1EdAXTB85359MY3RIk5mSJ60w%3D&_path=_format%3Dhtml%26_locale%3Dfr%26_controller%3Dmain_controller" alt="http://localhost/_fragment?_hash=iPJEdRoUpGrM1ztqByiorpfMPtiW%2FOWwdH1DBUXHhEc%3D&_path=_format%3Dhtml%26_locale%3Dfr%26_controller%3Dalt_controller" />',
+            $strategy->render($reference, $request, ['alt' => $altReference, 'absolute_uri' => true])->getContent()
+        );
+    }
+
     public function testRenderControllerReferenceWithoutSignerThrowsException()
     {
         $this->expectException(\LogicException::class);

src/Symfony/Component/HttpKernel/Tests/Fragment/SsiFragmentRendererTest.php

@@ -57,6 +57,24 @@ public function testRenderControllerReference()
         );
     }
 
+    public function testRenderControllerReferenceWithAbsoluteUri()
+    {
+        $signer = new UriSigner('foo');
+        $strategy = new SsiFragmentRenderer(new Ssi(), $this->getInlineStrategy(), $signer);
+
+        $request = Request::create('http://localhost/');
+        $request->setLocale('fr');
+        $request->headers->set('Surrogate-Capability', 'SSI/1.0');
+
+        $reference = new ControllerReference('main_controller', [], []);
+        $altReference = new ControllerReference('alt_controller', [], []);
+
+        $this->assertSame(
+            '<!--#include virtual="http://localhost/_fragment?_hash=Jz1P8NErmhKTeI6onI1EdAXTB85359MY3RIk5mSJ60w%3D&_path=_format%3Dhtml%26_locale%3Dfr%26_controller%3Dmain_controller" -->',
+            $strategy->render($reference, $request, ['alt' => $altReference, 'absolute_uri' => true])->getContent()
+        );
+    }
+
     public function testRenderControllerReferenceWithoutSignerThrowsException()
     {
         $this->expectException(\LogicException::class);