Repository: WordPress/WordPress-Coding-Standards (php)

Issue:
Change the property name in the MinimumWPVersionTrait trait
## Is your feature request related to a problem?

In the `MinimumWPVersionTrait` trait, we have a public property that can be referenced in the sniffs, called `$minimum_supported_version`. However, the CLI argument for setting the minimum supported WP version is named `minimum_supported_wp_version`.

https://github.com/WordPress/WordPress-Coding-Standards/blob/9544c7e0e78fc85405b32076ec2949c2e59854d1/WordPress/Helpers/MinimumWPVersionTrait.php#L71

And that can cause some confusion when writing sniffs - in the tests and in the sniffs we are using one naming (`minimum_supported_version`), and when the property should be consumed, either via CLI, or via ruleset, we need to use the other name (`minimum_supported_wp_version`):

```xml
<config name="minimum_supported_wp_version" value="5.4"/>
```

or

```bash
phpcs --runtime-set minimum_supported_wp_version 4.5
```

## Describe the solution you'd like

The solution would be to change this property in the trait to be named `$minimum_supported_wp_version`. All the sniffs consuming this trait would be affected, and the tests as well, but since we would release this in the 3.0.0 version, this is an allowed BC break. 

Pull request:
MinimumWPVersionTrait: rename minimum WP version property
As discussed in #2113, this changes the name for both the CLI setting as well as the property to `minimum_wp_version` in all applicable places.

Note: documentation (`phpcs.xml.dist.sample` and the Wiki) is not being updated in this PR. The wiki should be reviewed and updated just before release. The update to the `phpcs.xml.dist.sample` file is included in a WIP PR to update all public facing documentation just before the release.

Closes #2113

Note: This is a **breaking change** and should be so annotated in the changelog.

Patch:
diff --git a/WordPress/Helpers/MinimumWPVersionTrait.php b/WordPress/Helpers/MinimumWPVersionTrait.php
index 232fddc7..96810d35 100644
--- a/WordPress/Helpers/MinimumWPVersionTrait.php
+++ b/WordPress/Helpers/MinimumWPVersionTrait.php
@@ -19,7 +19,7 @@ use PHPCSUtils\BackCompat\Helper;
  * - Add appropriate `use` statement(s) to the file/class which intends to use this functionality.
  * - Call the `MinimumWPVersionTrait::get_wp_version_from_cli()` method in the `process()`/`process_token()`
  *   method.
- * - After that, the `MinimumWPVersionTrait::$minimum_supported_version` property can be freely used
+ * - After that, the `MinimumWPVersionTrait::$minimum_wp_version` property can be freely used
  *   in the sniff.
  *
  * @package WPCS\WordPressCodingStandards
