feat: Ability to skip "meta" tokens (whitespace, comments, attributes)

src/Tokenizer/Tokens.php

@@ -523,6 +523,18 @@ public function getCodeHash(): string
         return $this->codeHash;
     }
 
+    /**
+     * Get index for closest next token which is non meta (whitespace, comments, PHP8 attribute).
+     *
+     * This method is shorthand for getNonMetaSibling method.
+     *
+     * @param int $index token index
+     */
+    public function getNextNonMeta(int $index): ?int
+    {
+        return $this->getNonMetaSibling($index, 1);
+    }
+
     /**
      * Get index for closest next token which is non whitespace.
      *
@@ -572,6 +584,43 @@ public function getNonWhitespaceSibling(int $index, int $direction, ?string $whi
         }
     }
 
+    /**
+     * Get index for closest sibling token which is non meta (whitespace, comment, PHP8 attribute).
+     *
+     * @param int  $index     token index
+     * @param -1|1 $direction
+     */
+    public function getNonMetaSibling(int $index, int $direction): ?int
+    {
+        if (!\defined('T_ATTRIBUTE')) {
+            return $this->getMeaningfulTokenSibling($index, $direction);
+        }
+
+        do {
+            $index = $this->getMeaningfulTokenSibling($index, $direction);
+
+            if (1 === $direction && $this[$index]->isGivenKind(T_ATTRIBUTE)) {
+                $index = $this->findBlockEnd(self::BLOCK_TYPE_ATTRIBUTE, $index);
+            } elseif (-1 === $direction && $this[$index]->isGivenKind(CT::T_ATTRIBUTE_CLOSE)) {
+                $index = $this->findBlockStart(self::BLOCK_TYPE_ATTRIBUTE, $index);
+            }
+        } while ($this[$index]->isGivenKind([T_ATTRIBUTE, CT::T_ATTRIBUTE_CLOSE]));
+
+        return $index;
+    }
+
+    /**
+     * Get index for closest previous token which is non meta (whitespace, comment, PHP8 attribute).
+     *
+     * This method is shorthand for getNonMetaSibling method.
+     *
+     * @param int $index token index
+     */
+    public function getPrevNonMeta(int $index): ?int
+    {
+        return $this->getNonMetaSibling($index, -1);
+    }
+
     /**
      * Get index for closest previous token which is non whitespace.
      *

tests/Tokenizer/TokensTest.php

@@ -1806,6 +1806,92 @@ public function testFindingToken(): void
         self::assertTrue($tokens->isTokenKindFound(T_VARIABLE));
     }
 
+    /**
+     * @param -1|1 $direction
+     *
+     * @requires PHP 8.0
+     *
+     * @dataProvider provideGetNonMetaSiblingCases
+     */
+    public function testGetNonMetaSibling(string $code, int $index, int $direction, int $expectedIndex): void
+    {
+        $tokens = Tokens::fromCode($code);
+
+        self::assertSame($expectedIndex, $tokens->getNonMetaSibling($index, $direction));
+    }
+
+    /**
+     * @return iterable<array{0: string, 1: int, 2: -1|1, 3: int}>
+     */
+    public static function provideGetNonMetaSiblingCases(): iterable
+    {
+        $cases = [
+            'outside function signature' => [
+                '<?php
+
+$a = 1;
+
+#[Foo]
+// comment
+# comment
+#[Bar]
+/* comment */
+/** comment */
+/*
+ * comment
+ */
+#[
+    Baz,
+    Buzz
+]
+function xyz() {};
+',
+                7,
+                36,
+            ],
+
+            'inside function signature' => [
+                '<?php function xyz(#[Foo] #[Bar] $a) {};',
+                4,
+                13,
+            ],
+
+            'inside class' => [
+                '<?php
+class Xyz {
+    #[Foo]
+    private $a;
+}',
+                5,
+                11,
+            ],
+
+            'between class properties' => [
+                '<?php
+class Xyz {
+    private $a; // Something
+
+    #[Foo]
+    #[Bar]
+    /** @var int */
+    #[
+        Baz(new Xyz()),
+        Buzz(1, 2, 3)
+    ]
+    private $b;
+}',
+                10,
+                49,
+            ],
+        ];
+
+        foreach ($cases as $name => $case) {
+            yield "{$name}, next sibling" => [$case[0], $case[1], 1, $case[2]];
+
+            yield "{$name}, previous sibling" => [$case[0], $case[2], -1, $case[1]];
+        }
+    }
+
     private function getBlockEdgeCachingTestTokens(): Tokens
     {
         Tokens::clearCache();