[CLEANUP] Return null from DeclarationBlock::parse() on failure

Also add clarification of meaning of return value from
`CSSList::parseListItem()`, where `null` and `false` have different meanings.

Part of #1176.

Author: JakeQZ

config/phpstan-baseline.neon

@@ -48,12 +48,6 @@ 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

src/CSSList/CSSList.php

@@ -106,6 +106,9 @@ public static function parseList(ParserState $parserState, CSSList $list): void
 
     /**
      * @return AtRuleBlockList|KeyFrame|Charset|CSSNamespace|Import|AtRuleSet|DeclarationBlock|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,7 +151,7 @@ private static function parseListItem(ParserState $parserState, CSSList $list)
                 return null;
             }
         } else {
-            return DeclarationBlock::parse($parserState, $list);
+            return DeclarationBlock::parse($parserState, $list) ?? false;
         }
     }
 

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;
             }