[TASK] Add (and use) a CSSListItem type

This allows a single type to be used for the contents of a `CSSList`,
instead of a long list of orred types, and helps with static analysis.

Various `assertInstanceOf()` tests are added to the test cases to confirm that
the list items are of the type expected.

Some `implements` and `exetends` lists are now alphabetically sorted.

Author: JakeQZ

config/phpstan-baseline.neon

@@ -18,6 +18,12 @@ parameters:
 			count: 1
 			path: ../src/CSSList/CSSList.php
 
+		-
+			message: '#^Parameters should have "Sabberworm\\CSS\\CSSList\\CSSListItem\|array" types as the only types passed to this method$#'
+			identifier: typePerfect.narrowPublicClassMethodParamType
+			count: 1
+			path: ../src/CSSList/CSSList.php
+
 		-
 			message: '#^Short ternary operator is not allowed\. Use null coalesce operator if applicable or consider using long ternary\.$#'
 			identifier: ternary.shortNotAllowed
@@ -48,24 +54,12 @@ parameters:
 			count: 1
 			path: ../src/RuleSet/DeclarationBlock.php
 
-		-
-			message: '#^Returning false in non return bool class method\. Use null with type\|null instead or add bool return type$#'
-			identifier: typePerfect.nullOverFalse
-			count: 1
-			path: ../src/RuleSet/DeclarationBlock.php
-
 		-
 			message: '#^Only booleans are allowed in a negated boolean, string\|null given\.$#'
 			identifier: booleanNot.exprNotBoolean
 			count: 2
 			path: ../src/RuleSet/RuleSet.php
 
-		-
-			message: '#^Parameters should have "Sabberworm\\CSS\\Rule\\Rule" types as the only types passed to this method$#'
-			identifier: typePerfect.narrowPublicClassMethodParamType
-			count: 1
-			path: ../src/RuleSet/RuleSet.php
-
 		-
 			message: '#^Parameters should have "string" types as the only types passed to this method$#'
 			identifier: typePerfect.narrowPublicClassMethodParamType

src/CSSList/CSSList.php

@@ -31,7 +31,7 @@
  *
  * It can also contain `Import` and `Charset` objects stemming from at-rules.
  */
-abstract class CSSList implements Renderable, Commentable
+abstract class CSSList implements Commentable, CSSListItem, Renderable
 {
     /**
      * @var list<Comment>
@@ -41,7 +41,7 @@ abstract class CSSList implements Renderable, Commentable
     protected $comments = [];
 
     /**
-     * @var array<int<0, max>, RuleSet|CSSList|Import|Charset>
+     * @var array<int<0, max>, CSSListItem>
      *
      * @internal since 8.8.0
      */
@@ -105,7 +105,10 @@ public static function parseList(ParserState $parserState, CSSList $list): void
     }
 
     /**
-     * @return AtRuleBlockList|KeyFrame|Charset|CSSNamespace|Import|AtRuleSet|DeclarationBlock|false|null
+     * @return CSSListItem|false|null
+     *         If `null` is returned, it means the end of the list has been reached.
+     *         If `false` is returned, it means an invalid item has been encountered,
+     *         but parsing of the next item should proceed.
      *
      * @throws SourceException
      * @throws UnexpectedEOFException
@@ -139,7 +142,7 @@ private static function parseListItem(ParserState $parserState, CSSList $list)
         } elseif ($parserState->comes('}')) {
             if ($isRoot) {
                 if ($parserState->getSettings()->usesLenientParsing()) {
-                    return DeclarationBlock::parse($parserState);
+                    return DeclarationBlock::parse($parserState) ?? false;
                 } else {
                     throw new SourceException('Unopened {', $parserState->currentLine());
                 }
@@ -148,18 +151,16 @@ private static function parseListItem(ParserState $parserState, CSSList $list)
                 return null;
             }
         } else {
-            return DeclarationBlock::parse($parserState, $list);
+            return DeclarationBlock::parse($parserState, $list) ?? false;
         }
     }
 
     /**
-     * @return AtRuleBlockList|KeyFrame|Charset|CSSNamespace|Import|AtRuleSet|null
-     *
      * @throws SourceException
      * @throws UnexpectedTokenException
      * @throws UnexpectedEOFException
      */
