SlevomatCodingStandard.Functions.UnusedParameter: New option "allowedParameterPatterns" to suppress check for specific parameter names

Author: claytonrcarter

SlevomatCodingStandard/Sniffs/Functions/UnusedParameterSniff.php

@@ -2,16 +2,20 @@
 
 namespace SlevomatCodingStandard\Sniffs\Functions;
 
+use Exception;
 use PHP_CodeSniffer\Files\File;
 use PHP_CodeSniffer\Sniffs\Sniff;
 use PHP_CodeSniffer\Util\Tokens;
 use SlevomatCodingStandard\Helpers\FunctionHelper;
+use SlevomatCodingStandard\Helpers\SniffSettingsHelper;
 use SlevomatCodingStandard\Helpers\SuppressHelper;
 use SlevomatCodingStandard\Helpers\TokenHelper;
 use SlevomatCodingStandard\Helpers\VariableHelper;
 use function array_merge;
 use function in_array;
+use function preg_match;
 use function sprintf;
+use function substr;
 use const T_COMMA;
 use const T_VARIABLE;
 
@@ -23,6 +27,9 @@ class UnusedParameterSniff implements Sniff
 
 	private const NAME = 'SlevomatCodingStandard.Functions.UnusedParameter';
 
+	/** @var list<string> */
+	public array $allowedParameterPatterns = [];
+
 	/**
 	 * @return array<int, (int|string)>
 	 */
@@ -70,7 +77,10 @@ public function process(File $phpcsFile, $functionPointer): void
 				continue;
 			}
 
-			if (VariableHelper::isUsedInScope($phpcsFile, $functionPointer, $parameterPointer)) {
+			if (
+				$this->variableIsSuppressedViaName($tokens[$parameterPointer]['content']) ||
+				VariableHelper::isUsedInScope($phpcsFile, $functionPointer, $parameterPointer)
+			) {
 				$currentPointer = $parameterPointer + 1;
 				continue;
 			}
@@ -104,4 +114,19 @@ private function getSniffName(string $sniffName): string
 		return sprintf('%s.%s', self::NAME, $sniffName);
 	}
 
+	private function variableIsSuppressedViaName(string $variableName): bool
+	{
+		foreach (SniffSettingsHelper::normalizeArray($this->allowedParameterPatterns) as $allowedParamPattern) {
+			if (!SniffSettingsHelper::isValidRegularExpression($allowedParamPattern)) {
+				throw new Exception(sprintf('%s is not valid PCRE pattern.', $allowedParamPattern));
+			}
+
+			if (preg_match($allowedParamPattern, substr($variableName, 1)) === 1) {
+				return true;
+			}
+		}
+
+		return false;
+	}
+
 }

doc/functions.md

@@ -131,6 +131,10 @@ Looks for unused inherited variables passed to closure via `use`.
 
 Looks for unused parameters.
 
+This sniff provides the following setting:
+
+* `allowedParameterPatterns`: allows to configure which parameters are always allowed, even if unused. This is an array of regular expressions (PCRE) with delimiters, but without the leading `$` from variable names. (For example, use `[/^_/]` to allow parameters that start with an underscore, like `$_unused`.)
+
 #### SlevomatCodingStandard.Functions.UselessParameterDefaultValue 🚧
 
 Looks for useless parameter default value.

tests/Sniffs/Functions/UnusedParameterSniffTest.php

@@ -3,6 +3,7 @@
 namespace SlevomatCodingStandard\Sniffs\Functions;
 
 use SlevomatCodingStandard\Sniffs\TestCase;
+use Throwable;
 
 class UnusedParameterSniffTest extends TestCase
 {
@@ -40,4 +41,43 @@ public function testErrors(): void
 		);
 	}
 
+	public function testAllowedParameterSetting(): void
+	{
+		$report = self::checkFile(__DIR__ . '/data/unusedParameterErrors.php', [
+			'allowedParameterPatterns' => ['~^a$~'],
+		], [UnusedParameterSniff::CODE_UNUSED_PARAMETER]);
+
+		self::assertSame(2, $report->getErrorCount());
+
+		self::assertSniffError($report, 3, UnusedParameterSniff::CODE_UNUSED_PARAMETER, 'Unused parameter $b.');
+		self::assertSniffError($report, 66, UnusedParameterSniff::CODE_UNUSED_PARAMETER, 'Unused parameter $b.');
+
+		$report = self::checkFile(__DIR__ . '/data/unusedParameterErrors.php', [
+			'allowedParameterPatterns' => ['~^b$~'],
+		], [UnusedParameterSniff::CODE_UNUSED_PARAMETER]);
+
+		self::assertSame(10, $report->getErrorCount());
+
+		self::assertSniffError($report, 3, UnusedParameterSniff::CODE_UNUSED_PARAMETER, 'Unused parameter $a.');
+		self::assertSniffError($report, 7, UnusedParameterSniff::CODE_UNUSED_PARAMETER, 'Unused parameter $a.');
+		self::assertSniffError($report, 14, UnusedParameterSniff::CODE_UNUSED_PARAMETER, 'Unused parameter $a.');
+		self::assertSniffError($report, 19, UnusedParameterSniff::CODE_UNUSED_PARAMETER, 'Unused parameter $a.');
+		self::assertSniffError($report, 26, UnusedParameterSniff::CODE_UNUSED_PARAMETER, 'Unused parameter $a.');
+		self::assertSniffError($report, 35, UnusedParameterSniff::CODE_UNUSED_PARAMETER, 'Unused parameter $a.');
+		self::assertSniffError($report, 40, UnusedParameterSniff::CODE_UNUSED_PARAMETER, 'Unused parameter $a.');
+		self::assertSniffError($report, 47, UnusedParameterSniff::CODE_UNUSED_PARAMETER, 'Unused parameter $a.');
+		self::assertSniffError($report, 51, UnusedParameterSniff::CODE_UNUSED_PARAMETER, 'Unused parameter $a.');
+		self::assertSniffError($report, 53, UnusedParameterSniff::CODE_UNUSED_PARAMETER, 'Unused parameter $a.');
+	}
+
+	public function testThrowExceptionForInvalidPattern(): void
+	{
+		$this->expectException(Throwable::class);
+
+		self::checkFile(
+			__DIR__ . '/data/unusedParameterErrors.php',
+			['allowedParameterPatterns' => ['invalidPattern']],
+		);
+	}
+
 }