Merge branch 'trunk' into 783-checks-for-plugin-header-fields

.github/workflows/behat-test.yml

@@ -155,7 +155,7 @@ jobs:
 
       - name: Upload code coverage report
         if: ${{ matrix.coverage }}
-        uses: codecov/codecov-action@v4.6.0
+        uses: codecov/codecov-action@v5.0.7
         with:
           files: ${{ steps.coverage_files.outputs.files }}
           flags: feature

.github/workflows/php-lint.yml

@@ -61,3 +61,32 @@ jobs:
 
       - name: PHPMD
         run: composer phpmd
+
+  php-lint-sniffs:
+    name: PHP (Sniffs)
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.0'
+
+      - name: Validate Composer configuration
+        working-directory: "phpcs-sniffs"
+        run: composer validate
+
+      - name: Install PHP dependencies
+        uses: ramsey/composer-install@57532f8be5bda426838819c5ee9afb8af389d51a
+        with:
+          composer-options: '--prefer-dist'
+          working-directory: "phpcs-sniffs"
+
+      - name: PHP Lint
+        working-directory: "phpcs-sniffs"
+        run: composer lint
+
+      - name: PHP Lint PHPCS
+        working-directory: "phpcs-sniffs"
+        run: composer check-cs

.github/workflows/php-test.yml

@@ -100,7 +100,7 @@ jobs:
 
       - name: Upload code coverage report
         if: ${{ matrix.coverage }}
-        uses: codecov/codecov-action@68708a9f7a6b6b5fe33673f782f93725c5eff3c6
+        uses: codecov/codecov-action@015f24e6818733317a2da2edd6290ab26238649a
         with:
           file: build/logs/*.xml
           flags: unit
@@ -146,7 +146,7 @@ jobs:
 
       - name: Upload code coverage report
         if: ${{ matrix.coverage }}
-        uses: codecov/codecov-action@68708a9f7a6b6b5fe33673f782f93725c5eff3c6
+        uses: codecov/codecov-action@015f24e6818733317a2da2edd6290ab26238649a
         with:
           file: build/logs/*.xml
           flags: phpcs-sniffs

includes/Checker/Checks/Plugin_Repo/Plugin_Header_Fields_Check.php

@@ -308,7 +308,7 @@ public function run( Check_Result $result ) {
 
 		if ( ! empty( $plugin_header['RequiresPlugins'] ) ) {
 			if ( ! preg_match( '/^[a-z0-9-]+(?:,\s*[a-z0-9-]+)*$/', $plugin_header['RequiresPlugins'] ) ) {
-				$this->add_result_warning_for_file(
+				$this->add_result_error_for_file(
 					$result,
 					sprintf(
 						/* translators: %s: plugin header field */
@@ -320,7 +320,7 @@ public function run( Check_Result $result ) {
 					0,
 					0,
 					'',
-					6
+					7
 				);
 			}
 		}

includes/Checker/Checks/Plugin_Repo/Plugin_Readme_Check.php

@@ -104,6 +104,9 @@ protected function check_files( Check_Result $result, array $files ) {
 		// Check the readme file for warnings.
 		$this->check_for_warnings( $result, $readme_file, $parser );
 
+		// Check the readme file for donate link.
+		$this->check_for_donate_link( $result, $readme_file, $parser );
+
 		// Check the readme file for contributors.
 		$this->check_for_contributors( $result, $readme_file );
 	}
@@ -601,6 +604,41 @@ private function check_for_warnings( Check_Result $result, string $readme_file,
 		}
 	}
 
