Merge pull request #2630 from rodrigoprimo/enqueued-resource-parameters-case-insensitive-null

WP/EnqueuedResourceParameters: fix handling of non-lowercased `null` and fully qualified `\null` and `\false`

Author: dingo-d

.github/CONTRIBUTING.md

@@ -62,7 +62,7 @@ When you introduce new `public` sniff properties, or your sniff extends a class
 
 ### Pre-requisites
 * WordPress-Coding-Standards
-* PHP_CodeSniffer 3.13.0 or higher
+* PHP_CodeSniffer 3.13.4 or higher
 * PHPCSUtils 1.1.0 or higher
 * PHPCSExtra 1.4.0 or higher
 * PHPUnit 8.x - 9.x

WordPress/Sniffs/WP/EnqueuedResourceParametersSniff.php

@@ -15,10 +15,11 @@
 use WordPressCS\WordPress\AbstractFunctionParameterSniff;
 
 /**
- * This checks the enqueued 4th and 5th parameters to make sure the version and in_footer are set.
+ * This checks that the 4th ($ver) parameter is set for all enqueued resources and that the 5th ($in_footer) parameter
+ * is set for wp_register_script() and wp_enqueue_script().
  *
  * If a source ($src) value is passed, then version ($ver) needs to have non-falsy value.
- * If a source ($src) value is passed a check for in footer ($in_footer), warn the user if the value is falsy.
+ * If a source ($src) value is passed, then it is recommended to explicitly set the $in_footer parameter.
  *
  * @link https://developer.wordpress.org/reference/functions/wp_register_script/
  * @link https://developer.wordpress.org/reference/functions/wp_enqueue_script/
@@ -53,20 +54,21 @@ final class EnqueuedResourceParametersSniff extends AbstractFunctionParameterSni
 	);
 
 	/**
-	 * False + the empty tokens array.
+	 * False + T_NS_SEPARATOR + the empty tokens array.
 	 *
 	 * This array is enriched with the $emptyTokens array in the register() method.
 	 *
 	 * @var array<int|string, int|string>
 	 */
 	private $false_tokens = array(
-		\T_FALSE => \T_FALSE,
+		\T_FALSE        => \T_FALSE,
+		\T_NS_SEPARATOR => \T_NS_SEPARATOR, // Needed to handle fully qualified \false (PHPCS 3.x).
 	);
 
 	/**
 	 * Token codes which are "safe" to accept to determine whether a version would evaluate to `false`.
 	 *
-	 * This array is enriched with the several of the PHPCS token arrays in the register() method.
+	 * This array is enriched with several of the PHPCS token arrays in the register() method.
 	 *
 	 * @var array<int|string, int|string>
 	 */
@@ -88,7 +90,8 @@ final class EnqueuedResourceParametersSniff extends AbstractFunctionParameterSni
 	/**
 	 * Returns an array of tokens this test wants to listen for.
 	 *
-	 * Overloads and calls the parent method to allow for adding additional tokens to the $safe_tokens property.
+	 * Overloads and calls the parent method to allow for adding additional tokens to the
+	 * $false_tokens and $safe_tokens properties.
 	 *
 	 * @return array
 	 */
@@ -139,7 +142,7 @@ public function process_parameters( $stackPtr, $group_name, $matched_content, $p
 			}
 		}
 
