diff --git a/WordPress/Sniff.php b/WordPress/Sniff.php index 1abc6c920a..ed6bc3e1b7 100644 --- a/WordPress/Sniff.php +++ b/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; + } } diff --git a/WordPress/Sniffs/NamingConventions/PrefixAllGlobalsSniff.php b/WordPress/Sniffs/NamingConventions/PrefixAllGlobalsSniff.php index a77bcd0b91..eadf332601 100644 --- a/WordPress/Sniffs/NamingConventions/PrefixAllGlobalsSniff.php +++ b/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. diff --git a/WordPress/Sniffs/NamingConventions/ValidFunctionNameSniff.php b/WordPress/Sniffs/NamingConventions/ValidFunctionNameSniff.php index c88835cb6f..d8826ce1cf 100644 --- a/WordPress/Sniffs/NamingConventions/ValidFunctionNameSniff.php +++ b/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 ) ) { diff --git a/WordPress/Tests/NamingConventions/PrefixAllGlobalsUnitTest.1.inc b/WordPress/Tests/NamingConventions/PrefixAllGlobalsUnitTest.1.inc index 655096a4c3..12404130e6 100644 --- a/WordPress/Tests/NamingConventions/PrefixAllGlobalsUnitTest.1.inc +++ b/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. diff --git a/WordPress/Tests/NamingConventions/ValidFunctionNameUnitTest.inc b/WordPress/Tests/NamingConventions/ValidFunctionNameUnitTest.inc index 642fe78a80..f0403333ee 100644 --- a/WordPress/Tests/NamingConventions/ValidFunctionNameUnitTest.inc +++ b/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() {} +}