[TASK] Add trait providing standard implementation of Commentable

composer.json

@@ -33,6 +33,7 @@
         "phpstan/phpstan-phpunit": "1.4.2 || 2.0.4",
         "phpstan/phpstan-strict-rules": "1.6.2 || 2.0.3",
         "phpunit/phpunit": "8.5.41",
+        "rawr/cross-data-providers": "2.4.0",
         "rector/rector": "1.2.10 || 2.0.7",
         "rector/type-perfect": "1.0.0 || 2.0.2"
     },

src/Comment/CommentContainer.php

@@ -0,0 +1,44 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Sabberworm\CSS\Comment;
+
+/**
+ * Provides a standard reusable implementation of `Commentable`.
+ *
+ * @internal
+ *
+ * @phpstan-require-implements Commentable
+ */
+trait CommentContainer
+{
+    /**
+     * @var list<Comment>
+     */
+    protected $comments = [];
+
+    /**
+     * @param list<Comment> $comments
+     */
+    public function addComments(array $comments): void
+    {
+        $this->comments = \array_merge($this->comments, $comments);
+    }
+
+    /**
+     * @return list<Comment>
+     */
+    public function getComments(): array
+    {
+        return $this->comments;
+    }
+
+    /**
+     * @param list<Comment> $comments
+     */
+    public function setComments(array $comments): void
+    {
+        $this->comments = $comments;
+    }
+}

src/Comment/Commentable.php

@@ -4,6 +4,9 @@
 
 namespace Sabberworm\CSS\Comment;
 
