Merge pull request #2386 from WordPress/develop

Release WordPressCS 3.0.1

.github/FUNDING.yml

@@ -0,0 +1 @@
+custom: "https://opencollective.com/thewpcc/contribute/wp-php-63406"

.github/release-checklist.md

@@ -62,9 +62,10 @@ PR for tracking changes for the x.x.x release. Target release date: **DOW MONTH
 - [ ] Tweet, toot, etc about the release.
 - [ ] Post about it in Slack.
 - [ ] Submit for ["Month in WordPress"][month-in-wp].
-
+- [ ] Submit for the ["Monthy Dev Roundup"][dev-roundup].
 
 [phpcs-releases]:      https://github.com/squizlabs/PHP_CodeSniffer/releases
 [phpcsutils-releases]: https://github.com/PHPCSStandards/PHPCSUtils/releases
 [phpcsextra-releases]: https://github.com/PHPCSStandards/PHPCSExtra/releases
 [month-in-wp]:         https://make.wordpress.org/community/month-in-wordpress-submissions/
+[dev-roundup]:         https://github.com/WordPress/developer-blog-content/issues?q=is%3Aissue+label%3A%22Monthly+Roundup%22

.github/workflows/basic-qa.yml

@@ -141,6 +141,12 @@ jobs:
       - name: Test the WordPress ruleset
         run: $(pwd)/vendor/bin/phpcs -ps ./Tests/RulesetCheck/class-ruleset-test.inc --standard=WordPress
 
+      - name: Rename the example ruleset to one which can be used for a ruleset
+        run:  cp phpcs.xml.dist.sample sample.xml
+
+      - name: Test the example ruleset
+        run: $(pwd)/vendor/bin/phpcs -ps ./Tests/RulesetCheck/example-ruleset-test.inc --standard=./sample.xml
+
       # Test for fixer conflicts by running the auto-fixers of the complete WPCS over the test case files.
       # This is not an exhaustive test, but should give an early indication for typical fixer conflicts.
       # If only fixable errors are found, the exit code will be 1, which can be interpreted as success.

CHANGELOG.md

