PrefixAllGlobals: ignore deprecated functions

Check the function docblock for a `@deprecated` tag and if found, bow out.

Includes unit tests.

Fixes 1797

Note: the same should probably also be done for classes/interfaces/traits/constants marked as deprecated, but that's for another PR.

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/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.