Support multi-line comments

Comments are now stored as a single (optionally multi-line) string, instead of an array of strings, to make it more consistent with the data field.

Author: devfrey

src/BufferedEventStream.php

@@ -62,9 +62,9 @@ public function disconnect(WritableStreamInterface $stream): void
      */
     public function send(Event $event): void
     {
-        // Skip buffering events that only consist of comments, such as the
+        // Skip buffering events that only consist of a comment, such as the
         // keep-alive event.
-        if (! $event->consistsOnlyOfComments()) {
+        if (! $event->consistsOnlyOfComment()) {
             $this->lastEventId++;
 
             $event = $event->id($this->lastEventId);

src/Encoder.php

@@ -10,24 +10,24 @@ class Encoder
     /**
      * Encode given fields into an event.
      *
-     * @param  array<string>  $comments
+     * @param  string  $comment
      * @param  string|null  $event
      * @param  string  $data
      * @param  string  $id
      * @param  int|null  $retry
      * @return string
      */
     public function __invoke(
-        array $comments,
+        string $comment,
         ?string $event,
         string $data,
         string $id,
         ?int $retry
     ): string {
         $encoded = '';
 
-        foreach ($comments as $comment) {
-            $encoded .= ":{$comment}\n";
+        foreach ($this->explodeLineBreaks($comment) as $line) {
+            $encoded .= ":{$line}\n";
         }
 
         if (! is_null($event)) {
@@ -50,11 +50,11 @@ public function __invoke(
     }
 
     /**
-     * Line breaks within a data field are not permitted, because they would indicate the end of a field (or even a
-     * block). Therefore every line break should result in an additional data field.
+     * Line breaks within comments and data fields are not permitted, because they would indicate the end of a field
+     * (or even a block). Therefore every line break should result in an additional comment or data field.
      *
      * @param  string  $data
-     * @return array
+     * @return array<string>
      */
     protected function explodeLineBreaks(string $data): array
     {

src/Event.php

@@ -10,8 +10,8 @@ final class Event
     /** @var string|null */
     private $event;
 
-    /** @var array<string> */
-    private $comments = [];
+    /** @var string */
+    private $comment = '';
 
     /** @var string */
     private $data = '';
@@ -28,23 +28,23 @@ public function __construct(?string $event = null)
     }
 
     /**
-     * Append one or more comments.
+     * Set the event comment, supports line breaks.
      * Do not prefix comments with a colon – this is done by the encoder.
      *
-     * @param  string  ...$comments
+     * @param  string  $comment
      * @return self
      */
-    public function comment(string ...$comments): self
+    public function comment(string $comment): self
     {
         $clone = clone $this;
 
-        array_push($clone->comments, ...$comments);
+        $clone->comment = $comment;
 
         return $clone;
     }
 
     /**
-     * Set the event data.
+     * Set the event data, supports line breaks.
      *
      * @param  string  $data
      * @return $this
@@ -96,7 +96,7 @@ public function retry(?int $retry): self
     public function toString(Encoder $encoder): string
     {
         return $encoder(
-            $this->comments,
+            $this->comment,
             $this->event,
             $this->data,
             $this->id,
@@ -105,16 +105,16 @@ public function toString(Encoder $encoder): string
     }
 
     /**
-     * Determine if this event consists only of comments.
+     * Determine if this event consists only of a comment.
      *
      * @return bool
      */
-    public function consistsOnlyOfComments(): bool
+    public function consistsOnlyOfComment(): bool
     {
         return is_null($this->event)
             && is_null($this->retry)
             && $this->data === ''
-            && $this->comments !== [];
+            && $this->comment !== '';
     }
 }
 

tests/EncoderTest.php

@@ -83,11 +83,11 @@ public function single_comment()
     }
 
     /** @test */
-    public function multiple_comments()
+    public function multi_line_comments()
     {
         $event = (new Event())->comment(
-            'This is a comment',
-            'And this too.'
+            "This is a comment\n" .
+            "And this too."
         );
 
         self::assertEquals(

tests/EventTest.php

@@ -0,0 +1,35 @@
+<?php
+
+namespace Tests;
+
+use Devfrey\FrameworkX\EventSource\Event;
+use PHPUnit\Framework\TestCase;
+
+final class EventTest extends TestCase
+{
+    /** @test */
+    public function consistsOnlyOfComment_returns_true_for_an_event_with_only_a_comment()
+    {
+        $event = (new Event())->comment('Test');
+
+        self::assertTrue($event->consistsOnlyOfComment());
+    }
+
+    /** @test */
+    public function consistsOnlyOfComment_returns_false_for_an_event_with_data()
+    {
+        $event = (new Event())
+            ->data('foo')
+            ->comment('bar');
+
+        self::assertFalse($event->consistsOnlyOfComment());
+    }
+
+    /** @test */
+    public function consistsOnlyOfComment_returns_false_for_an_empty_event()
+    {
+        $event = new Event();
+
+        self::assertFalse($event->consistsOnlyOfComment());
+    }
+}