Merge pull request #2052 from WordPress/feature/1465-new-deprecationh…

…elper

3.0: Move "deprecation" related utilities to dedicated DeprecationHelper + handle PHP 8.0 attributes

WordPress/Helpers/DeprecationHelper.php

@@ -0,0 +1,74 @@
+<?php
+/**
+ * WordPress Coding Standard.
+ *
+ * @package WPCS\WordPressCodingStandards
+ * @link    https://github.com/WordPress/WordPress-Coding-Standards
+ * @license https://opensource.org/licenses/MIT MIT
+ */
+
+namespace WordPressCS\WordPress\Helpers;
+
+use PHP_CodeSniffer\Files\File;
+use PHP_CodeSniffer\Util\Tokens;
+
+/**
+ * Helper utilities for checking whether something has been marked as deprecated.
+ *
+ * {@internal The functionality in this class will likely be replaced at some point in
+ * the future by functions from PHPCSUtils.}
+ *
+ * @package WPCS\WordPressCodingStandards
+ * @since   3.0.0 The method in this class was previously contained in the
+ *                `WordPressCS\WordPress\Sniff` class and has been moved here.
+ */
+final class DeprecationHelper {
+
+	/**
+	 * Check whether a function has been marked as deprecated via a @deprecated tag
+	 * in the function docblock.
+	 *
+	 * @since 2.2.0
+	 * @since 3.0.0 Moved from the Sniff class to this class.
+	 *
+	 * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned.
+	 * @param int                         $stackPtr  The position of a T_FUNCTION
+	 *                                               token in the stack.
+	 *
+	 * @return bool
+	 */
+	public static function is_function_deprecated( File $phpcsFile, $stackPtr ) {
+		$tokens                  = $phpcsFile->getTokens();
+		$ignore                  = Tokens::$methodPrefixes;
+		$ignore[ \T_WHITESPACE ] = \T_WHITESPACE;
+
+		for ( $comment_end = ( $stackPtr - 1 ); $comment_end >= 0; $comment_end-- ) {
+			if ( isset( $ignore[ $tokens[ $comment_end ]['code'] ] ) === true ) {
+				continue;
+			}
+
+			if ( \T_ATTRIBUTE_END === $tokens[ $comment_end ]['code']
+				&& isset( $tokens[ $comment_end ]['attribute_opener'] ) === true
+			) {
+				$comment_end = $tokens[ $comment_end ]['attribute_opener'];
+				continue;
+			}
+
+			break;
+		}
+
+		if ( \T_DOC_COMMENT_CLOSE_TAG !== $tokens[ $comment_end ]['code'] ) {
+			// Function doesn't have a doc comment or is using the wrong type of comment.
+			return false;
+		}
+
+		$comment_start = $tokens[ $comment_end ]['comment_opener'];
+		foreach ( $tokens[ $comment_start ]['comment_tags'] as $tag ) {
+			if ( '@deprecated' === $tokens[ $tag ]['content'] ) {
+				return true;
+			}
+		}
+
+		return false;
+	}
+}

WordPress/Sniff.php

@@ -2345,39 +2345,4 @@ protected function get_list_variables( $stackPtr, $list_open_close = array() ) {
 
 		return $var_pointers;
 	}
-
-	/**
-	 * Check whether a function has been marked as deprecated via a @deprecated tag
-	 * in the function docblock.
-	 *
-	 * {@internal This method is static to allow the ValidFunctionName class to use it.}}
-	 *
-	 * @since 2.2.0
-	 *
-	 * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned.
-	 * @param int                         $stackPtr  The position of a T_FUNCTION
-	 *                                               token in the stack.
-	 *
-	 * @return bool
-	 */
-	public static function is_function_deprecated( File $phpcsFile, $stackPtr ) {
-		$tokens = $phpcsFile->getTokens();
-		$find   = Tokens::$methodPrefixes;
-		$find[] = \T_WHITESPACE;
-
-		$comment_end = $phpcsFile->findPrevious( $find, ( $stackPtr - 1 ), null, true );
-		if ( \T_DOC_COMMENT_CLOSE_TAG !== $tokens[ $comment_end ]['code'] ) {
-			// Function doesn't have a doc comment or is using the wrong type of comment.
-			return false;
-		}
-
-		$comment_start = $tokens[ $comment_end ]['comment_opener'];
-		foreach ( $tokens[ $comment_start ]['comment_tags'] as $tag ) {
-			if ( '@deprecated' === $tokens[ $tag ]['content'] ) {
-				return true;
-			}
-		}
-
-		return false;
-	}
 }

