Merge pull request #1806 from WordPress/feature/1797-ignore-deprecate…

…d-functions-for-namechecks

PrefixAllGlobals + ValidFunctionName: ignore deprecated methods by design

WordPress/Sniff.php

@@ -3385,4 +3385,38 @@ 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

@@ -21,7 +21,8 @@
  * @since   0.12.0
  * @since   0.13.0 Class name changed: this class is now namespaced.
  * @since   1.2.0  Now also checks whether namespaces are prefixed.
- * @since   2.2.0  Now also checks variables assigned via the list() construct.
+ * @since   2.2.0  - Now also checks variables assigned via the list() construct.
+ *                 - Now also ignores global functions which are marked as @deprecated.
  *
  * @uses    \WordPressCS\WordPress\Sniff::$custom_test_class_whitelist
  */
@@ -382,6 +383,15 @@ public function process_token( $stackPtr ) {
 						return;
 					}
 
+					if ( $this->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
+						 * name would still trigger an error.
+						 */
+						return;
+					}
+
 					$item_name = $this->phpcsFile->getDeclarationName( $stackPtr );
 					if ( isset( $this->built_in_functions[ $item_name ] ) ) {
 						// Backfill for PHP native function.

WordPress/Sniffs/NamingConventions/ValidFunctionNameSniff.php

@@ -24,6 +24,7 @@
  * @since   0.13.0 Class name changed: this class is now namespaced.
  * @since   2.0.0  The `get_name_suggestion()` method has been moved to the
  *                 WordPress native `Sniff` base class as `get_snake_case_name_suggestion()`.
+ * @since   2.2.0  Will now ignore functions and methods which are marked as @deprecated.
  *
  * Last synced with parent class December 2018 up to commit ee167761d7756273b8ad0ad68bf3db1f2c211bb8.
  * @link    https://github.com/squizlabs/PHP_CodeSniffer/blob/master/CodeSniffer/Standards/PEAR/Sniffs/NamingConventions/ValidFunctionNameSniff.php
@@ -43,6 +44,16 @@ class ValidFunctionNameSniff extends PHPCS_PEAR_ValidFunctionNameSniff {
 	 * @return void
 	 */
 	protected function processTokenOutsideScope( File $phpcsFile, $stackPtr ) {
+
+		if ( Sniff::is_function_deprecated( $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
+			 * name would still trigger an error.
+			 */
+			return;
+		}
+
 		$functionName = $phpcsFile->getDeclarationName( $stackPtr );
 
 		if ( ! isset( $functionName ) ) {
@@ -51,7 +62,7 @@ protected function processTokenOutsideScope( File $phpcsFile, $stackPtr ) {
 		}
 
 		if ( '' === ltrim( $functionName, '_' ) ) {
-			// Ignore special functions.
+			// Ignore special functions, like __().
 			return;
 		}
 
@@ -102,6 +113,15 @@ protected function processTokenWithinScope( File $phpcsFile, $stackPtr, $currSco
 			return;
 		}
 
+		if ( Sniff::is_function_deprecated( $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
+			 * name would still trigger an error.
+			 */
+			return;
+		}
+
 		$methodName = $phpcsFile->getDeclarationName( $stackPtr );
 
 		if ( ! isset( $methodName ) ) {

WordPress/Tests/NamingConventions/PrefixAllGlobalsUnitTest.1.inc

@@ -471,11 +471,20 @@ function acronym_lists_in_function_scope() {
 	list( $foo['key'], $foo[ $c ] ) = $array; // OK. Variable array key should be ignored.
 }
 
-// phpcs:set WordPress.NamingConventions.PrefixAllGlobals prefixes[]
+// Issue #1797 - Ignore non-prefixed deprecated functions.
+/**
+ * Function description.
+ *
+ * @since 1.2.3
+ * @deprecated 2.3.4
+ *
+ * @return void
+ */
+function deprecated_function() {}
 
 /*
  * Bad: Issue https://github.com/WordPress/WordPress-Coding-Standards/issues/1733.
- * 
+ *
  * Short prefixes are not allowed. The errors are triggered
  * on LINE 1 for the unit-test, because it's the phpcs:set command that is
  * wrong, not the implementing code.

WordPress/Tests/NamingConventions/ValidFunctionNameUnitTest.inc

@@ -123,3 +123,25 @@ abstract class My_Class {
     public function my_Class() {}
     public function _MY_CLASS() {}
 }
+
+/**
+ * Function description.
+ *
+ * @since 1.2.3
+ * @deprecated 2.3.4
+ *
+ * @return void
+ */
+function __deprecatedFunction() {}
+
+class Deprecated {
+	/**
+	 * Function description.
+	 *
+	 * @since 1.2.3
+	 * @deprecated 2.3.4
+	 *
+	 * @return void
+	 */
+	public static function __deprecatedMethod() {}
+}