Merge pull request #2157 from WordPress/feature/move-property-handlin…

…g-method-to-helper-class Move "property handling" related utilities to dedicated `RulesetPropertyHelper`
WordPress · Dec 19, 2022 · 69f6e72 · 69f6e72
2 parents e4edee7 + c4553f2
commit 69f6e72
Show file tree

Hide file tree

Showing 16 changed files with 112 additions and 74 deletions.
diff --git a/WordPress/AbstractArrayAssignmentRestrictionsSniff.php b/WordPress/AbstractArrayAssignmentRestrictionsSniff.php
@@ -11,6 +11,7 @@
 
 use PHPCSUtils\Utils\MessageHelper;
 use PHPCSUtils\Utils\TextStrings;
+use WordPressCS\WordPress\Helpers\RulesetPropertyHelper;
 use WordPressCS\WordPress\Sniff;
 
 /**
@@ -134,7 +135,7 @@ protected function setup_groups() {
 	 */
 	public function process_token( $stackPtr ) {
 
-		$this->excluded_groups = $this->merge_custom_array( $this->exclude );
+		$this->excluded_groups = RulesetPropertyHelper::merge_custom_array( $this->exclude );
 		if ( array_diff_key( $this->groups_cache, $this->excluded_groups ) === array() ) {
 			// All groups have been excluded.
 			// Don't remove the listener as the exclude property can be changed inline.

diff --git a/WordPress/AbstractClassRestrictionsSniff.php b/WordPress/AbstractClassRestrictionsSniff.php
@@ -11,6 +11,7 @@
 
 use PHPCSUtils\Utils\Namespaces;
 use WordPressCS\WordPress\AbstractFunctionRestrictionsSniff;
+use WordPressCS\WordPress\Helpers\RulesetPropertyHelper;
 
 /**
  * Restricts usage of some classes.
@@ -93,7 +94,7 @@ public function process_token( $stackPtr ) {
 		// Reset the temporary storage before processing the token.
 		unset( $this->classname );
 
-		$this->excluded_groups = $this->merge_custom_array( $this->exclude );
+		$this->excluded_groups = RulesetPropertyHelper::merge_custom_array( $this->exclude );
 		if ( array_diff_key( $this->groups, $this->excluded_groups ) === array() ) {
 			// All groups have been excluded.
 			// Don't remove the listener as the exclude property can be changed inline.

diff --git a/WordPress/AbstractFunctionRestrictionsSniff.php b/WordPress/AbstractFunctionRestrictionsSniff.php
@@ -11,6 +11,7 @@
 
 use PHP_CodeSniffer\Util\Tokens;
 use PHPCSUtils\Utils\MessageHelper;
+use WordPressCS\WordPress\Helpers\RulesetPropertyHelper;
 use WordPressCS\WordPress\Sniff;
 
 /**
@@ -183,7 +184,7 @@ protected function setup_groups( $key ) {
 	 */
 	public function process_token( $stackPtr ) {
 
-		$this->excluded_groups = $this->merge_custom_array( $this->exclude );
+		$this->excluded_groups = RulesetPropertyHelper::merge_custom_array( $this->exclude );
 		if ( array_diff_key( $this->groups, $this->excluded_groups ) === array() ) {
 			// All groups have been excluded.
 			// Don't remove the listener as the exclude property can be changed inline.

diff --git a/WordPress/Helpers/IsUnitTestTrait.php b/WordPress/Helpers/IsUnitTestTrait.php
@@ -13,7 +13,7 @@
 use PHP_CodeSniffer\Util\Tokens;
 use PHPCSUtils\Utils\Namespaces;
 use PHPCSUtils\Utils\ObjectDeclarations;
-use WordPressCS\WordPress\Sniff as WPCS_Sniff;
+use WordPressCS\WordPress\Helpers\RulesetPropertyHelper;
 
 /**
  * Helper utilities for sniffs which need to take into account whether the
@@ -127,7 +127,7 @@ protected function is_test_class( File $phpcsFile, $stackPtr ) {
 		}
 
 		// Add any potentially extra custom test classes to the known test classes list.
-		$known_test_classes = WPCS_Sniff::merge_custom_array(
+		$known_test_classes = RulesetPropertyHelper::merge_custom_array(
 			$this->custom_test_classes,
 			$this->known_test_classes
 		);

diff --git a/WordPress/Helpers/RulesetPropertyHelper.php b/WordPress/Helpers/RulesetPropertyHelper.php
@@ -0,0 +1,72 @@
+<?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;
+
+/**
+ * Helper utilities for working with user provided property values.
+ *
+ * ---------------------------------------------------------------------------------------------
+ * This class is only intended for internal use by WordPressCS and is not part of the public API.
+ * This also means that it has no promise of backward compatibility. Use at your own risk.
+ * ---------------------------------------------------------------------------------------------
+ *
+ * @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 RulesetPropertyHelper {
+
+	/**
+	 * Merge a pre-set array with a ruleset provided array.
+	 *
+	 * - By default flips custom lists to allow for using `isset()` instead
+	 *   of `in_array()`.
+	 * - When `$flip` is true:
+	 *   * Presumes the base array is in a `'value' => true` format.
+	 *   * Any custom items will be given the value `false` to be able to
+	 *     distinguish them from pre-set (base array) values.
+	 *   * Will filter previously added custom items out from the base array
+	 *     before merging/returning to allow for resetting to the base array.
+	 *
+	 * {@internal Function is static as it doesn't use any of the properties or others
+	 * methods anyway.}
+	 *
+	 * @since 0.11.0
+	 * @since 2.0.0  No longer supports custom array properties which were incorrectly
+	 *               passed as a string.
+	 * @since 3.0.0  Moved from the Sniff class to this class.
+	 *
+	 * @param array $custom Custom list as provided via a ruleset.
+	 * @param array $base   Optional. Base list. Defaults to an empty array.
+	 *                      Expects `value => true` format when `$flip` is true.
+	 * @param bool  $flip   Optional. Whether or not to flip the custom list.
+	 *                      Defaults to true.
+	 * @return array
+	 */
+	public static function merge_custom_array( $custom, $base = array(), $flip = true ) {
+		if ( true === $flip ) {
+			$base = array_filter( $base );
+		}
+
+		if ( empty( $custom ) || ! \is_array( $custom ) ) {
+			return $base;
+		}
+
+		if ( true === $flip ) {
+			$custom = array_fill_keys( $custom, false );
+		}
+
+		if ( empty( $base ) ) {
+			return $custom;
+		}
+
+		return array_merge( $base, $custom );
+	}
+}
diff --git a/WordPress/Sniff.php b/WordPress/Sniff.php
@@ -763,53 +763,6 @@ public static function get_snake_case_name_suggestion( $name ) {
 		return $suggested;
 	}
 
-	/**
-	 * Merge a pre-set array with a ruleset provided array.
-	 *
-	 * - By default flips custom lists to allow for using `isset()` instead
-	 *   of `in_array()`.
-	 * - When `$flip` is true:
-	 *   * Presumes the base array is in a `'value' => true` format.
-	 *   * Any custom items will be given the value `false` to be able to
-	 *     distinguish them from pre-set (base array) values.
-	 *   * Will filter previously added custom items out from the base array
-	 *     before merging/returning to allow for resetting to the base array.
-	 *
-	 * {@internal Function is static as it doesn't use any of the properties or others
-	 * methods anyway and this way the `WordPress.NamingConventions.ValidVariableName` sniff
-	 * which extends an upstream sniff can also use it.}}
-	 *
-	 * @since 0.11.0
-	 * @since 2.0.0  No longer supports custom array properties which were incorrectly
-	 *               passed as a string.
-	 *
-	 * @param array $custom Custom list as provided via a ruleset.
-	 * @param array $base   Optional. Base list. Defaults to an empty array.
-	 *                      Expects `value => true` format when `$flip` is true.
-	 * @param bool  $flip   Optional. Whether or not to flip the custom list.
-	 *                      Defaults to true.
-	 * @return array
-	 */
-	public static function merge_custom_array( $custom, $base = array(), $flip = true ) {
-		if ( true === $flip ) {
-			$base = array_filter( $base );
-		}
-
-		if ( empty( $custom ) || ! \is_array( $custom ) ) {
-			return $base;
-		}
-
-		if ( true === $flip ) {
-			$custom = array_fill_keys( $custom, false );
-		}
-
-		if ( empty( $base ) ) {
-			return $custom;
-		}
-
-		return array_merge( $base, $custom );
-	}
-
 	/**
 	 * Get the last pointer in a line.
 	 *

diff --git a/WordPress/Sniffs/DB/DirectDatabaseQuerySniff.php b/WordPress/Sniffs/DB/DirectDatabaseQuerySniff.php
@@ -9,8 +9,9 @@
 
 namespace WordPressCS\WordPress\Sniffs\DB;
 
-use WordPressCS\WordPress\Sniff;
 use PHP_CodeSniffer\Util\Tokens;
+use WordPressCS\WordPress\Helpers\RulesetPropertyHelper;
+use WordPressCS\WordPress\Sniff;
 
 /**
  * Flag Database direct queries.
@@ -275,7 +276,7 @@ protected function mergeFunctionLists() {
 		}
 
 		if ( $this->customCacheGetFunctions !== $this->addedCustomFunctions['cacheget'] ) {
-			$this->cacheGetFunctions = $this->merge_custom_array(
+			$this->cacheGetFunctions = RulesetPropertyHelper::merge_custom_array(
 				$this->customCacheGetFunctions,
 				$this->cacheGetFunctions
 			);
@@ -284,7 +285,7 @@ protected function mergeFunctionLists() {
 		}
 
 		if ( $this->customCacheSetFunctions !== $this->addedCustomFunctions['cacheset'] ) {
-			$this->cacheSetFunctions = $this->merge_custom_array(
+			$this->cacheSetFunctions = RulesetPropertyHelper::merge_custom_array(
 				$this->customCacheSetFunctions,
 				$this->cacheSetFunctions
 			);
@@ -293,7 +294,7 @@ protected function mergeFunctionLists() {
 		}
 
 		if ( $this->customCacheDeleteFunctions !== $this->addedCustomFunctions['cachedelete'] ) {
-			$this->cacheDeleteFunctions = $this->merge_custom_array(
+			$this->cacheDeleteFunctions = RulesetPropertyHelper::merge_custom_array(
 				$this->customCacheDeleteFunctions,
 				$this->cacheDeleteFunctions
 			);

diff --git a/WordPress/Sniffs/NamingConventions/PrefixAllGlobalsSniff.php b/WordPress/Sniffs/NamingConventions/PrefixAllGlobalsSniff.php
@@ -20,6 +20,7 @@
 use WordPressCS\WordPress\AbstractFunctionParameterSniff;
 use WordPressCS\WordPress\Helpers\DeprecationHelper;
 use WordPressCS\WordPress\Helpers\IsUnitTestTrait;
+use WordPressCS\WordPress\Helpers\RulesetPropertyHelper;
 use WordPressCS\WordPress\Helpers\WPHookHelper;
 
 /**
@@ -283,7 +284,7 @@ public function process_token( $stackPtr ) {
 			}
 		}
 
-		$this->prefixes = $this->merge_custom_array( $this->prefixes, array(), false );
+		$this->prefixes = RulesetPropertyHelper::merge_custom_array( $this->prefixes, array(), false );
 		if ( empty( $this->prefixes ) ) {
 			// No prefixes passed, nothing to do.
 			return;

diff --git a/WordPress/Sniffs/NamingConventions/ValidVariableNameSniff.php b/WordPress/Sniffs/NamingConventions/ValidVariableNameSniff.php
@@ -12,6 +12,7 @@
 use PHP_CodeSniffer\Sniffs\AbstractVariableSniff as PHPCS_AbstractVariableSniff;
 use PHP_CodeSniffer\Files\File;
 use PHP_CodeSniffer\Util\Tokens;
+use WordPressCS\WordPress\Helpers\RulesetPropertyHelper;
 use WordPressCS\WordPress\Sniff;
 
 /**
@@ -288,9 +289,9 @@ public static function isSnakeCase( $var_name ) {
 	protected function merge_allow_lists() {
 		if ( $this->allowed_custom_properties !== $this->addedCustomProperties['properties'] ) {
 			// Fix property potentially passed as comma-delimited string.
-			$customProperties = Sniff::merge_custom_array( $this->allowed_custom_properties, array(), false );
+			$customProperties = RulesetPropertyHelper::merge_custom_array( $this->allowed_custom_properties, array(), false );
 
-			$this->allowed_mixed_case_member_var_names = Sniff::merge_custom_array(
+			$this->allowed_mixed_case_member_var_names = RulesetPropertyHelper::merge_custom_array(
 				$customProperties,
 				$this->allowed_mixed_case_member_var_names
 			);

diff --git a/WordPress/Sniffs/PHP/NoSilencedErrorsSniff.php b/WordPress/Sniffs/PHP/NoSilencedErrorsSniff.php
@@ -9,8 +9,9 @@
 
 namespace WordPressCS\WordPress\Sniffs\PHP;
 
-use WordPressCS\WordPress\Sniff;
 use PHP_CodeSniffer\Util\Tokens;
+use WordPressCS\WordPress\Helpers\RulesetPropertyHelper;
+use WordPressCS\WordPress\Sniff;
 
 /**
  * Discourage the use of the PHP error silencing operator.
@@ -183,7 +184,7 @@ public function register() {
 	 */
 	public function process_token( $stackPtr ) {
 		// Handle the user-defined custom function list.
-		$this->customAllowedFunctionsList = $this->merge_custom_array( $this->customAllowedFunctionsList, array(), false );
+		$this->customAllowedFunctionsList = RulesetPropertyHelper::merge_custom_array( $this->customAllowedFunctionsList, array(), false );
 		$this->customAllowedFunctionsList = array_map( 'strtolower', $this->customAllowedFunctionsList );
 
 		/*

diff --git a/WordPress/Sniffs/Security/EscapeOutputSniff.php b/WordPress/Sniffs/Security/EscapeOutputSniff.php
@@ -12,6 +12,7 @@
 use PHP_CodeSniffer\Util\Tokens;
 use PHPCSUtils\Utils\PassedParameters;
 use PHPCSUtils\Utils\TextStrings;
+use WordPressCS\WordPress\Helpers\RulesetPropertyHelper;
 use WordPressCS\WordPress\Helpers\VariableHelper;
 use WordPressCS\WordPress\Sniff;
 
@@ -478,9 +479,9 @@ public function process_token( $stackPtr ) {
 	 */
 	protected function mergeFunctionLists() {
 		if ( $this->customEscapingFunctions !== $this->addedCustomFunctions['escape'] ) {
-			$customEscapeFunctions = $this->merge_custom_array( $this->customEscapingFunctions, array(), false );
+			$customEscapeFunctions = RulesetPropertyHelper::merge_custom_array( $this->customEscapingFunctions, array(), false );
 
-			$this->escapingFunctions = $this->merge_custom_array(
+			$this->escapingFunctions = RulesetPropertyHelper::merge_custom_array(
 				$customEscapeFunctions,
 				$this->escapingFunctions
 			);
@@ -489,7 +490,7 @@ protected function mergeFunctionLists() {
 		}
 
 		if ( $this->customAutoEscapedFunctions !== $this->addedCustomFunctions['autoescape'] ) {
-			$this->autoEscapedFunctions = $this->merge_custom_array(
+			$this->autoEscapedFunctions = RulesetPropertyHelper::merge_custom_array(
 				$this->customAutoEscapedFunctions,
 				$this->autoEscapedFunctions
 			);
@@ -499,7 +500,7 @@ protected function mergeFunctionLists() {
 
 		if ( $this->customPrintingFunctions !== $this->addedCustomFunctions['print'] ) {
 
-			$this->printingFunctions = $this->merge_custom_array(
+			$this->printingFunctions = RulesetPropertyHelper::merge_custom_array(
 				$this->customPrintingFunctions,
 				$this->printingFunctions
 			);

diff --git a/WordPress/Sniffs/Security/NonceVerificationSniff.php b/WordPress/Sniffs/Security/NonceVerificationSniff.php
@@ -11,6 +11,7 @@
 
 use PHP_CodeSniffer\Util\Tokens;
 use PHPCSUtils\Utils\MessageHelper;
+use WordPressCS\WordPress\Helpers\RulesetPropertyHelper;
 use WordPressCS\WordPress\Helpers\VariableHelper;
 use WordPressCS\WordPress\Sniff;
 
@@ -296,7 +297,7 @@ private function has_nonce_check( $stackPtr ) {
 	 */
 	protected function mergeFunctionLists() {
 		if ( $this->customNonceVerificationFunctions !== $this->addedCustomFunctions['nonce'] ) {
-			$this->nonceVerificationFunctions = $this->merge_custom_array(
+			$this->nonceVerificationFunctions = RulesetPropertyHelper::merge_custom_array(
 				$this->customNonceVerificationFunctions,
 				$this->nonceVerificationFunctions
 			);
@@ -305,7 +306,7 @@ protected function mergeFunctionLists() {
 		}
 
 		if ( $this->customSanitizingFunctions !== $this->addedCustomFunctions['sanitize'] ) {
-			$this->sanitizingFunctions = $this->merge_custom_array(
+			$this->sanitizingFunctions = RulesetPropertyHelper::merge_custom_array(
 				$this->customSanitizingFunctions,
 				$this->sanitizingFunctions
 			);
@@ -314,7 +315,7 @@ protected function mergeFunctionLists() {
 		}
 
 		if ( $this->customUnslashingSanitizingFunctions !== $this->addedCustomFunctions['unslashsanitize'] ) {
-			$this->unslashingSanitizingFunctions = $this->merge_custom_array(
+			$this->unslashingSanitizingFunctions = RulesetPropertyHelper::merge_custom_array(
 				$this->customUnslashingSanitizingFunctions,
 				$this->unslashingSanitizingFunctions
 			);

diff --git a/WordPress/Sniffs/Security/ValidatedSanitizedInputSniff.php b/WordPress/Sniffs/Security/ValidatedSanitizedInputSniff.php
@@ -11,6 +11,7 @@
 
 use PHP_CodeSniffer\Util\Tokens;
 use PHPCSUtils\Utils\TextStrings;
+use WordPressCS\WordPress\Helpers\RulesetPropertyHelper;
 use WordPressCS\WordPress\Helpers\VariableHelper;
 use WordPressCS\WordPress\Sniff;
 
@@ -212,7 +213,7 @@ function( $embed ) {
 	 */
 	protected function mergeFunctionLists() {
 		if ( $this->customSanitizingFunctions !== $this->addedCustomFunctions['sanitize'] ) {
-			$this->sanitizingFunctions = $this->merge_custom_array(
+			$this->sanitizingFunctions = RulesetPropertyHelper::merge_custom_array(
 				$this->customSanitizingFunctions,
 				$this->sanitizingFunctions
 			);
@@ -221,7 +222,7 @@ protected function mergeFunctionLists() {
 		}
 
 		if ( $this->customUnslashingSanitizingFunctions !== $this->addedCustomFunctions['unslashsanitize'] ) {
-			$this->unslashingSanitizingFunctions = $this->merge_custom_array(
+			$this->unslashingSanitizingFunctions = RulesetPropertyHelper::merge_custom_array(
 				$this->customUnslashingSanitizingFunctions,
 				$this->unslashingSanitizingFunctions
 			);