[FEATURE] Add consumeWhitespaceWithComments and redirect consumeWhitespace (backported)

CHANGELOG.md

@@ -7,10 +7,16 @@ This project adheres to [Semantic Versioning](https://semver.org/).
 
 ### Added
 
+- Add `ParserState::consumeWhiteSpaceWithComments()` method (#670)
+
 ### Changed
 
+- Redirect `ParserState::consumeWhiteSpace()` to `ParserState::consumeWhiteSpaceWithComments()` (#670)
+
 ### Deprecated
 
+- Deprecate `ParserState::consumeWhiteSpace()` in favor of `ParserState::consumeWhiteSpaceWithComments()` (#670)
+
 ### Removed
 
 ### Fixed

src/Parsing/ParserState.php

@@ -226,12 +226,35 @@ public function parseCharacter($bIsForIdentifier)
     }
 
     /**
-     * @return array<int, Comment>|void
+     * Consumes whitespace and comments and returns a list of comments.
+     *
+     * @return list<Comment> List of comments.
      *
      * @throws UnexpectedEOFException
      * @throws UnexpectedTokenException
+     *
+     * @deprecated From version 9.0.0 onwards this method will be undergo a breaking
+     *      change. This method will no longer consume comments, only whitespace.
+     *      Use `ParserState::consumeWhiteSpaceWithComments` as a replacement if you
+     *      need the former behaviour of consuming whitespace and comments.
+     *
+     * @see `ParserState::consumeWhiteSpaceWithComments` for a version that also
+     *      returns comments.
      */
     public function consumeWhiteSpace()
+    {
+        return $this->consumeWhiteSpaceWithComments();
+    }
+
+    /**
+     * Consumes whitespace and comments and returns a list of comments.
+     *
+     * @return list<Comment> List of comments.
+     *
+     * @throws UnexpectedEOFException
+     * @throws UnexpectedTokenException
+     */
+    public function consumeWhiteSpaceWithComments()
     {
         $aComments = [];
         do {