+	/**
+	 * Checks the readme file for donate link.
+	 *
+	 * @since 1.3.0
+	 *
+	 * @param Check_Result $result      The Check Result to amend.
+	 * @param string       $readme_file Readme file.
+	 * @param Parser       $parser      The Parser object.
+	 */
+	private function check_for_donate_link( Check_Result $result, string $readme_file, Parser $parser ) {
+		$donate_link = $parser->donate_link;
+
+		// Bail if empty donate link.
+		if ( empty( $donate_link ) ) {
+			return;
+		}
+
+		if ( ! ( filter_var( $donate_link, FILTER_VALIDATE_URL ) === $donate_link && str_starts_with( $donate_link, 'http' ) ) ) {
+			$this->add_result_warning_for_file(
+				$result,
+				sprintf(
+					/* translators: %s: plugin header field */
+					__( 'The "%s" header in the readme file must be a valid URL.', 'plugin-check' ),
+					'Donate link'
+				),
+				'readme_invalid_donate_link',
+				$readme_file,
+				0,
+				0,
+				'https://developer.wordpress.org/plugins/wordpress-org/how-your-readme-txt-works/#readme-header-information',
+				6
+			);
+		}
+	}
+
 	/**
 	 * Checks the readme file for contributors.
 	 *

includes/Checker/Checks/Security/Late_Escaping_Check.php

@@ -78,4 +78,41 @@ public function get_description(): string {
 	public function get_documentation_url(): string {
 		return __( 'https://developer.wordpress.org/apis/security/escaping/', 'plugin-check' );
 	}
+
+	/**
+	 * Amends the given result with a message for the specified file, including error information.
+	 *
+	 * @since 1.3.0
+	 *
+	 * @param Check_Result $result   The check result to amend, including the plugin context to check.
+	 * @param bool         $error    Whether it is an error or notice.
+	 * @param string       $message  Error message.
+	 * @param string       $code     Error code.
+	 * @param string       $file     Absolute path to the file where the issue was found.
+	 * @param int          $line     The line on which the message occurred. Default is 0 (unknown line).
+	 * @param int          $column   The column on which the message occurred. Default is 0 (unknown column).
+	 * @param string       $docs     URL for further information about the message.
+	 * @param int          $severity Severity level. Default is 5.
+	 */
+	protected function add_result_message_for_file( Check_Result $result, $error, $message, $code, $file, $line = 0, $column = 0, string $docs = '', $severity = 5 ) {
+		switch ( $code ) {
+			case 'WordPress.Security.EscapeOutput.OutputNotEscaped':
+				$docs = __( 'https://developer.wordpress.org/apis/security/escaping/#escaping-functions', 'plugin-check' );
+				break;
+
+			case 'WordPress.Security.EscapeOutput.UnsafePrintingFunction':
+				$docs = __( 'https://developer.wordpress.org/apis/security/escaping/#escaping-with-localization', 'plugin-check' );
+				break;
+
+			case 'WordPress.Security.EscapeOutput.UnsafeSearchQuery':
+				$docs = __( 'https://developer.wordpress.org/reference/functions/get_search_query/', 'plugin-check' );
+				break;
+
+			default:
+				$docs = __( 'https://developer.wordpress.org/apis/security/escaping/', 'plugin-check' );
+				break;
+		}
+
+		parent::add_result_message_for_file( $result, $error, $message, $code, $file, $line, $column, $docs, $severity );
+	}
 }

package.json

@@ -10,7 +10,7 @@
     "npm": ">=10.2.3"
   },
   "devDependencies": {
-    "@wordpress/env": "^10.11.0",
+    "@wordpress/env": "^10.12.0",
     "@wordpress/scripts": "^30.5.1",
     "gherkin-lint": "^4.2.4",
     "patch-package": "^8.0.0"

phpcs-rulesets/plugin-review.xml

@@ -56,6 +56,11 @@
 		<severity>7</severity>
 	</rule>
 
+	<!-- Prohibit the use of HEREDOC or NOWDOC. -->
+	<rule ref="Squiz.PHP.Heredoc">
+		<severity>7</severity>
+	</rule>
+
 	<!-- Prohibit the use of the `goto` PHP language construct. -->
 	<rule ref="Generic.PHP.DiscourageGoto.Found">
 		<type>error</type>
@@ -141,7 +146,7 @@
 		<severity>7</severity>
 	</rule>
 
-    <!-- Check for discouraged WordPress functions. -->
+	<!-- Check for discouraged WordPress functions. -->
 	<rule ref="WordPress.WP.DiscouragedFunctions">
 		<severity>6</severity>
 	</rule>
@@ -151,4 +156,9 @@
 		<severity>7</severity>
 	</rule>
 
+	<!-- Check for missing required function parameters. -->
+	<rule ref="PluginCheck.CodeAnalysis.RequiredFunctionParameters">
+		<severity>7</severity>
+	</rule>
+
 </ruleset>

phpcs-sniffs/PluginCheck/Sniffs/CodeAnalysis/LocalhostSniff.php

@@ -55,7 +55,7 @@ public function process_token( $stackPtr ) {
 					'Do not use Localhost/127.0.0.1 in your code. Found: %s',
 					$this->find_token_in_multiline_string( $stackPtr, $content, $match[1] ),
 					'Found',
-					[ $match[0] ]
+					array( $match[0] )
 				);
 			}
 		}