WordPress/Sniffs/NamingConventions/PrefixAllGlobalsSniff.php

@@ -16,6 +16,7 @@
 use PHPCSUtils\Utils\Scopes;
 use PHPCSUtils\Utils\TextStrings;
 use WordPressCS\WordPress\AbstractFunctionParameterSniff;
+use WordPressCS\WordPress\Helpers\DeprecationHelper;
 use WordPressCS\WordPress\Helpers\IsUnitTestTrait;
 
 /**
@@ -386,7 +387,7 @@ public function process_token( $stackPtr ) {
 						return;
 					}
 
-					if ( $this->is_function_deprecated( $this->phpcsFile, $stackPtr ) === true ) {
+					if ( DeprecationHelper::is_function_deprecated( $this->phpcsFile, $stackPtr ) === true ) {
 						/*
 						 * Deprecated functions don't have to comply with the naming conventions,
 						 * otherwise functions deprecated in favour of a function with a compliant

WordPress/Sniffs/NamingConventions/ValidFunctionNameSniff.php

@@ -9,11 +9,12 @@
 
 namespace WordPressCS\WordPress\Sniffs\NamingConventions;
 
-use WordPressCS\WordPress\Sniff;
 use PHPCSUtils\BackCompat\BCTokens;
 use PHPCSUtils\Utils\FunctionDeclarations;
 use PHPCSUtils\Utils\ObjectDeclarations;
 use PHPCSUtils\Utils\Scopes;
+use WordPressCS\WordPress\Helpers\DeprecationHelper;
+use WordPressCS\WordPress\Sniff;
 
 /**
  * Enforces WordPress function name and method name format, based upon Squiz code.
@@ -55,7 +56,7 @@ public function register() {
 	 */
 	public function process_token( $stackPtr ) {
 
-		if ( Sniff::is_function_deprecated( $this->phpcsFile, $stackPtr ) === true ) {
+		if ( DeprecationHelper::is_function_deprecated( $this->phpcsFile, $stackPtr ) === true ) {
 			/*
 			 * Deprecated functions don't have to comply with the naming conventions,
 			 * otherwise functions deprecated in favour of a function with a compliant

WordPress/Tests/NamingConventions/PrefixAllGlobalsUnitTest.1.inc

@@ -482,6 +482,20 @@ function acronym_lists_in_function_scope() {
  */
 function deprecated_function() {}
 
+/**
+ * Function description.
+ *
+ * @since 1.2.3
+ * @deprecated 2.3.4
+ *
+ * @return void
+ */
+#[MyAttribute([
+	'something',
+	'something else',
+])]
+function deprecated_function_with_attribute() {}
+
 /*
  * Bad: Issue https://github.com/WordPress/WordPress-Coding-Standards/issues/1733.
  *

WordPress/Tests/NamingConventions/ValidFunctionNameUnitTest.inc

@@ -163,3 +163,17 @@ function ___triple_underscore() {} // OK.
 class Triple {
 	function ___triple_underscore() {} // OK.
 }
+
+class DeprecatedWithAttribute {
+	/**
+	 * Function description.
+	 *
+	 * @since 1.2.3
+	 * @deprecated 2.3.4
+	 *
+	 * @return void
+	 */
+	#[SomeAttribute]
+	#[AnotherAttribute]
+	public static function __deprecatedMethod() {}
+}