Merge pull request #1410 from tomjn/vip-migrate-filesystem-write-disa…

…llow-sniff Deprecate Remaining VIP sniffs
WordPress · Jul 16, 2018 · 58b4c23 · 58b4c23
2 parents c27ae76 + 50c6d77
commit 58b4c23
Show file tree

Hide file tree

Showing 26 changed files with 433 additions and 110 deletions.
diff --git a/README.md b/README.md
@@ -133,8 +133,10 @@ You can use the following as standard names when invoking `phpcs` to select snif
   - `WordPress-Docs` - additional ruleset for [WordPress inline documentation standards](https://make.wordpress.org/core/handbook/best-practices/inline-documentation-standards/)
   - `WordPress-Extra` - extended ruleset for recommended best practices, not sufficiently covered in the WordPress core coding standards
     - includes `WordPress-Core`
-  - `WordPress-VIP` - extended ruleset for [WordPress.com VIP coding requirements](https://vip.wordpress.com/documentation/code-review-what-we-look-for/)
-    - includes `WordPress-Core`
+
+**Notes:** This WPCS package contains the sniffs for another ruleset, `WordPress-VIP`. This ruleset was originally intended to aid with the [WordPress.com VIP coding requirements](https://vip.wordpress.com/documentation/code-review-what-we-look-for/), but this is no longer used or recommended by the WordPress.com VIP team or their clients, since they prefer to use their [official VIP coding standards](https://github.com/Automattic/VIP-Coding-Standards) ruleset instead.
+
+Before WPCS `1.0.0`, the WordPress-VIP ruleset was included as part of the complete `WordPress` ruleset. **As of `1.0.0` the `WordPress-VIP` ruleset is not part of the WordPress ruleset, and it is deprecated**. The remaining `WordPress-VIP` sniffs may still be referenced in custom rulesets, so to maintain some backwards compatibility, they will remain in WPCS until `2.0.0`. See [#1309](https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards/issues/1309) for more information.
 
 ### Using a custom ruleset
 

diff --git a/WordPress-VIP/ruleset.xml b/WordPress-VIP/ruleset.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0"?>
 <ruleset name="WordPress VIP">
-	<description>WordPress.com VIP Coding Standards</description>
+	<description>Deprecated WordPress.com VIP Coding Standards, use the official VIP coding standards instead, these can be found at https://github.com/Automattic/VIP-Coding-Standards</description>
 
 	<autoload>./../WordPress/PHPCSAliases.php</autoload>
 
@@ -131,7 +131,12 @@
 	#############################################################################
 	-->
 
-	<!-- Prevent deprecation notice when the sniff is not explicitely included. -->
+	<!-- Prevent deprecation notice when the sniff is not explicitly included. -->
+	<rule ref="WordPress.VIP.AdminBarRemoval.DeprecatedSniff">
+		<severity>0</severity>
+	</rule>
+
+	<!-- Prevent deprecation notice when the sniff is not explicitly included. -->
 	<rule ref="WordPress.VIP.DirectDatabaseQuery.DeprecatedSniff">
 		<severity>0</severity>
 	</rule>
@@ -147,7 +152,7 @@
 		<severity>0</severity>
 	</rule>
 
-	<!-- Prevent deprecation notice when the sniff is not explicitely included. -->
+	<!-- Prevent deprecation notice when the sniff is not explicitly included. -->
 	<rule ref="WordPress.VIP.SlowDBQuery.DeprecatedSniff">
 		<severity>0</severity>
 	</rule>
@@ -169,7 +174,7 @@
 		<severity>0</severity>
 	</rule>
 
-	<!-- Prevent deprecation notice when the sniff is not explicitely included. -->
+	<!-- Prevent deprecation notice when the sniff is not explicitly included. -->
 	<rule ref="WordPress.VIP.PluginMenuSlug.DeprecatedSniff">
 		<severity>0</severity>
 	</rule>
@@ -179,7 +184,7 @@
 		<severity>0</severity>
 	</rule>
 
-	<!-- Prevent deprecation notice when the sniff is not explicitely included. -->
+	<!-- Prevent deprecation notice when the sniff is not explicitly included. -->
 	<rule ref="WordPress.VIP.ValidatedSanitizedInput.DeprecatedSniff">
 		<severity>0</severity>
 	</rule>
@@ -198,7 +203,7 @@
 		<severity>0</severity>
 	</rule>
 
-	<!-- Prevent deprecation notice when the sniff is not explicitely included. -->
+	<!-- Prevent deprecation notice when the sniff is not explicitly included. -->
 	<rule ref="WordPress.VIP.CronInterval.DeprecatedSniff">
 		<severity>0</severity>
 	</rule>
@@ -211,7 +216,42 @@
 		<severity>0</severity>
 	</rule>
 
-	<!-- Prevent deprecation notice when the sniff is not explicitely included. -->
+	<!-- Prevent deprecation notice when the sniff is not explicitly included. -->
+	<rule ref="WordPress.VIP.FileSystemWritesDisallow.DeprecatedSniff">
+		<severity>0</severity>
+	</rule>
+
+	<!-- Prevent deprecation notice when the sniff is not explicitly included. -->
+	<rule ref="WordPress.VIP.OrderByRand.DeprecatedSniff">
+		<severity>0</severity>
+	</rule>
+
+	<!-- Prevent deprecation notice when the sniff is not explicitly included. -->
+	<rule ref="WordPress.VIP.RestrictedFunctions.DeprecatedSniff">
+		<severity>0</severity>
+	</rule>
+
+	<!-- Prevent deprecation notice when the sniff is not explicitly included. -->
+	<rule ref="WordPress.VIP.RestrictedVariables.DeprecatedSniff">
+		<severity>0</severity>
+	</rule>
+
+	<!-- Prevent deprecation notice when the sniff is not explicitly included. -->
+	<rule ref="WordPress.VIP.SessionFunctionsUsage.DeprecatedSniff">
+		<severity>0</severity>
+	</rule>
+
+	<!-- Prevent deprecation notice when the sniff is not explicitly included. -->
+	<rule ref="WordPress.VIP.SessionVariableUsage.DeprecatedSniff">
+		<severity>0</severity>
+	</rule>
+
+	<!-- Prevent deprecation notice when the sniff is not explicitly included. -->
+	<rule ref="WordPress.VIP.SuperGlobalInputUsage.DeprecatedSniff">
+		<severity>0</severity>
+	</rule>
+
+	<!-- Prevent deprecation notice when the sniff is not explicitly included. -->
 	<rule ref="WordPress.VIP.TimezoneChange.DeprecatedSniff">
 		<severity>0</severity>
 	</rule>

diff --git a/WordPress/AbstractVariableRestrictionsSniff.php b/WordPress/AbstractVariableRestrictionsSniff.php
@@ -22,6 +22,8 @@
  *                 `WordPress_Sniffs_Variables_VariableRestrictionsSniff` to
  *                 `WordPress_AbstractVariableRestrictionsSniff`.
  * @since   0.11.0 Extends the WordPress_Sniff class.
+ *
+ * @deprecated 1.0.0 All sniffs depending on this class were deprecated.
  */
 abstract class AbstractVariableRestrictionsSniff extends Sniff {
 

diff --git a/WordPress/Sniff.php b/WordPress/Sniff.php
@@ -2371,6 +2371,7 @@ public function get_declared_namespace_name( $stackPtr ) {
 	 *               originally created.
 	 * @since 0.13.0 The $stackPtr parameter is now optional. Either that or the
 	 *               $content parameter has to be passed.
+	 * @deprecated 1.0.0 This method is only used by deprecated sniffs.
 	 *
 	 * @param string $tag_name The name of the HTML tag without brackets. So if
 	 *                         searching for '<span...', this would be 'span'.

diff --git a/WordPress/Sniffs/VIP/AdminBarRemovalSniff.php b/WordPress/Sniffs/VIP/AdminBarRemovalSniff.php
@@ -24,9 +24,25 @@
  *                 - Added the $remove_only property.
  *                 - Now also sniffs for manipulation of the admin bar visibility through CSS.
  * @since   0.13.0 Class name changed: this class is now namespaced.
+ *
+ * @deprecated 1.0.0  This sniff has been deprecated.
+ *                    This file remains for now to prevent BC breaks.
  */
 class AdminBarRemovalSniff extends AbstractFunctionParameterSniff {
 
+	/**
+	 * Keep track of whether the warnings have been thrown to prevent
+	 * the messages being thrown for every token triggering the sniff.
+	 *
+	 * @since 1.0.0
+	 *
+	 * @var array
+	 */
+	private $thrown = array(
+		'DeprecatedSniff'                 => false,
+		'FoundPropertyForDeprecatedSniff' => false,
+	);
+
 	/**
 	 * A list of tokenizers this sniff supports.
 	 *
@@ -167,7 +183,9 @@ public function register() {
 	}
 
 	/**
-	 * Processes this test, when one of its tokens is encountered.
+	 * Process the token and handle the deprecation notices.
+	 *
+	 * @since 1.0.0 Adjusted to allow for throwing the deprecation notices.
 	 *
 	 * @param int $stackPtr The position of the current token in the stack.
 	 *
@@ -176,6 +194,23 @@ public function register() {
 	 */
 	public function process_token( $stackPtr ) {
 
+		if ( false === $this->thrown['DeprecatedSniff'] ) {
+			$this->thrown['DeprecatedSniff'] = $this->phpcsFile->addWarning(
+				'The "WordPress.VIP.AdminBarRemoval" sniff has been deprecated. Please update your custom ruleset.',
+				0,
+				'DeprecatedSniff'
+			);
+		}
+
+		if ( ( true !== $this->remove_only ) &&
+			false === $this->thrown['FoundPropertyForDeprecatedSniff'] ) {
+			$this->thrown['FoundPropertyForDeprecatedSniff'] = $this->phpcsFile->addWarning(
+				'The "WordPress.VIP.AdminBarRemoval" sniff has been deprecated. Please update your custom ruleset.',
+				0,
+				'FoundPropertyForDeprecatedSniff'
+			);
+		}
+
 		$file_name      = $this->phpcsFile->getFileName();
 		$file_extension = substr( strrchr( $file_name, '.' ), 1 );
 

diff --git a/WordPress/Sniffs/VIP/FileSystemWritesDisallowSniff.php b/WordPress/Sniffs/VIP/FileSystemWritesDisallowSniff.php
@@ -22,6 +22,9 @@
  * @since   0.11.0 Extends the WordPress_AbstractFunctionRestrictionsSniff instead of the
  *                 Generic_Sniffs_PHP_ForbiddenFunctionsSniff.
  * @since   0.13.0 Class name changed: this class is now namespaced.
+ *
+ * @deprecated 1.0.0  This sniff has been deprecated.
+ *                    This file remains for now to prevent BC breaks.
  */
 class FileSystemWritesDisallowSniff extends AbstractFunctionRestrictionsSniff {
 
@@ -32,6 +35,19 @@ class FileSystemWritesDisallowSniff extends AbstractFunctionRestrictionsSniff {
 	 */
 	public $error = true;
 
+	/**
+	 * Keep track of whether the warnings have been thrown to prevent
+	 * the messages being thrown for every token triggering the sniff.
+	 *
+	 * @since 1.0.0
+	 *
+	 * @var array
+	 */
+	private $thrown = array(
+		'DeprecatedSniff'                 => false,
+		'FoundPropertyForDeprecatedSniff' => false,
+	);
+
 	/**
 	 * Groups of functions to restrict.
 	 *
@@ -102,4 +118,35 @@ public function getGroups() {
 		return $groups;
 	}
 
+	/**
+	 * Process the token and handle the deprecation notices.
+	 *
+	 * @since 1.0.0 Added to allow for throwing the deprecation notices.
+	 *
+	 * @param int $stackPtr The position of the current token in the stack.
+	 *
+	 * @return void|int
+	 */
+	public function process_token( $stackPtr ) {
+		if ( false === $this->thrown['DeprecatedSniff'] ) {
+			$this->thrown['DeprecatedSniff'] = $this->phpcsFile->addWarning(
+				'The "WordPress.VIP.FileSystemWritesDisallow" sniff has been deprecated. Please update your custom ruleset.',
+				0,
+				'DeprecatedSniff'
+			);
+		}
+
+		if ( ( ! empty( $this->exclude ) || true !== $this->error )
+			&& false === $this->thrown['FoundPropertyForDeprecatedSniff']
+		) {
+			$this->thrown['FoundPropertyForDeprecatedSniff'] = $this->phpcsFile->addWarning(
+				'The "WordPress.VIP.FileSystemWritesDisallow" sniff has been deprecated. Please update your custom ruleset.',
+				0,
+				'FoundPropertyForDeprecatedSniff'
+			);
+		}
+
+		return parent::process_token( $stackPtr );
+	}
+
 }
diff --git a/WordPress/Sniffs/VIP/OrderByRandSniff.php b/WordPress/Sniffs/VIP/OrderByRandSniff.php
@@ -20,9 +20,25 @@
  *
  * @since   0.9.0
  * @since   0.13.0 Class name changed: this class is now namespaced.
+ *
+ * @deprecated 1.0.0  This sniff has been deprecated.
+ *                    This file remains for now to prevent BC breaks.
  */
 class OrderByRandSniff extends AbstractArrayAssignmentRestrictionsSniff {
 
+	/**
+	 * Keep track of whether the warnings have been thrown to prevent
+	 * the messages being thrown for every token triggering the sniff.
+	 *
+	 * @since 1.0.0
+	 *
+	 * @var array
+	 */
+	private $thrown = array(
+		'DeprecatedSniff'                 => false,
+		'FoundPropertyForDeprecatedSniff' => false,
+	);
+
 	/**
 	 * Groups of variables to restrict.
 	 *
@@ -39,6 +55,37 @@ public function getGroups() {
 		);
 	}
 
+	/**
+	 * Process the token and handle the deprecation notices.
+	 *
+	 * @since 1.0.0 Added to allow for throwing the deprecation notices.
+	 *
+	 * @param int $stackPtr The position of the current token in the stack.
+	 *
+	 * @return void|int
+	 */
+	public function process_token( $stackPtr ) {
+		if ( false === $this->thrown['DeprecatedSniff'] ) {
+			$this->thrown['DeprecatedSniff'] = $this->phpcsFile->addWarning(
+				'The "WordPress.VIP.OrderByRand" sniff has been deprecated. Please update your custom ruleset.',
+				0,
+				'DeprecatedSniff'
+			);
+		}
+
+		if ( ! empty( $this->exclude )
+			&& false === $this->thrown['FoundPropertyForDeprecatedSniff']
+		) {
+			$this->thrown['FoundPropertyForDeprecatedSniff'] = $this->phpcsFile->addWarning(
+				'The "WordPress.VIP.OrderByRand" sniff has been deprecated. Please update your custom ruleset.',
+				0,
+				'FoundPropertyForDeprecatedSniff'
+			);
+		}
+
+		return parent::process_token( $stackPtr );
+	}
+
 	/**
 	 * Callback to process each confirmed key, to check value
 	 * This must be extended to add the logic to check assignment value

diff --git a/WordPress/Sniffs/VIP/RestrictedFunctionsSniff.php b/WordPress/Sniffs/VIP/RestrictedFunctionsSniff.php
@@ -29,9 +29,25 @@
  *                 WordPress_Sniffs_WP_AlternativeFunctionsSniff.
  *                 The check for `eval()` now defers to the upstream Squiz.PHP.Eval sniff.
  * @since   0.13.0 Class name changed: this class is now namespaced.
+ *
+ * @deprecated 1.0.0  This sniff has been deprecated.
+ *                    This file remains for now to prevent BC breaks.
  */
 class RestrictedFunctionsSniff extends AbstractFunctionRestrictionsSniff {
 
+	/**
+	 * Keep track of whether the warnings have been thrown to prevent
+	 * the messages being thrown for every token triggering the sniff.
+	 *
+	 * @since 1.0.0
+	 *
+	 * @var array
+	 */
+	private $thrown = array(
+		'DeprecatedSniff'                 => false,
+		'FoundPropertyForDeprecatedSniff' => false,
+	);
+
 	/**
 	 * Groups of functions to restrict.
 	 *
@@ -225,4 +241,35 @@ public function getGroups() {
 		);
 	}
 
+	/**
+	 * Process the token and handle the deprecation notices.
+	 *
+	 * @since 1.0.0 Added to allow for throwing the deprecation notices.
+	 *
+	 * @param int $stackPtr The position of the current token in the stack.
+	 *
+	 * @return void|int
+	 */
+	public function process_token( $stackPtr ) {
+		if ( false === $this->thrown['DeprecatedSniff'] ) {
+			$this->thrown['DeprecatedSniff'] = $this->phpcsFile->addWarning(
+				'The "WordPress.VIP.RestrictedFunctions" sniff has been deprecated. Please update your custom ruleset.',
+				0,
+				'DeprecatedSniff'
+			);
+		}
+
+		if ( ! empty( $this->exclude )
+			&& false === $this->thrown['FoundPropertyForDeprecatedSniff']
+		) {
+			$this->thrown['FoundPropertyForDeprecatedSniff'] = $this->phpcsFile->addWarning(
+				'The "WordPress.VIP.RestrictedFunctions" sniff has been deprecated. Please update your custom ruleset.',
+				0,
+				'FoundPropertyForDeprecatedSniff'
+			);
+		}
+
+		return parent::process_token( $stackPtr );
+	}
+
 }