PHP 8.5 | Tokenizer/PHP: polyfill the (void) cast

As part of the RFC for the `#[NoDiscard]` attribute, a new typecast `(void)` has been introduced.

This commit polyfills this new token for PHP < 8.5.

Includes tests covering the complete set of type casts, even though the PHPCS Tokenizer only handles the `(void)` cast.
Reason being, that PHP has deprecated and removed some casts, like `(unset)`, and their token constants may be removed from PHP Core at some point in the future. These tests should serve as a warning system for that eventuality.

Ref: https://wiki.php.net/rfc/marking_return_value_as_important#void_cast_to_suppress_the_warning

Author: jrfnl

src/Tokenizers/PHP.php

@@ -1122,6 +1122,58 @@ protected function tokenize(string $code)
                 continue;
             }
 
+            /*
+                Detect PHP 8.5+ void casting and assign the casts their own token.
+
+                Mind: type cast tokens _may_ contain whitespace, but no new lines and no comments.
+            */
+
+            if (PHP_VERSION_ID < 80500
+                && $token[0] === '('
+            ) {
+                $content = $token[0];
+                $i       = ($stackPtr + 1);
+
+                if (is_array($tokens[$i]) === true
+                    && $tokens[$i][0] === T_WHITESPACE
+                    && strpos($tokens[$i][1], "\n") === false
+                    && strpos($tokens[$i][1], "\r") === false
+                ) {
+                    $content .= $tokens[$i][1];
+                    ++$i;
+                }
+
+                if (is_array($tokens[$i]) === true
+                    && $tokens[$i][0] === T_STRING
+                    && strtolower($tokens[$i][1]) === 'void'
+                ) {
+                    $content .= $tokens[$i][1];
+                    ++$i;
+
+                    if (is_array($tokens[$i]) === true
+                        && $tokens[$i][0] === T_WHITESPACE
+                        && strpos($tokens[$i][1], "\n") === false
+                        && strpos($tokens[$i][1], "\r") === false
+                    ) {
+                        $content .= $tokens[$i][1];
+                        ++$i;
+                    }
+
+                    if ($tokens[$i][0] === ')') {
+                        $content .= $tokens[$i][0];
+
+                        $finalTokens[$newStackPtr] = [
+                            'code'    => T_VOID_CAST,
+                            'type'    => 'T_VOID_CAST',
+                            'content' => $content,
+                        ];
+                        $newStackPtr++;
+                        $stackPtr = $i;
+                        continue;
+                    }
+                }
+            }
+
             /*
                 If this is a heredoc, PHP will tokenize the whole
                 thing which causes problems when heredocs don't

src/Util/Tokens.php

@@ -143,6 +143,11 @@
     define('T_PRIVATE_SET', 'PHPCS_T_PRIVATE_SET');
 }
 
+// Some PHP 8.5 tokens, replicated for lower versions.
+if (defined('T_VOID_CAST') === false) {
+    define('T_VOID_CAST', 'PHPCS_T_VOID_CAST');
+}
+
 // Tokens used for parsing doc blocks.
 define('T_DOC_COMMENT_STAR', 'PHPCS_T_DOC_COMMENT_STAR');
 define('T_DOC_COMMENT_WHITESPACE', 'PHPCS_T_DOC_COMMENT_WHITESPACE');
@@ -266,6 +271,7 @@ final class Tokens
         T_OBJECT_CAST => T_OBJECT_CAST,
         T_UNSET_CAST  => T_UNSET_CAST,
         T_BINARY_CAST => T_BINARY_CAST,
+        T_VOID_CAST   => T_VOID_CAST,
     ];
 
     /**

tests/Core/Tokenizers/PHP/TypecastsTest.inc

@@ -0,0 +1,130 @@
+<?php
+
+/*
+ * Safeguard that all type casts past and present are tokenized correctly.
+ *
+ * This is also intended as an early warning system for when type cast tokens would be removed
+ * for type casts which are no longer supported by PHP itself.
+ *
+ * Pertinent type cast changes in PHP:
+ * - (unset) cast was introduced in PHP 5.0.
+ * - (binary) cast was introduced in PHP 5.2.1.
+ * - (unset) cast was deprecated in PHP 7.2 and removed in PHP 8.0.
+ * - (real) cast was deprecated in PHP 7.4 and removed in PHP 8.0.
+ * - (void) cast was introduced in PHP 8.5.
+ * - (integer), (boolean), (double) and (binary) casts are deprecated since PHP 8.5 and will be removed in PHP 9.0.
+ */
+
+/* testNotATypeCast1 */
+$a = (NOT_A_TYPECAST);
+
+/* testBool */
+$a = (bool) $b;
+
+/* testSpacyUppercaseBool */
+$a = ( BOOL) $b;
+
+/* testBoolean */
+$a = (boolean) $b;
+
+/* testSpacyUppercaseBoolean */
+$a = ( BOOLEAN ) $b;
+
+/* testInt */
+$a = (int) $b;
+
+/* testSpacyUppercaseInt */
+$a = ( INT ) $b;
+
+/* testInteger */
+$a = (integer) $b;
+
+/* testSpacyUppercaseInteger */
+$a = (   INTEGER ) $b;
+
+/* testFloat */
+$a = (float) $b;
+
+/* testSpacyUppercaseFloat */
+$a = ( FLOAT ) $b;
+
+/* testReal */
+$a = (real) $b;
+
+/* testSpacyUppercaseReal */
+$a = ( REAL ) $b;
+
+/* testDouble */
+$a = (double) $b;
+
+/* testSpacyUppercaseDouble */
+$a = ( DOUBLE   ) $b;
+
+/* testString */
+$a = (string) $b;
+
+/* testSpacyUppercaseString */
+$a = (STRING ) $b;
+
+/* testBinary */
+$a = (binary) $b;
+
+/* testSpacyUppercaseBinary */
+$a = ( BINARY ) $b;
+
+/* testArray */
+$a = (array) $b;
+
+/* testSpacyUppercaseArray */
+$a = (   ARRAY   ) $b;
+
+/* testObject */
+$a = (object) $b;
+
+/* testSpacyUppercaseObject */
+$a = ( OBJECT ) $b;
+
+/* testUnset */
+$a = (unset) $b;
+
+/* testSpacyUppercaseUnset */
+$a = ( UNSET ) $b;
+
+/* testVoid */
+$a = (void) $b;
+
+/* testVoidNested */
+$a = ((void) $b);
+
+/* testSpacyVoid */
+$a = (   void   ) $b;
+
+/* testTabbyVoid */
+$a = (	void	) $b; // Tab whitespace.
+
+/* testUppercaseVoid */
+$a = (VOID) $b;
+
+
+/*
+ * New lines and comments are not allowed in a type cast.
+ */
+
+/* testNotATypeCast2 */
+$a = (
+void
+) $b;
+
+/* testNotATypeCast3 */
+$a = (
+
+    void
+
+) $b;
+
+/* testNotATypeCast4 */
+$a = ( /*comment*/ void /*comment */ ) $b;
+
+// Parse error. This must be the last test in the file!
+/* testNotATypeCast5 */
+$a = (void