[FEATURE] Support for inserting an item in a CSSList

Signed-off-by: Daniel Ziegenberg <daniel@ziegenberg.at>
Co-authored-by: Frederic Massart <fred@moodle.com>

Author: ziegenberg

src/CSSList/CSSList.php

@@ -296,6 +296,27 @@ public function splice($iOffset, $iLength = null, $mReplacement = null)
         array_splice($this->aContents, $iOffset, $iLength, $mReplacement);
     }
 
+    /**
+     * Insert an item before or after its sibling.
+     *
+     * @param RuleSet|CSSList|Import|Charset $oItem The item.
+     * @param RuleSet|CSSList|Import|Charset $oSibling The sibling.
+     * @param string $sPosition The position.
+     *
+     * @return void
+     */
+    public function insert(mixed $oItem, mixed $oSibling, string $sPosition = 'before'): void
+    {
+        $iIndex = in_array($oSibling, $this->aContents);
+        if ($iIndex === false) {
+            $this->append($oItem);
+        } else if ($sPosition === 'before') {
+            $this->replace($oSibling, array($oItem, $oSibling));
+        } else {
+            $this->replace($oSibling, array($oSibling, $oItem));
+        }
+    }
+
     /**
      * Removes an item from the CSS list.
      *

tests/CSSList/DocumentTest.php

@@ -2,6 +2,7 @@
 
 namespace Sabberworm\CSS\Tests\CSSList;
 
+use Generator;
 use PHPUnit\Framework\TestCase;
 use Sabberworm\CSS\Comment\Commentable;
 use Sabberworm\CSS\CSSList\Document;
@@ -85,4 +86,72 @@ public function setContentsReplacesContentsSetInPreviousCall()
 
         self::assertSame($contents2, $this->subject->getContents());
     }
+
+    /**
+     * @return Generator
+     */
+    public static function insertDataProvider(): Generator
+    {
+
+        $bogusOne = new DeclarationBlock();
+        $bogusOne->setSelectors('.bogus-one');
+        $bogusTwo = new DeclarationBlock();
+        $bogusTwo->setSelectors('.bogus-two');
+
+        $oItem = new DeclarationBlock();
+        $oItem->setSelectors('.item');
+
+        $oSibling = new DeclarationBlock();
+        $oSibling->setSelectors('.sibling');
+
+        $oOrphan = new DeclarationBlock();
+        $oOrphan->setSelectors('.forever-alone');
+
+        yield 'insert before' => [
+            'initialContent' => [$bogusOne, $oSibling, $bogusTwo],
+            'oItem' => $oItem,
+            'oSibling' => $oSibling,
+            'position' => 'before',
+            'expectedContent' => [$bogusOne, $oItem, $oSibling, $bogusTwo],
+            ];
+        yield 'insert after' => [
+            'initialContent' => [$bogusOne, $oSibling, $bogusTwo],
+            'oItem' => $oItem,
+            'oSibling' => $oSibling,
+            'position' => 'after',
+            'expectedContent' => [$bogusOne, $oSibling, $oItem, $bogusTwo],
+            ];
+        yield 'append if not found' => [
+            'initialContent' => [$bogusOne, $oSibling, $bogusTwo],
+            'oItem' => $oItem,
+            'oSibling' => $oOrphan,
+            'position' => 'before',
+            'expectedContent' => [$bogusOne, $oSibling, $bogusTwo, $oItem],
+            ];
+    }
+
+    /**
+     * @test
+     *
+     * @param array $contents
+     * 
+     * @dataProvider insertDataProvider
+     */
+    public function insertContent(
+        array $initialContent,
+        DeclarationBlock $oItem,
+        DeclarationBlock $oSibling,
+        string $sPosition,
+        array $expectedContent
+    ) {
+
+        $this->subject->setContents($initialContent);
+
+        $this->assertCount(3, $this->subject->getContents());
+
+        $this->subject->insert($oItem, $oSibling, $sPosition);
+
+        $this->assertCount(4, $this->subject->getContents());
+        $this->assertSame($expectedContent, $this->subject->getContents());
+    }
 }