-    private static function parseAtRule(ParserState $parserState)
+    private static function parseAtRule(ParserState $parserState): ?CSSListItem
     {
         $parserState->consume('@');
         $identifier = $parserState->parseIdentifier();
@@ -262,28 +263,24 @@ public function getLineNo(): int
 
     /**
      * Prepends an item to the list of contents.
-     *
-     * @param RuleSet|CSSList|Import|Charset $item
      */
-    public function prepend($item): void
+    public function prepend(CSSListItem $item): void
     {
         \array_unshift($this->contents, $item);
     }
 
     /**
      * Appends an item to the list of contents.
-     *
-     * @param RuleSet|CSSList|Import|Charset $item
      */
-    public function append($item): void
+    public function append(CSSListItem $item): void
     {
         $this->contents[] = $item;
     }
 
     /**
      * Splices the list of contents.
      *
-     * @param array<int, RuleSet|CSSList|Import|Charset> $replacement
+     * @param array<int, CSSListItem> $replacement
      */
     public function splice(int $offset, ?int $length = null, ?array $replacement = null): void
     {
@@ -293,11 +290,8 @@ public function splice(int $offset, ?int $length = null, ?array $replacement = n
     /**
      * Inserts an item in the CSS list before its sibling. If the desired sibling cannot be found,
      * the item is appended at the end.
-     *
-     * @param RuleSet|CSSList|Import|Charset $item
-     * @param RuleSet|CSSList|Import|Charset $sibling
      */
-    public function insertBefore($item, $sibling): void
+    public function insertBefore(CSSListItem $item, CSSListItem $sibling): void
     {
         if (\in_array($sibling, $this->contents, true)) {
             $this->replace($sibling, [$item, $sibling]);
@@ -309,13 +303,13 @@ public function insertBefore($item, $sibling): void
     /**
      * Removes an item from the CSS list.
      *
-     * @param RuleSet|Import|Charset|CSSList $itemToRemove
+     * @param CSSListItem $itemToRemove
      *        May be a `RuleSet` (most likely a `DeclarationBlock`), an `Import`,
      *        a `Charset` or another `CSSList` (most likely a `MediaQuery`)
      *
      * @return bool whether the item was removed
      */
-    public function remove($itemToRemove): bool
+    public function remove(CSSListItem $itemToRemove): bool
     {
         $key = \array_search($itemToRemove, $this->contents, true);
         if ($key !== false) {
@@ -329,12 +323,12 @@ public function remove($itemToRemove): bool
     /**
      * Replaces an item from the CSS list.
      *
-     * @param RuleSet|Import|Charset|CSSList $oldItem
+     * @param CSSListItem $oldItem
      *        May be a `RuleSet` (most likely a `DeclarationBlock`), an `Import`, a `Charset`
      *        or another `CSSList` (most likely a `MediaQuery`)
-     * @param RuleSet|Import|Charset|CSSList|array<RuleSet|Import|Charset|CSSList> $newItem
+     * @param CSSListItem|array<CSSListItem> $newItem
      */
-    public function replace($oldItem, $newItem): bool
+    public function replace(CSSListItem $oldItem, $newItem): bool
     {
         $key = \array_search($oldItem, $this->contents, true);
         if ($key !== false) {
@@ -350,7 +344,7 @@ public function replace($oldItem, $newItem): bool
     }
 
     /**
-     * @param array<int, RuleSet|Import|Charset|CSSList> $contents
+     * @param array<int, CSSListItem> $contents
      */
     public function setContents(array $contents): void
     {
@@ -441,7 +435,7 @@ abstract public function isRootList(): bool;
     /**
      * Returns the stored items.
      *
-     * @return array<int<0, max>, RuleSet|Import|Charset|CSSList>
+     * @return array<int<0, max>, CSSListItem>
      */
     public function getContents(): array
     {

src/CSSList/CSSListItem.php

@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Sabberworm\CSS\CSSList;
+
+use Sabberworm\CSS\Comment\Commentable;
+use Sabberworm\CSS\Renderable;
+
+/**
+ * Represents anything that can be in the `$contents` of a `CSSList`.
+ *
+ * The interface does not define any methods to implement.
+ * It's purpose is to allow a single type to be specified for `CSSList::$contents` and manipulation methods thereof.
+ * It extends `Commentable` and `Renderable` because all `CSSListItem`s are both.
+ * This allows implementations to call methods from those interfaces without any additional type checks.
+ */
+interface CSSListItem extends Commentable, Renderable {}

src/Property/AtRule.php

@@ -5,9 +5,10 @@
 namespace Sabberworm\CSS\Property;
 
 use Sabberworm\CSS\Comment\Commentable;
+use Sabberworm\CSS\CSSList\CSSListItem;
 use Sabberworm\CSS\Renderable;
 
-interface AtRule extends Renderable, Commentable
+interface AtRule extends Commentable, CSSListItem, Renderable
 {
     /**
      * Since there are more set rules than block rules,

src/RuleSet/DeclarationBlock.php

@@ -30,14 +30,12 @@ class DeclarationBlock extends RuleSet
     private $selectors = [];
 
     /**
-     * @return DeclarationBlock|false
-     *
      * @throws UnexpectedTokenException
      * @throws UnexpectedEOFException
      *
      * @internal since V8.8.0
      */
-    public static function parse(ParserState $parserState, ?CSSList $list = null)
+    public static function parse(ParserState $parserState, ?CSSList $list = null): ?DeclarationBlock
     {
         $comments = [];
         $result = new DeclarationBlock($parserState->currentLine());
@@ -63,7 +61,7 @@ public static function parse(ParserState $parserState, ?CSSList $list = null)
                 if (!$parserState->comes('}')) {
                     $parserState->consumeUntil('}', false, true);
                 }
-                return false;
+                return null;
             } else {
                 throw $e;
             }

src/RuleSet/RuleSet.php

@@ -6,6 +6,7 @@
 
 use Sabberworm\CSS\Comment\Comment;
 use Sabberworm\CSS\Comment\Commentable;
+use Sabberworm\CSS\CSSList\CSSListItem;
 use Sabberworm\CSS\OutputFormat;
 use Sabberworm\CSS\Parsing\ParserState;
 use Sabberworm\CSS\Parsing\UnexpectedEOFException;
@@ -22,7 +23,7 @@
  * If you want to manipulate a `RuleSet`, use the methods `addRule(Rule $rule)`, `getRules()` and `removeRule($rule)`
  * (which accepts either a `Rule` or a rule name; optionally suffixed by a dash to remove all related rules).
  */
-abstract class RuleSet implements Renderable, Commentable
+abstract class RuleSet implements Commentable, CSSListItem, Renderable
 {
     /**
      * the rules in this rule set, using the property name as the key,

tests/CSSList/AtRuleBlockListTest.php

@@ -5,6 +5,7 @@
 namespace Sabberworm\CSS\Tests\CSSList;
 
 use PHPUnit\Framework\TestCase;
+use Sabberworm\CSS\CSSList\AtRuleBlockList;
 use Sabberworm\CSS\Parser;
 use Sabberworm\CSS\Settings;
 
@@ -60,6 +61,7 @@ public function parsesRuleNameOfMediaQueries(string $css): void
         $contents = (new Parser($css))->parse()->getContents();
         $atRuleBlockList = $contents[0];
 
+        self::assertInstanceOf(AtRuleBlockList::class, $atRuleBlockList);
         self::assertSame('media', $atRuleBlockList->atRuleName());
     }
 
@@ -73,6 +75,7 @@ public function parsesArgumentsOfMediaQueries(string $css): void
         $contents = (new Parser($css))->parse()->getContents();
         $atRuleBlockList = $contents[0];
 
+        self::assertInstanceOf(AtRuleBlockList::class, $atRuleBlockList);
         self::assertSame('(min-width: 768px)', $atRuleBlockList->atRuleArgs());
     }