@@ -8,6 +8,23 @@ This projects adheres to [Semantic Versioning](https://semver.org/) and [Keep a
 
 _No documentation available about unreleased changes as of yet._
 
+## [3.0.1] - 2023-09-13
+
+### Added
+
+- In WordPressCS 3.0.0, the functionality of the `WordPress.Security.EscapeOutput` sniff was updated to report unescaped message parameters passed to exceptions created in `throw` statements. This specific violation now has a separate error code: `ExceptionNotEscaped`. This will allow users to ignore or exclude that specific error code. Props [@anomiex].
+    The error code(s) for other escaping issues flagged by the sniff remain unchanged.
+
+### Changed
+
+- Updated the CI workflow to test the example ruleset for issues.
+- Funding files and updates in the Readme about funding the project.
+
+### Fixed
+
+- Fixed a sniff name in the `phpcs.xml.dist.sample` file (case-sensitive sniff name). Props [@dawidurbanski].
+
+
 ## [3.0.0] - 2023-08-21
 
 ### Important information about this release:
@@ -1556,6 +1573,7 @@ Initial tagged release.
 [Composer PHPCS plugin]: https://github.com/PHPCSStandards/composer-installer
 
 [Unreleased]: https://github.com/WordPress/WordPress-Coding-Standards/compare/main...HEAD
+[3.0.1]: https://github.com/WordPress/WordPress-Coding-Standards/compare/3.0.0...3.0.1
 [3.0.0]: https://github.com/WordPress/WordPress-Coding-Standards/compare/2.3.0...3.0.0
 [2.3.0]: https://github.com/WordPress/WordPress-Coding-Standards/compare/2.2.1...2.3.0
 [2.2.1]: https://github.com/WordPress/WordPress-Coding-Standards/compare/2.2.0...2.2.1
@@ -1585,8 +1603,10 @@ Initial tagged release.
 [0.3.0]: https://github.com/WordPress/WordPress-Coding-Standards/compare/2013-10-06...0.3.0
 [2013-10-06]: https://github.com/WordPress/WordPress-Coding-Standards/compare/2013-06-11...2013-10-06
 
+[@anomiex]:       https://github.com/anomiex
 [@ckanitz]:       https://github.com/ckanitz
 [@craigfrancis]:  https://github.com/craigfrancis
+[@dawidurbanski]: https://github.com/dawidurbanski
 [@desrosj]:       https://github.com/desrosj
 [@grappler]:      https://github.com/grappler
 [@Ipstenu]:       https://github.com/Ipstenu

README.md

@@ -39,13 +39,17 @@
 * [Fixing errors or ignoring them](#fixing-errors-or-ignoring-them)
     + [Tools shipped with WordPressCS](#tools-shipped-with-wordpresscs)
 * [Contributing](#contributing)
+* [Funding](#funding)
 * [License](#license)
 
+---
 
 ## Introduction
 
 This project is a collection of [PHP_CodeSniffer](https://github.com/squizlabs/PHP_CodeSniffer) rules (sniffs) to validate code developed for WordPress. It ensures code quality and adherence to coding conventions, especially the official [WordPress Coding Standards](https://make.wordpress.org/core/handbook/best-practices/coding-standards/).
 
+This project needs funding. [Find out how you can help](#funding).
+
 ## Minimum Requirements
 
 The WordPress Coding Standards package requires:
@@ -62,7 +66,7 @@ For the best results, it is recommended to also ensure the following additional
 
 ## Installation
 
-As of WordPressCS 3.0.0, installation via Composer using the below instructions is the only supported type of installation.
+As of [WordPressCS 3.0.0](https://make.wordpress.org/core/2023/08/21/wordpresscs-3-0-0-is-now-available/), installation via Composer using the below instructions is the only supported type of installation.
 
 [Composer](https://getcomposer.org/) will automatically install the project dependencies and register the rulesets from WordPressCS and other external standards with PHP_CodeSniffer using the [Composer PHPCS plugin](https://github.com/PHPCSStandards/composer-installer).
 
@@ -248,6 +252,10 @@ At this moment, WordPressCS offer the following tools:
 
 See [CONTRIBUTING](.github/CONTRIBUTING.md), including information about [unit testing](.github/CONTRIBUTING.md#unit-testing) the standard.
 
+## Funding
+
+If you want to sponsor the work on WordPressCS, you can do so by donating to the [WP PHP Open Collective](https://opencollective.com//thewpcc/contribute/wp-php-63406).
+
 ## License
 
 See [LICENSE](LICENSE) (MIT).

Tests/RulesetCheck/example-ruleset-test.inc

@@ -0,0 +1,8 @@
+<?php
+/**
+ * File which should not yield any errors when using the example ruleset.
+ *
+ * @package My\Prefix\Package
+ */
+
+$my_prefix_var = 'hello';

WordPress/Sniffs/Security/EscapeOutputSniff.php

@@ -263,7 +263,7 @@ public function process_token( $stackPtr ) {
 
 				// Examine each parameter individually.
 				foreach ( $params as $param ) {
-					$this->check_code_is_escaped( $param['start'], ( $param['end'] + 1 ) );
+					$this->check_code_is_escaped( $param['start'], ( $param['end'] + 1 ), 'ExceptionNotEscaped' );
 				}
 
 				return $end;
@@ -446,12 +446,13 @@ public function process_matched_token( $stackPtr, $group_name, $matched_content
 	 *
 	 * @since 3.0.0 Split off from the process_token() method.
 	 *
-	 * @param int $start The position to start checking from.
-	 * @param int $end   The position to stop the check at.
+	 * @param int    $start The position to start checking from.
+	 * @param int    $end   The position to stop the check at.
+	 * @param string $code  Code to use for the PHPCS error.
 	 *
 	 * @return int Integer stack pointer to skip forward.
 	 */
-	protected function check_code_is_escaped( $start, $end ) {
+	protected function check_code_is_escaped( $start, $end, $code = 'OutputNotEscaped' ) {
 		/*
 		 * Check for a ternary operator.
 		 * We only need to do this here if this statement is lacking parenthesis.
@@ -532,7 +533,7 @@ protected function check_code_is_escaped( $start, $end ) {
 
 			// Handle PHP 8.0+ match expressions.
 			if ( \T_MATCH === $this->tokens[ $i ]['code'] ) {
-				$match_valid = $this->walk_match_expression( $i );
+				$match_valid = $this->walk_match_expression( $i, $code );
 				if ( false === $match_valid ) {
 					// Live coding or parse error. Shouldn't be possible as PHP[CS] will tokenize the keyword as `T_STRING` in that case.
 					break; // @codeCoverageIgnore
@@ -553,7 +554,7 @@ protected function check_code_is_escaped( $start, $end ) {
 				$array_items = PassedParameters::getParameters( $this->phpcsFile, $i, 0, true );
 				if ( ! empty( $array_items ) ) {
 					foreach ( $array_items as $array_item ) {
-						$this->check_code_is_escaped( $array_item['start'], ( $array_item['end'] + 1 ) );
+						$this->check_code_is_escaped( $array_item['start'], ( $array_item['end'] + 1 ), $code );
 					}
 				}
 
@@ -699,7 +700,7 @@ protected function check_code_is_escaped( $start, $end ) {
 						$formatting_params = PassedParameters::getParameters( $this->phpcsFile, $i );
 						if ( ! empty( $formatting_params ) ) {
 							foreach ( $formatting_params as $format_param ) {
-								$this->check_code_is_escaped( $format_param['start'], ( $format_param['end'] + 1 ) );
+								$this->check_code_is_escaped( $format_param['start'], ( $format_param['end'] + 1 ), $code );
 							}
 						}
 
@@ -754,7 +755,7 @@ protected function check_code_is_escaped( $start, $end ) {
 			$this->phpcsFile->addError(
 				"All output should be run through an escaping function (see the Security sections in the WordPress Developer Handbooks), found '%s'.",
 				$ptr,
-				'OutputNotEscaped',
+				$code,
 				array( $content )
 			);
 		}
@@ -825,11 +826,12 @@ private function find_long_ternary( $start, $end ) {
 	 *
 	 * @since 3.0.0
 	 *
-	 * @param int $stackPtr Pointer to a T_MATCH token.
+	 * @param int    $stackPtr Pointer to a T_MATCH token.
+	 * @param string $code     Code to use for the PHPCS error.
 	 *
 	 * @return int|false Stack pointer to skip to or FALSE if the match expression contained a parse error.
 	 */
-	private function walk_match_expression( $stackPtr ) {
+	private function walk_match_expression( $stackPtr, $code ) {
 		if ( ! isset( $this->tokens[ $stackPtr ]['scope_opener'], $this->tokens[ $stackPtr ]['scope_closer'] ) ) {
 			// Parse error/live coding. Shouldn't be possible as PHP[CS] will tokenize the keyword as `T_STRING` in that case.
 			return false; // @codeCoverageIgnore
@@ -889,7 +891,7 @@ private function walk_match_expression( $stackPtr ) {
 			}
 
 			// Now check that the value returned by this match "leaf" is correctly escaped.
-			$this->check_code_is_escaped( $item_start, $item_end );
+			$this->check_code_is_escaped( $item_start, $item_end, $code );
 
 			// Independently of whether or not the check was succesfull or ran into (parse error) problems,
 			// always skip to the identified end of the item.

phpcs.xml.dist.sample

@@ -146,7 +146,7 @@
 	<rule ref="WordPress.WP.GlobalVariablesOverride">
 		<exclude-pattern>/path/to/Tests/*Test\.php</exclude-pattern>
 	</rule>
-	<rule ref="WordPress.Files.Filename">
+	<rule ref="WordPress.Files.FileName">
 		<exclude-pattern>/path/to/Tests/*Test\.php</exclude-pattern>
 	</rule>