[WebLink] Add class to parse Link headers from HTTP responses

symfony · GromNaN · May 27, 2025 · May 14, 2025 · May 27, 2025 · 461f7930053f4a09ea3c52cf7cbf1f23d729dfa6
commit 461f7930053f4a09ea3c52cf7cbf1f23d729dfa6
diff --git a/src/Symfony/Bundle/FrameworkBundle/DependencyInjection/FrameworkExtension.php b/src/Symfony/Bundle/FrameworkBundle/DependencyInjection/FrameworkExtension.php
@@ -216,6 +216,7 @@
 use Symfony\Component\Validator\ObjectInitializerInterface;
 use Symfony\Component\Validator\Validation;
 use Symfony\Component\Webhook\Controller\WebhookController;
+use Symfony\Component\WebLink\HttpHeaderParser;
 use Symfony\Component\WebLink\HttpHeaderSerializer;
 use Symfony\Component\Workflow;
 use Symfony\Component\Workflow\WorkflowInterface;
@@ -497,6 +498,11 @@ public function load(array $configs, ContainerBuilder $container): void
             }
 
             $loader->load('web_link.php');
+
+            // Require symfony/web-link 7.4
+            if (!class_exists(HttpHeaderParser::class)) {
+                $container->removeDefinition('web_link.http_header_parser');
+            }
         }
 
         if ($this->readConfigEnabled('uid', $container, $config['uid'])) {

diff --git a/src/Symfony/Bundle/FrameworkBundle/Resources/config/web_link.php b/src/Symfony/Bundle/FrameworkBundle/Resources/config/web_link.php
@@ -12,6 +12,7 @@
 namespace Symfony\Component\DependencyInjection\Loader\Configurator;
 
 use Symfony\Component\WebLink\EventListener\AddLinkHeaderListener;
+use Symfony\Component\WebLink\HttpHeaderParser;
 use Symfony\Component\WebLink\HttpHeaderSerializer;
 
 return static function (ContainerConfigurator $container) {
@@ -20,6 +21,9 @@
         ->set('web_link.http_header_serializer', HttpHeaderSerializer::class)
         ->alias(HttpHeaderSerializer::class, 'web_link.http_header_serializer')
 
+        ->set('web_link.http_header_parser', HttpHeaderParser::class)
+        ->alias(HttpHeaderParser::class, 'web_link.http_header_parser')
+
         ->set('web_link.add_link_header_listener', AddLinkHeaderListener::class)
             ->args([
                 service('web_link.http_header_serializer'),

@@ -1,6 +1,12 @@
 CHANGELOG
 =========
 
+7.4
+---
+
+ * Add `HttpHeaderParser` to read `Link` headers from HTTP responses
+ * Make `HttpHeaderSerializer` non-final
+
 4.4.0
 -----
 

@@ -0,0 +1,87 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\WebLink;
+
+use Psr\Link\EvolvableLinkProviderInterface;
+
+/**
+ * Parse a list of HTTP Link headers into a list of Link instances.
+ *
+ * @see https://tools.ietf.org/html/rfc5988
+ *
+ * @author Jérôme Tamarelle <jerome@tamarelle.net>
+ */
+class HttpHeaderParser
+{
+    // Regex to match each link entry: <...>; param1=...; param2=...
+    private const LINK_PATTERN = '/<([^>]*)>\s*((?:\s*;\s*[a-zA-Z0-9\-_]+(?:\s*=\s*(?:"(?:[^"\\\\]|\\\\.)*"|[^";,\s]+))?)*)/';
+
+    // Regex to match parameters: ; key[=value]
+    private const PARAM_PATTERN = '/;\s*([a-zA-Z0-9\-_]+)(?:\s*=\s*(?:"((?:[^"\\\\]|\\\\.)*)"|([^";,\s]+)))?/';
+
+    /**
+     * @param string|string[] $headers Value of the "Link" HTTP header
+     */
+    public function parse(string|array $headers): EvolvableLinkProviderInterface
+    {
+        if (is_array($headers)) {
+            $headers = implode(', ', $headers);
+        }
+        $links = new GenericLinkProvider();
+
+        if (!preg_match_all(self::LINK_PATTERN, $headers, $matches, \PREG_SET_ORDER)) {
+            return $links;
+        }
+
+        foreach ($matches as $match) {
+            $href = $match[1];
+            $attributesString = $match[2];
+
+            $attributes = [];
+            if (preg_match_all(self::PARAM_PATTERN, $attributesString, $attributeMatches, \PREG_SET_ORDER)) {
+                $rels = null;
+                foreach ($attributeMatches as $pm) {
+                    $key = $pm[1];
+                    $value = match (true) {
+                        // Quoted value, unescape quotes
+                        ($pm[2] ?? '') !== '' => stripcslashes($pm[2]),
+                        ($pm[3] ?? '') !== '' => $pm[3],
+                        // No value
+                        default => true,
+                    };
+
+                    if ($key === 'rel') {
+                        // Only the first occurrence of the "rel" attribute is read
+                        $rels ??= $value === true ? [] : preg_split('/\s+/', $value, 0, \PREG_SPLIT_NO_EMPTY);
+                    } elseif (is_array($attributes[$key] ?? null)) {
+                        $attributes[$key][] = $value;
+                    } elseif (isset($attributes[$key])) {
+                        $attributes[$key] = [$attributes[$key], $value];
+                    } else {
+                        $attributes[$key] = $value;
+                    }
+                }
+            }
+
+            $link = new Link(null, $href);
+            foreach ($rels ?? [] as $rel) {
+                $link = $link->withRel($rel);
+            }
+            foreach ($attributes as $k => $v) {
+                $link = $link->withAttribute($k, $v);
+            }
+            $links = $links->withLink($link);
+        }
+
+        return $links;
+    }
+}
@@ -20,7 +20,7 @@
  *
  * @author Kévin Dunglas <dunglas@gmail.com>
  */
-final class HttpHeaderSerializer
+class HttpHeaderSerializer
 {
     /**
      * Builds the value of the "Link" HTTP header.

@@ -153,7 +153,7 @@ class Link implements EvolvableLinkInterface
     private array $rel = [];
 
     /**
-     * @var array<string, string|bool|string[]>
+     * @var array<string, scalar|\Stringable|list<scalar|\Stringable>>
      */
     private array $attributes = [];
 
@@ -181,6 +181,11 @@ public function getRels(): array
         return array_values($this->rel);
     }
 
+    /**
+     * Returns a list of attributes that describe the target URI.
+     *
+     * @return array<string, scalar|\Stringable|list<scalar|\Stringable>>
+     */
     public function getAttributes(): array
     {
         return $this->attributes;
@@ -210,6 +215,14 @@ public function withoutRel(string $rel): static
         return $that;
     }
 
+    /**
+     * Returns an instance with the specified attribute added.
+     *
+     * If the specified attribute is already present, it will be overwritten
+     * with the new value.
+     *
+     * @param scalar|\Stringable|list<scalar|\Stringable> $value
+     */
     public function withAttribute(string $attribute, string|\Stringable|int|float|bool|array $value): static
     {
         $that = clone $this;

@@ -0,0 +1,112 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\WebLink\Tests;
+
+use PHPUnit\Framework\Attributes\DataProvider;
+use PHPUnit\Framework\TestCase;
+use Symfony\Component\WebLink\HttpHeaderParser;
+
+class HttpHeaderParserTest extends TestCase
+{
+    public function testParse()
+    {
+        $parser = new HttpHeaderParser();
+
+        $header = [
+            '</1>; rel="prerender",</2>; rel="dns-prefetch"; pr="0.7",</3>; rel="preload"; as="script"',
+            '</4>; rel="preload"; as="image"; nopush,</5>; rel="alternate next"; hreflang="fr"; hreflang="de"; title="Hello"'
+        ];
+        $provider = $parser->parse($header);
+        $links = $provider->getLinks();
+
+        self::assertCount(5, $links);
+
+        self::assertSame(['prerender'], $links[0]->getRels());
+        self::assertSame('/1', $links[0]->getHref());
+        self::assertSame([], $links[0]->getAttributes());
+
+        self::assertSame(['dns-prefetch'], $links[1]->getRels());
+        self::assertSame('/2', $links[1]->getHref());
+        self::assertSame(['pr' => '0.7'], $links[1]->getAttributes());
+
+        self::assertSame(['preload'], $links[2]->getRels());
+        self::assertSame('/3', $links[2]->getHref());
+        self::assertSame(['as' => 'script'], $links[2]->getAttributes());
+
+        self::assertSame(['preload'], $links[3]->getRels());
+        self::assertSame('/4', $links[3]->getHref());
+        self::assertSame(['as' => 'image', 'nopush' => true], $links[3]->getAttributes());
+
+        self::assertSame(['alternate', 'next'], $links[4]->getRels());
+        self::assertSame('/5', $links[4]->getHref());
+        self::assertSame(['hreflang' => ['fr', 'de'], 'title' => 'Hello'], $links[4]->getAttributes());
+    }
+
+    public function testParseEmpty()
+    {
+        $parser = new HttpHeaderParser();
+        $provider = $parser->parse('');
+        self::assertCount(0, $provider->getLinks());
+    }
+
+    /** @dataProvider provideHeaderParsingCases */
+    #[DataProvider('provideHeaderParsingCases')]
+    public function testParseVariousAttributes(string $header, array $expectedRels, array $expectedAttributes)
+    {
+        $parser = new HttpHeaderParser();
+        $links = $parser->parse($header)->getLinks();
+
+        self::assertCount(1, $links);
+        self::assertSame('/foo', $links[0]->getHref());
+        self::assertSame($expectedRels, $links[0]->getRels());
+        self::assertSame($expectedAttributes, $links[0]->getAttributes());
+    }
+
+    public static function provideHeaderParsingCases()
+    {
+        yield 'double_quotes_in_attribute_value' => [
+            '</foo>; rel="alternate"; title="\"escape me\" \"already escaped\" \"\"\""',
+            ['alternate'],
+            ['title' => '"escape me" "already escaped" """'],
+        ];
+
+        yield 'unquoted_attribute_value' => [
+            '</foo>; rel=alternate; type=text/html',
+            ['alternate'],
+            ['type' => 'text/html'],
+        ];
+
+        yield 'attribute_with_punctuation' => [
+            '</foo>; rel="alternate"; title=">; hello, world; test:case"',
+            ['alternate'],
+            ['title' => '>; hello, world; test:case'],
+        ];
+
+        yield 'no_rel' => [
+            '</foo>; type=text/html',
+            [],
+            ['type' => 'text/html'],
+        ];
+
+        yield 'empty_rel' => [
+            '</foo>; rel',
+            [],
+            [],
+        ];
+
+        yield 'multiple_rel_attributes_get_first' => [
+            '</foo>; rel="alternate" rel="next"',
+            ['alternate'],
+            [],
+        ];
+    }
+}
@@ -27,10 +27,10 @@ public function testCanSetAndRetrieveValues()
             ->withAttribute('me', 'you')
         ;
 
-        $this->assertEquals('http://www.google.com', $link->getHref());
+        $this->assertSame('http://www.google.com', $link->getHref());
         $this->assertContains('next', $link->getRels());
         $this->assertArrayHasKey('me', $link->getAttributes());
-        $this->assertEquals('you', $link->getAttributes()['me']);
+        $this->assertSame('you', $link->getAttributes()['me']);
     }
 
     public function testCanRemoveValues()
@@ -44,7 +44,7 @@ public function testCanRemoveValues()
         $link = $link->withoutAttribute('me')
             ->withoutRel('next');
 
-        $this->assertEquals('http://www.google.com', $link->getHref());
+        $this->assertSame('http://www.google.com', $link->getHref());
         $this->assertFalse(\in_array('next', $link->getRels(), true));
         $this->assertArrayNotHasKey('me', $link->getAttributes());
     }
@@ -65,7 +65,7 @@ public function testConstructor()
     {
         $link = new Link('next', 'http://www.google.com');
 
-        $this->assertEquals('http://www.google.com', $link->getHref());
+        $this->assertSame('http://www.google.com', $link->getHref());
         $this->assertContains('next', $link->getRels());
     }