feature #49798 [HttpClient] Add ServerSentEvent::getArrayData() to get the SSE's data decoded as an array directly (fancyweb)

This PR was merged into the 6.3 branch.

Discussion
----------

[HttpClient] Add ServerSentEvent::getArrayData() to get the SSE's data decoded as an array directly

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

Although the data field in SSEs can be "anything", it's really common that it's a JSON payload.

Just like we have a shortcut in responses (`ResponseInterface::toArray()`), I think it's worth having a shortcut in `ServerSentEvent` to avoid writing boilerplate code again and again 😅

Commits
-------

cdbf939210 [HttpClient] Add ServerSentEvent::getArrayData() to get the SSE's data decoded as an array directly

Author: nicolas-grekas

CHANGELOG.md

@@ -5,6 +5,7 @@ CHANGELOG
 ---
 
  * Add `UriTemplateHttpClient` to use URI templates as specified in the RFC 6570
+ * Add `ServerSentEvent::getArrayData()` to get the Server-Sent Event's data decoded as an array when it's a JSON payload
 
 6.2
 ---

Chunk/ServerSentEvent.php

@@ -11,6 +11,7 @@
 
 namespace Symfony\Component\HttpClient\Chunk;
 
+use Symfony\Component\HttpClient\Exception\JsonException;
 use Symfony\Contracts\HttpClient\ChunkInterface;
 
 /**
@@ -23,6 +24,7 @@ final class ServerSentEvent extends DataChunk implements ChunkInterface
     private string $id = '';
     private string $type = 'message';
     private float $retry = 0;
+    private ?array $jsonData = null;
 
     public function __construct(string $content)
     {
@@ -76,4 +78,30 @@ public function getRetry(): float
     {
         return $this->retry;
     }
+
+    /**
+     * Gets the SSE data decoded as an array when it's a JSON payload.
+     */
+    public function getArrayData(): array
+    {
+        if (null !== $this->jsonData) {
+            return $this->jsonData;
+        }
+
+        if ('' === $this->data) {
+            throw new JsonException(sprintf('Server-Sent Event%s data is empty.', '' !== $this->id ? sprintf(' "%s"', $this->id) : ''));
+        }
+
+        try {
+            $jsonData = json_decode($this->data, true, 512, \JSON_BIGINT_AS_STRING | \JSON_THROW_ON_ERROR);
+        } catch (\JsonException $e) {
+            throw new JsonException(sprintf('Decoding Server-Sent Event%s failed: ', '' !== $this->id ? sprintf(' "%s"', $this->id) : '').$e->getMessage(), $e->getCode());
+        }
+
+        if (!\is_array($jsonData)) {
+            throw new JsonException(sprintf('JSON content was expected to decode to an array, "%s" returned in Server-Sent Event%s.', get_debug_type($jsonData), '' !== $this->id ? sprintf(' "%s"', $this->id) : ''));
+        }
+
+        return $this->jsonData = $jsonData;
+    }
 }

Tests/Chunk/ServerSentEventTest.php

@@ -13,6 +13,7 @@
 
 use PHPUnit\Framework\TestCase;
 use Symfony\Component\HttpClient\Chunk\ServerSentEvent;
+use Symfony\Component\HttpClient\Exception\JsonException;
 
 /**
  * @author Antoine Bluchet <soyuka@gmail.com>
@@ -76,4 +77,45 @@ public function testParseNewLine()
         $sse = new ServerSentEvent($rawData);
         $this->assertSame("<tag>\n\n  <foo />\n\n\n</tag>", $sse->getData());
     }
+
+    public function testGetArrayData()
+    {
+        $this->assertSame(['foo' => 'bar'], (new ServerSentEvent(<<<STR
+id: 33
+data: {"foo": "bar"}
+STR
+        ))->getArrayData());
+    }
+
+    public function testGetArrayDataWithNoContent()
+    {
+        $this->expectException(JsonException::class);
+        $this->expectExceptionMessage('Server-Sent Event data is empty.');
+
+        (new ServerSentEvent(''))->getArrayData();
+    }
+
+    public function testGetArrayDataWithInvalidJson()
+    {
+        $this->expectException(JsonException::class);
+        $this->expectExceptionMessage('Decoding Server-Sent Event "33" failed: Syntax error');
+
+        (new ServerSentEvent(<<<STR
+id: 33
+data: foobarccc
+STR
+        ))->getArrayData();
+    }
+
+    public function testGetArrayDataWithNonArrayJson()
+    {
+        $this->expectException(JsonException::class);
+        $this->expectExceptionMessage('JSON content was expected to decode to an array, "string" returned in Server-Sent Event "33".');
+
+        (new ServerSentEvent(<<<STR
+id: 33
+data: "ccc"
+STR
+        ))->getArrayData();
+    }
 }