+/**
+ * A standard implementation of this interface is available in the `CommentContainer` trait.
+ */
 interface Commentable
 {
     /**

tests/Unit/Comment/CommentContainerTest.php

@@ -0,0 +1,232 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Sabberworm\CSS\Tests\Unit\Comment;
+
+use PHPUnit\Framework\Constraint\LogicalAnd;
+use PHPUnit\Framework\Constraint\TraversableContains;
+use PHPUnit\Framework\TestCase;
+use Sabberworm\CSS\Comment\Comment;
+use Sabberworm\CSS\Tests\Unit\Comment\Fixtures\ConcreteCommentContainer;
+use TRegx\DataProvider\DataProviders;
+
+/**
+ * @covers \Sabberworm\CSS\Comment\CommentContainer
+ */
+final class CommentContainerTest extends TestCase
+{
+    /**
+     * @var ConcreteCommentContainer
+     */
+    private $subject;
+
+    protected function setUp(): void
+    {
+        $this->subject = new ConcreteCommentContainer();
+    }
+
+    /**
+     * @test
+     */
+    public function getCommentsInitiallyReturnsEmptyArray(): void
+    {
+        self::assertSame([], $this->subject->getComments());
+    }
+
+    /**
+     * @return array<non-empty-string, array{0: list<Comment>}>
+     */
+    public function provideCommentArray(): array
+    {
+        return [
+            'no comment' => [[]],
+            'one comment' => [[new Comment('Is this really a spoon?')]],
+            'two comments' => [[
+                new Comment('I’m a teapot.'),
+                new Comment('I’m a cafetière.'),
+            ]],
+        ];
+    }
+
+    /**
+     * @test
+     *
+     * @param list<Comment> $comments
+     *
+     * @dataProvider provideCommentArray
+     */
+    public function addCommentsOnVirginContainerAddsCommentsProvided(array $comments): void
+    {
+        $this->subject->addComments($comments);
+
+        self::assertSame($comments, $this->subject->getComments());
+    }
+
+    /**
+     * @test
+     *
+     * @param list<Comment> $comments
+     *
+     * @dataProvider provideCommentArray
+     */
+    public function addCommentsWithEmptyArrayKeepsOriginalCommentsUnchanged(array $comments): void
+    {
+        $this->subject->setComments($comments);
+
+        $this->subject->addComments([]);
+
+        self::assertSame($comments, $this->subject->getComments());
+    }
+
+    /**
+     * @return array<non-empty-string, array{0: list<Comment>}>
+     */
+    public function provideAlternativeCommentArray(): array
+    {
+        return [
+            'no comment' => [[]],
+            'one comment' => [[new Comment('Can I eat it with my hands?')]],
+            'two comments' => [[
+                new Comment('I’m a beer barrel.'),
+                new Comment('I’m a vineyard.'),
+            ]],
+        ];
+    }
+
+    /**
+     * @return array<non-empty-string, array{0: non-empty-list<Comment>}>
+     */
+    public function provideAlternativeNonemptyCommentArray(): array
+    {
+        $data = $this->provideAlternativeCommentArray();
+
+        unset($data['no comment']);
+
+        return $data;
+    }
+
+    /**
+     * This provider crosses two comment arrays (0, 1 or 2 comments) with different comments,
+     * so that all combinations can be tested.
+     *
+     * @return array<non-empty-string, array{0: list<Comment>, 1: list<Comment>}>
+     */
+    public function provideTwoDistinctCommentArrays(): array
+    {
+        return DataProviders::cross($this->provideCommentArray(), $this->provideAlternativeCommentArray());
+    }
+
+    /**
+     * @return array<non-empty-string, array{0: list<Comment>, 1: non-empty-list<Comment>}>
+     */
+    public function provideTwoDistinctCommentArraysWithSecondNonempty(): array
+    {
+        return DataProviders::cross($this->provideCommentArray(), $this->provideAlternativeNonemptyCommentArray());
+    }
+
+    private static function createContainsContstraint(Comment $comment): TraversableContains
+    {
+        return new TraversableContains($comment);
+    }
+
+    /**
+     * @param non-empty-list<Comment> $comments
+     *
+     * @return non-empty-list<TraversableContains>
+     */
+    private static function createContainsContstraints(array $comments): array
+    {
+        return \array_map([self::class, 'createContainsContstraint'], $comments);
+    }
+
+    /**
+     * @test
+     *
+     * @param list<Comment> $commentsToAdd
+     * @param non-empty-list<Comment> $originalComments
+     *
+     * @dataProvider provideTwoDistinctCommentArraysWithSecondNonempty
+     */
+    public function addCommentsKeepsOriginalComments(array $commentsToAdd, array $originalComments): void
+    {
+        $this->subject->setComments($originalComments);
+
+        $this->subject->addComments($commentsToAdd);
+
+        self::assertThat(
+            $this->subject->getComments(),
+            LogicalAnd::fromConstraints(...self::createContainsContstraints($originalComments))
+        );
+    }
+
+    /**
+     * @test
+     *
+     * @param list<Comment> $originalComments
+     * @param non-empty-list<Comment> $commentsToAdd
+     *
+     * @dataProvider provideTwoDistinctCommentArraysWithSecondNonempty
+     */
+    public function addCommentsAfterCommentsSetAddsCommentsProvided(array $originalComments, array $commentsToAdd): void
+    {
+        $this->subject->setComments($originalComments);
+
+        $this->subject->addComments($commentsToAdd);
+
+        self::assertThat(
+            $this->subject->getComments(),
+            LogicalAnd::fromConstraints(...self::createContainsContstraints($commentsToAdd))
+        );
+    }
+
+    /**
+     * @test
+     *
+     * @param non-empty-list<Comment> $comments
+     *
+     * @dataProvider provideAlternativeNonemptyCommentArray
+     */
+    public function addCommentsAppends(array $comments): void
+    {
+        $firstComment = new Comment('I must be first!');
+        $this->subject->setComments([$firstComment]);
+
+        $this->subject->addComments($comments);
+
+        $result = $this->subject->getComments();
+        self::assertNotEmpty($result);
+        self::assertSame($firstComment, $result[0]);
+    }
+
+    /**
+     * @test
+     *
+     * @param list<Comment> $comments
+     *
+     * @dataProvider provideCommentArray
+     */
+    public function setCommentsOnVirginContainerSetsCommentsProvided(array $comments): void
+    {
+        $this->subject->setComments($comments);
+
+        self::assertSame($comments, $this->subject->getComments());
+    }
+
+    /**
+     * @test
+     *
+     * @param list<Comment> $originalComments
+     * @param list<Comment> $commentsToSet
+     *
+     * @dataProvider provideTwoDistinctCommentArrays
+     */
+    public function setCommentsReplacesWithCommentsProvided(array $originalComments, array $commentsToSet): void
+    {
+        $this->subject->setComments($originalComments);
+
+        $this->subject->setComments($commentsToSet);
+
+        self::assertSame($commentsToSet, $this->subject->getComments());
+    }
+}

tests/Unit/Comment/Fixtures/ConcreteCommentContainer.php

@@ -0,0 +1,13 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Sabberworm\CSS\Tests\Unit\Comment\Fixtures;
+
+use Sabberworm\CSS\Comment\Commentable;
+use Sabberworm\CSS\Comment\CommentContainer;
+
+final class ConcreteCommentContainer implements Commentable
+{
+    use CommentContainer;
+}