phpcs-sniffs/PluginCheck/Sniffs/CodeAnalysis/RequiredFunctionParametersSniff.php

@@ -0,0 +1,84 @@
+<?php
+/**
+ * RequiredFunctionParametersSniff
+ *
+ * Based on code from {@link https://github.com/WordPress/WordPress-Coding-Standards}
+ * which is licensed under {@link https://opensource.org/licenses/MIT}.
+ *
+ * @package PluginCheck
+ */
+
+namespace PluginCheckCS\PluginCheck\Sniffs\CodeAnalysis;
+
+use PHPCSUtils\Utils\MessageHelper;
+use PHPCSUtils\Utils\PassedParameters;
+use WordPressCS\WordPress\AbstractFunctionParameterSniff;
+
+/**
+ * Detect missing required function parameters.
+ *
+ * @link https://developer.wordpress.org/plugins/wordpress-org/detailed-plugin-guidelines/
+ *
+ * @since 1.3.0
+ */
+final class RequiredFunctionParametersSniff extends AbstractFunctionParameterSniff {
+
+	/**
+	 * Array of functions to check.
+	 *
+	 * @since 1.3.0
+	 *
+	 * @var array<string, array<string, int|string>> Function name as key, array with target parameter and name as value.
+	 */
+	protected $target_functions = array(
+		'parse_str' => array(
+			'position' => 2,
+			'name'     => 'result',
+		),
+	);
+
+	/**
+	 * Processes this test, when one of its tokens is encountered.
+	 *
+	 * @since 1.3.0
+	 *
+	 * @param int $stackPtr The position of the current token in the stack.
+	 * @return int|void Integer stack pointer to skip forward or void to continue normal file processing.
+	 */
+	public function process_token( $stackPtr ) {
+		if ( isset( $this->target_functions[ strtolower( $this->tokens[ $stackPtr ]['content'] ) ] ) ) {
+			// Disallow excluding function groups for this sniff.
+			$this->exclude = array();
+
+			return parent::process_token( $stackPtr );
+		}
+	}
+
+	/**
+	 * Process the parameters of a matched function call.
+	 *
+	 * @since 1.3.0
+	 *
+	 * @param int    $stackPtr        The position of the current token in the stack.
+	 * @param string $group_name      The name of the group which was matched.
+	 * @param string $matched_content The token content (function name) which was matched in lowercase.
+	 * @param array  $parameters      Array with information about the parameters.
+	 * @return void
+	 */
+	public function process_parameters( $stackPtr, $group_name, $matched_content, $parameters ) {
+		$target_param = $this->target_functions[ $matched_content ];
+
+		$found_param = PassedParameters::getParameterFromStack( $parameters, $target_param['position'], $target_param['name'] );
+
+		if ( false === $found_param ) {
+			$error_code = MessageHelper::stringToErrorCode( $matched_content . '_' . $target_param['name'], true );
+
+			$this->phpcsFile->addError(
+				'The "%s" parameter for function %s() is missing.',
+				$stackPtr,
+				$error_code . 'Missing',
+				array( $target_param['name'], $matched_content )
+			);
+		}
+	}
+}

phpcs-sniffs/PluginCheck/Tests/CodeAnalysis/RequiredFunctionParametersUnitTest.inc

@@ -0,0 +1,11 @@
+<?php
+
+parse_str( $param_one, $param_two ); // Good.
+parse_str( $param_one ); // Bad.
+
+$str = "first=value&arr[]=foo+bar&arr[]=baz";
+parse_str($str, $output); // Good.
+parse_str($str); // Bad.
+
+parse_str("My Value=Something", $output); // Good.
+parse_str("My Value=Something"); // Bad.