-		if ( false === $version_param || 'null' === $version_param['clean'] ) {
+		if ( false === $version_param || strtolower( ltrim( $version_param['clean'], '\\' ) ) === 'null' ) {
 			$type = 'script';
 			if ( strpos( $matched_content, '_style' ) !== false ) {
 				$type = 'style';
@@ -165,8 +168,8 @@ public function process_parameters( $stackPtr, $group_name, $matched_content, $p
 		/*
 		 * In footer Check
 		 *
-		 * Check to make sure that $in_footer is set to true.
-		 * It will warn the user to make sure it is intended.
+		 * Check to make sure that $in_footer is explicitly set.
+		 * Warn the user if it is not set.
 		 *
 		 * Only wp_register_script and wp_enqueue_script need this check,
 		 * as this parameter is not available to wp_register_style and wp_enqueue_style.

WordPress/Tests/WP/EnqueuedResourceParametersUnitTest.1.inc

@@ -29,7 +29,7 @@ wp_register_script( 'someScript-js', 'https://example.com/someScript.js' , array
 wp_register_script( 'someScript-js', 'https://example.com/someScript.js' , array( 'jquery' ), function() { }, true ); // OK.
 wp_register_script( 'someScript-js', 'https://example.com/someScript.js' , array( 'jquery' ), $version, true ); // OK.
 
-wp_register_script( 'someScript-js', 'https://example.com/someScript.js' , array( 'jquery' ), '1.1.0' ); // Warning - In Footer is set to a falsy (default) value.
+wp_register_script( 'someScript-js', 'https://example.com/someScript.js' , array( 'jquery' ), '1.1.0' ); // Warning - $in_footer is not explicitly set.
 wp_register_script( 'someScript-js', 'https://example.com/someScript.js' , array( 'jquery' ), '1.1.0', false ); // OK.
 wp_register_script( 'someScript-js', 'https://example.com/someScript.js' , array( 'jquery' ), '1.1.0', null ); // OK.
 wp_register_script( 'someScript-js', 'https://example.com/someScript.js' , array( 'jquery' ), '1.1.0', 0 ); // OK.
@@ -95,3 +95,16 @@ wp_register_script( 'someScript-js', 'https://example.com/someScript.js' , array
 wp_register_script( 'someScript-js', 'https://example.com/someScript.js' , array( 'jquery' ), (double) 0, true ); // Error - 0, false or NULL are not allowed.
 
 wp_register_script( 'someScript-js', 'https://example.com/someScript.js' , array( 'jquery' ), (binary) 0, true ); // Error - 0, false or NULL are not allowed.
+
+// Safeguard handling of non-lowercase `null`.
+wp_register_script( 'someScript-js', 'https://example.com/someScript.js' , array( 'jquery' ), NULL, true ); // Warning - 0, false or NULL are not allowed.
+
+/*
+ * Safeguard handling of fully qualified \true, \false and \null.
+ * Also safeguard that adding T_NS_SEPARATOR to $false_tokens doesn't cause false positives due to problems in is_falsy().
+ */
+wp_register_script( 'someScript-js', 'https://example.com/someScript.js' , array( 'jquery' ), \FALSE, \true ); // Error - 0, false or NULL are not allowed.
+wp_register_script( 'someScript-js', 'https://example.com/someScript.js' , array( 'jquery' ), \null, \TRUE ); // Warning - 0, false or NULL are not allowed.
+wp_register_script( 'someScript-js', 'https://example.com/someScript.js' , array( 'jquery' ), \Null, true ); // Warning - 0, false or NULL are not allowed.
+wp_register_script( 'someScript-js', 'https://example.com/someScript.js' , array( 'jquery' ), \true, \False ); // Ok.
+wp_register_script( 'someScript-js', 'https://example.com/someScript.js' , array( 'jquery' ), \get_version(), \null ); // OK.

WordPress/Tests/WP/EnqueuedResourceParametersUnitTest.php

@@ -31,22 +31,23 @@ public function getErrorList( $testFile = '' ) {
 		switch ( $testFile ) {
 			case 'EnqueuedResourceParametersUnitTest.1.inc':
 				return array(
-					6  => 1,
-					9  => 1,
-					10 => 1,
-					12 => 1,
-					13 => 1,
-					14 => 1,
-					22 => 1,
-					54 => 1,
-					57 => 1,
-					61 => 1,
-					82 => 1,
-					85 => 1,
-					89 => 1,
-					92 => 1,
-					95 => 1,
-					97 => 1,
+					6   => 1,
+					9   => 1,
+					10  => 1,
+					12  => 1,
+					13  => 1,
+					14  => 1,
+					22  => 1,
+					54  => 1,
+					57  => 1,
+					61  => 1,
+					82  => 1,
+					85  => 1,
+					89  => 1,
+					92  => 1,
+					95  => 1,
+					97  => 1,
+					106 => 1,
 				);
 
 			case 'EnqueuedResourceParametersUnitTest.2.inc':
@@ -70,14 +71,17 @@ public function getWarningList( $testFile = '' ) {
 		switch ( $testFile ) {
 			case 'EnqueuedResourceParametersUnitTest.1.inc':
 				return array(
-					3  => 2,
-					11 => 1,
-					32 => 1,
-					39 => 2,
-					42 => 1,
-					45 => 1,
-					66 => 2,
-					77 => 1,
+					3   => 2,
+					11  => 1,
+					32  => 1,
+					39  => 2,
+					42  => 1,
+					45  => 1,
+					66  => 2,
+					77  => 1,
+					100 => 1,
+					107 => 1,
+					108 => 1,
 				);
 
 			default:

composer.json

@@ -21,7 +21,7 @@
 		"ext-libxml": "*",
 		"ext-tokenizer": "*",
 		"ext-xmlreader": "*",
-		"squizlabs/php_codesniffer": "^3.13.0",
+		"squizlabs/php_codesniffer": "^3.13.4",
 		"phpcsstandards/phpcsutils": "^1.1.0",
 		"phpcsstandards/phpcsextra": "^1.4.0"
 	},