@@ -32,12 +32,12 @@ trait MinimumWPVersionTrait {
 	 * Minimum supported WordPress version.
 	 *
 	 * Currently used by the `WordPress.WP.AlternativeFunctions`,
-	 * `WordPress.WP.DeprecatedClasses`, `WordPress.WP.DeprecatedFunctions`,
-	 * `WordPress.WP.DeprecatedParameter` and the `WordPress.WP.DeprecatedParameterValues` sniff.
+	 * `WordPress.WP.Capabilities`, `WordPress.WP.DeprecatedClasses`,
+	 * `WordPress.WP.DeprecatedFunctions`, `WordPress.WP.DeprecatedParameter`
+	 * and the `WordPress.WP.DeprecatedParameterValues` sniff.
 	 *
-	 * These sniffs will throw an error when usage of a deprecated class/function/parameter
-	 * is detected if the class/function/parameter was deprecated before the minimum
-	 * supported WP version; a warning otherwise.
+	 * These sniffs will adapt their behaviour based on the minimum supported WP version
+	 * indicated.
 	 * By default, it is set to presume that a project will support the current
 	 * WP version and up to three releases before.
 	 *
@@ -48,41 +48,42 @@ trait MinimumWPVersionTrait {
 	 * Example usage:
 	 * <rule ref="WordPress.WP.DeprecatedClasses">
 	 *  <properties>
-	 *   <property name="minimum_supported_version" value="4.3"/>
+	 *   <property name="minimum_wp_version" value="4.3"/>
 	 *  </properties>
 	 * </rule>
 	 *
-	 * Alternatively, the value can be passed in one go for all sniff using it via
+	 * Alternatively, the value can be passed in one go for all sniffs using it via
 	 * the command line or by setting a `<config>` value in a custom phpcs.xml ruleset.
-	 * Note: the `_wp_` in the command line property name!
 	 *
-	 * CL: `phpcs --runtime-set minimum_supported_wp_version 4.5`
-	 * Ruleset: `<config name="minimum_supported_wp_version" value="4.5"/>`
+	 * CL: `phpcs --runtime-set minimum_wp_version 4.5`
+	 * Ruleset: `<config name="minimum_wp_version" value="4.5"/>`
 	 *
 	 * @since 0.14.0 Previously the individual sniffs each contained this property.
-	 * @since 3.0.0  Moved from the Sniff class to this dedicated Trait.
+	 * @since 3.0.0  - Moved from the Sniff class to this dedicated Trait.
+	 *               - The property has been renamed from `$minimum_supported_version` to `$minimum_wp_version`.
+	 *               - The CLI option has been renamed from `minimum_supported_wp_version` to `minimum_wp_version`.
 	 *
 	 * @internal When the value of this property is changed, it will also need
 	 *           to be changed in the `WP/AlternativeFunctionsUnitTest.inc` file.
 	 *
 	 * @var string WordPress version.
 	 */
-	public $minimum_supported_version = '5.1';
+	public $minimum_wp_version = '5.1';
 
 	/**
 	 * Overrule the minimum supported WordPress version with a command-line/config value.
 	 *
 	 * Handle setting the minimum supported WP version in one go for all sniffs which
 	 * expect it via the command line or via a `<config>` variable in a ruleset.
-	 * The config variable overrules the default `$minimum_supported_version` and/or a
-	 * `$minimum_supported_version` set for individual sniffs through the ruleset.
+	 * The config variable overrules the default `$minimum_wp_version` and/or a
+	 * `$minimum_wp_version` set for individual sniffs through the ruleset.
 	 *
 	 * @since 0.14.0
 	 * @since 3.0.0  - Moved from the Sniff class to this dedicated Trait.
 	 *               - Renamed from `get_wp_version_from_cl()` to `get_wp_version_from_cli()`.
 	 */
 	protected function get_wp_version_from_cli() {
-		$cli_supported_version = Helper::getConfigData( 'minimum_supported_wp_version' );
+		$cli_supported_version = Helper::getConfigData( 'minimum_wp_version' );
 
 		if ( empty( $cli_supported_version ) ) {
 			return;
@@ -92,7 +93,7 @@ trait MinimumWPVersionTrait {
 		if ( ! empty( $cli_supported_version )
 			&& filter_var( $cli_supported_version, \FILTER_VALIDATE_FLOAT ) !== false
 		) {
-			$this->minimum_supported_version = $cli_supported_version;
+			$this->minimum_wp_version = $cli_supported_version;
 		}
 	}
 
diff --git a/WordPress/Sniffs/WP/AlternativeFunctionsSniff.php b/WordPress/Sniffs/WP/AlternativeFunctionsSniff.php
index cad367fc..cccaf5dd 100644
--- a/WordPress/Sniffs/WP/AlternativeFunctionsSniff.php
+++ b/WordPress/Sniffs/WP/AlternativeFunctionsSniff.php
@@ -24,7 +24,7 @@ use WordPressCS\WordPress\Helpers\MinimumWPVersionTrait;
  * @since   1.0.0  - Takes the minimum supported WP version into account.
  *                 - Takes exceptions based on passed parameters into account.
  *
- * @uses    \WordPressCS\WordPress\Helpers\MinimumWPVersionTrait::$minimum_supported_version
+ * @uses    \WordPressCS\WordPress\Helpers\MinimumWPVersionTrait::$minimum_wp_version
  */
 class AlternativeFunctionsSniff extends AbstractFunctionRestrictionsSniff {
 
@@ -210,7 +210,7 @@ class AlternativeFunctionsSniff extends AbstractFunctionRestrictionsSniff {
 				 * @see https://developer.wordpress.org/reference/functions/wp_parse_url/#changelog
 				 */
 				if ( PassedParameters::getParameterCount( $this->phpcsFile, $stackPtr ) !== 1
-					&& version_compare( $this->minimum_supported_version, '4.7.0', '<' )
+					&& version_compare( $this->minimum_wp_version, '4.7.0', '<' )
 				) {
 					return;
 				}
@@ -288,7 +288,7 @@ class AlternativeFunctionsSniff extends AbstractFunctionRestrictionsSniff {
 		}
 
 		// Verify if the alternative is available in the minimum supported WP version.
-		if ( version_compare( $this->groups[ $group_name ]['since'], $this->minimum_supported_version, '<=' ) ) {
+		if ( version_compare( $this->groups[ $group_name ]['since'], $this->minimum_wp_version, '<=' ) ) {
 			return parent::process_matched_token( $stackPtr, $group_name, $matched_content );
 		}
 	}
diff --git a/WordPress/Sniffs/WP/CapabilitiesSniff.php b/WordPress/Sniffs/WP/CapabilitiesSniff.php
index b980be1d..942b6b6b 100644
--- a/WordPress/Sniffs/WP/CapabilitiesSniff.php
+++ b/WordPress/Sniffs/WP/CapabilitiesSniff.php
@@ -24,6 +24,8 @@ use WordPressCS\WordPress\Helpers\MinimumWPVersionTrait;
  * @package WPCS\WordPressCodingStandards
  *
  * @since   3.0.0
+ *
+ * @uses    \WordPressCS\WordPress\Helpers\MinimumWPVersionTrait::$minimum_wp_version
  */
 class CapabilitiesSniff extends AbstractFunctionParameterSniff {
 
@@ -432,7 +434,7 @@ class CapabilitiesSniff extends AbstractFunctionParameterSniff {
 
 		if ( isset( $this->deprecated_capabilities[ $matched_parameter ] ) ) {
 			$this->get_wp_version_from_cli( $this->phpcsFile );
-			$is_error = version_compare( $this->deprecated_capabilities[ $matched_parameter ], $this->minimum_supported_version, '<' );
+			$is_error = version_compare( $this->deprecated_capabilities[ $matched_parameter ], $this->minimum_wp_version, '<' );
 
 			$data = array(
 				$matched_parameter,
diff --git a/WordPress/Sniffs/WP/DeprecatedClassesSniff.php b/WordPress/Sniffs/WP/DeprecatedClassesSniff.php
index c1fd8e05..effc42df 100644
--- a/WordPress/Sniffs/WP/DeprecatedClassesSniff.php
+++ b/WordPress/Sniffs/WP/DeprecatedClassesSniff.php
@@ -30,7 +30,7 @@ use WordPressCS\WordPress\Helpers\MinimumWPVersionTrait;
  *                 being provided via the command-line or as as <config> value
  *                 in a custom ruleset.
  *
- * @uses    \WordPressCS\WordPress\Helpers\MinimumWPVersionTrait::$minimum_supported_version
+ * @uses    \WordPressCS\WordPress\Helpers\MinimumWPVersionTrait::$minimum_wp_version
  */
 class DeprecatedClassesSniff extends AbstractClassRestrictionsSniff {
 
@@ -116,7 +116,7 @@ class DeprecatedClassesSniff extends AbstractClassRestrictionsSniff {
 			$this->phpcsFile,
 			$message,
 			$stackPtr,
-			( version_compare( $this->deprecated_classes[ $class_name ]['version'], $this->minimum_supported_version, '<' ) ),
+			( version_compare( $this->deprecated_classes[ $class_name ]['version'], $this->minimum_wp_version, '<' ) ),
 			MessageHelper::stringToErrorcode( $class_name . 'Found' ),
 			$data
 		);
diff --git a/WordPress/Sniffs/WP/DeprecatedFunctionsSniff.php b/WordPress/Sniffs/WP/DeprecatedFunctionsSniff.php
index b9379c4e..2e5968d0 100644
--- a/WordPress/Sniffs/WP/DeprecatedFunctionsSniff.php
+++ b/WordPress/Sniffs/WP/DeprecatedFunctionsSniff.php
@@ -30,7 +30,7 @@ use WordPressCS\WordPress\Helpers\MinimumWPVersionTrait;
  *                 being provided via the command-line or as as <config> value
  *                 in a custom ruleset.
  *
- * @uses    \WordPressCS\WordPress\Helpers\MinimumWPVersionTrait::$minimum_supported_version
+ * @uses    \WordPressCS\WordPress\Helpers\MinimumWPVersionTrait::$minimum_wp_version
  */
 class DeprecatedFunctionsSniff extends AbstractFunctionRestrictionsSniff {
 
@@ -1418,7 +1418,7 @@ class DeprecatedFunctionsSniff extends AbstractFunctionRestrictionsSniff {
 			$this->phpcsFile,
 			$message,
 			$stackPtr,
-			( version_compare( $this->deprecated_functions[ $function_name ]['version'], $this->minimum_supported_version, '<' ) ),
+			( version_compare( $this->deprecated_functions[ $function_name ]['version'], $this->minimum_wp_version, '<' ) ),
 			MessageHelper::stringToErrorcode( $matched_content . 'Found' ),
 			$data
 		);
diff --git a/WordPress/Sniffs/WP/DeprecatedParameterValuesSniff.php b/WordPress/Sniffs/WP/DeprecatedParameterValuesSniff.php
index be90ca70..c726a840 100644
--- a/WordPress/Sniffs/WP/DeprecatedParameterValuesSniff.php
+++ b/WordPress/Sniffs/WP/DeprecatedParameterValuesSniff.php
@@ -22,7 +22,7 @@ use WordPressCS\WordPress\Helpers\MinimumWPVersionTrait;
  *
  * @since   1.0.0
  *
- * @uses    \WordPressCS\WordPress\Helpers\MinimumWPVersionTrait::$minimum_supported_version
+ * @uses    \WordPressCS\WordPress\Helpers\MinimumWPVersionTrait::$minimum_wp_version
  */
 class DeprecatedParameterValuesSniff extends AbstractFunctionParameterSniff {
 
@@ -208,7 +208,7 @@ class DeprecatedParameterValuesSniff extends AbstractFunctionParameterSniff {
 			$data[]   = $parameter_args[ $matched_parameter ]['alt'];
 		}
 
-		$is_error = version_compare( $parameter_args[ $matched_parameter ]['version'], $this->minimum_supported_version, '<' );
+		$is_error = version_compare( $parameter_args[ $matched_parameter ]['version'], $this->minimum_wp_version, '<' );
 		MessageHelper::addMessage(
 			$this->phpcsFile,
 			$message,
diff --git a/WordPress/Sniffs/WP/DeprecatedParametersSniff.php b/WordPress/Sniffs/WP/DeprecatedParametersSniff.php
index 787da508..623e5fbc 100644
--- a/WordPress/Sniffs/WP/DeprecatedParametersSniff.php
+++ b/WordPress/Sniffs/WP/DeprecatedParametersSniff.php
@@ -31,7 +31,7 @@ use WordPressCS\WordPress\Helpers\MinimumWPVersionTrait;
  *                 being provided via the command-line or as as <config> value
  *                 in a custom ruleset.
  *
- * @uses    \WordPressCS\WordPress\Helpers\MinimumWPVersionTrait::$minimum_supported_version
+ * @uses    \WordPressCS\WordPress\Helpers\MinimumWPVersionTrait::$minimum_wp_version
  */
 class DeprecatedParametersSniff extends AbstractFunctionParameterSniff {
 
@@ -319,7 +319,7 @@ class DeprecatedParametersSniff extends AbstractFunctionParameterSniff {
 			}
 
 			$message  = 'The parameter "%s" at position #%s of %s() has been deprecated since WordPress version %s.';
-			$is_error = version_compare( $parameter_args['version'], $this->minimum_supported_version, '<' );
+			$is_error = version_compare( $parameter_args['version'], $this->minimum_wp_version, '<' );
 			$code     = MessageHelper::stringToErrorcode( ucfirst( $matched_content ) . 'Param' . $position . 'Found' );
 
 			$data = array(


Test patch:
diff --git a/WordPress/Tests/WP/AlternativeFunctionsUnitTest.inc b/WordPress/Tests/WP/AlternativeFunctionsUnitTest.inc
index d819f25a..c74000b6 100644
--- a/WordPress/Tests/WP/AlternativeFunctionsUnitTest.inc
+++ b/WordPress/Tests/WP/AlternativeFunctionsUnitTest.inc
@@ -28,17 +28,17 @@ srand(); // Warning.
 mt_srand(); // Warning.
 wp_rand(); // OK.
 
-// phpcs:set WordPress.WP.AlternativeFunctions minimum_supported_version 4.0
+// phpcs:set WordPress.WP.AlternativeFunctions minimum_wp_version 4.0
 parse_url( 'http://example.com/' ); // OK.
-// phpcs:set WordPress.WP.AlternativeFunctions minimum_supported_version 4.6
+// phpcs:set WordPress.WP.AlternativeFunctions minimum_wp_version 4.6
 
 strip_tags( $something, '<iframe>' ); // OK.
 
-// phpcs:set WordPress.WP.AlternativeFunctions minimum_supported_version 4.0
+// phpcs:set WordPress.WP.AlternativeFunctions minimum_wp_version 4.0
 parse_url($url, PHP_URL_QUERY); // OK.
-// phpcs:set WordPress.WP.AlternativeFunctions minimum_supported_version 4.7
+// phpcs:set WordPress.WP.AlternativeFunctions minimum_wp_version 4.7
 parse_url($url, PHP_URL_SCHEME); // Warning.
-// phpcs:set WordPress.WP.AlternativeFunctions minimum_supported_version 4.6
+// phpcs:set WordPress.WP.AlternativeFunctions minimum_wp_version 4.6
 
 file_get_contents( $local_file, true ); // OK.
 file_get_contents( $url, false ); // Warning.
diff --git a/WordPress/Tests/WP/CapabilitiesUnitTest.1.inc b/WordPress/Tests/WP/CapabilitiesUnitTest.1.inc
index 40226dcd..f0de254a 100644
--- a/WordPress/Tests/WP/CapabilitiesUnitTest.1.inc
+++ b/WordPress/Tests/WP/CapabilitiesUnitTest.1.inc
@@ -42,10 +42,10 @@ if ( author_can( $post, '' ) ) { } // Error.
 /*
  * Deprecated capabilities.
  */
-// phpcs:set WordPress.WP.Capabilities minimum_supported_version 2.9
+// phpcs:set WordPress.WP.Capabilities minimum_wp_version 2.9
 if ( author_can( $post, 'level_3' ) ) { } // Warning.
 
-// phpcs:set WordPress.WP.Capabilities minimum_supported_version 5.9
+// phpcs:set WordPress.WP.Capabilities minimum_wp_version 5.9
 if ( author_can( $post, 'level_5' ) ) { } // Error.
 add_options_page( 'page_title', 'menu_title', 'level_10', 'menu_slug', 'function' ); // Error.
 
diff --git a/WordPress/Tests/WP/CapabilitiesUnitTest.php b/WordPress/Tests/WP/CapabilitiesUnitTest.php
index dc8326e0..34b7b50f 100644
--- a/WordPress/Tests/WP/CapabilitiesUnitTest.php
+++ b/WordPress/Tests/WP/CapabilitiesUnitTest.php
@@ -31,12 +31,12 @@ class CapabilitiesUnitTest extends AbstractSniffUnitTest {
 		if ( 'CapabilitiesUnitTest.1.inc' === $filename ) {
 			$config->warningSeverity = 3;
 		} elseif ( 'CapabilitiesUnitTest.2.inc' === $filename ) {
-			Helper::setConfigData( 'minimum_supported_wp_version', '2.9', true, $config );
+			Helper::setConfigData( 'minimum_wp_version', '2.9', true, $config );
 		} elseif ( 'CapabilitiesUnitTest.3.inc' === $filename ) {
-			Helper::setConfigData( 'minimum_supported_wp_version', '6.1', true, $config );
+			Helper::setConfigData( 'minimum_wp_version', '6.1', true, $config );
 		} else {
 			// Delete for other files.
-			Helper::setConfigData( 'minimum_supported_wp_version', null, true, $config );
+			Helper::setConfigData( 'minimum_wp_version', null, true, $config );
 		}
 	}