From 0fa736aced04e00d1fc1a0cd50f99f1452d8ba7a Mon Sep 17 00:00:00 2001
From: Daniel Ziegenberg <daniel@ziegenberg.at>
Date: Sun, 25 Aug 2024 18:59:17 +0200
Subject: [PATCH 1/2] [FEATURE] Add comsumeWhitespaceWithComments and redirect
 comsumeWhitespace (#670)

Having comsumeWhitespace also consume comments and returning them was unexpected.

Signed-off-by: Daniel Ziegenberg <daniel@ziegenberg.at>
---
 CHANGELOG.md                |  4 ++++
 src/Parsing/ParserState.php | 17 ++++++++++++++++-
 2 files changed, 20 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index d1837d0b..436e015e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,8 +7,12 @@ This project adheres to [Semantic Versioning](https://semver.org/).
 
 ### Added
 
+- Add `ParserState::consumeWhiteSpaceWithComments()` method (#670)
+
 ### Changed
 
+- Redirect `ParserState::consumeWhiteSpace()` to `ParserState::consumeWhiteSpaceWithComments()` (#670)
+
 ### Deprecated
 
 ### Removed
diff --git a/src/Parsing/ParserState.php b/src/Parsing/ParserState.php
index 07578461..61547942 100644
--- a/src/Parsing/ParserState.php
+++ b/src/Parsing/ParserState.php
@@ -226,12 +226,27 @@ 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
      */
     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 {

From d53d9bab5f24344f330ab63e348ba690e666579e Mon Sep 17 00:00:00 2001
From: Daniel Ziegenberg <daniel@ziegenberg.at>
Date: Sun, 25 Aug 2024 19:08:35 +0200
Subject: [PATCH 2/2] [TASK] Deprecate ParserState::comsumeWhitespace (#670)

Signed-off-by: Daniel Ziegenberg <daniel@ziegenberg.at>
---
 CHANGELOG.md                | 2 ++
 src/Parsing/ParserState.php | 8 ++++++++
 2 files changed, 10 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 436e015e..e4701589 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -15,6 +15,8 @@ This project adheres to [Semantic Versioning](https://semver.org/).
 
 ### Deprecated
 
+- Deprecate `ParserState::consumeWhiteSpace()` in favor of `ParserState::consumeWhiteSpaceWithComments()` (#670)
+
 ### Removed
 
 ### Fixed
diff --git a/src/Parsing/ParserState.php b/src/Parsing/ParserState.php
index 61547942..3ef9c5f6 100644
--- a/src/Parsing/ParserState.php
+++ b/src/Parsing/ParserState.php
@@ -232,6 +232,14 @@ public function parseCharacter($bIsForIdentifier)
      *
      * @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()
     {