From 33aefae8c9c1b4ff141b2cbc4183a0395505359f Mon Sep 17 00:00:00 2001
From: Tomas Votruba <tomas.vot@gmail.com>
Date: Tue, 9 Jun 2026 18:44:06 +0100
Subject: [PATCH] extend dead param worker

---
 .../ParamReturnAndVarTagMalformsFixer.php     | 19 +++++++++
 .../MalformWorker/DeadParamMalformWorker.php  | 41 +++++++++++++++++++
 .../Fixture/dead_param.php.inc                | 22 ++++++++++
 .../Fixture/dead_param_only.php.inc           | 18 ++++++++
 .../Fixture/wrong4.php.inc                    |  1 -
 .../Fixture/wrong9.php.inc                    |  1 -
 6 files changed, 100 insertions(+), 2 deletions(-)
 create mode 100644 src/TokenRunner/DocBlock/MalformWorker/DeadParamMalformWorker.php
 create mode 100644 tests/Fixer/Commenting/ParamReturnAndVarTagMalformsFixer/Fixture/dead_param.php.inc
 create mode 100644 tests/Fixer/Commenting/ParamReturnAndVarTagMalformsFixer/Fixture/dead_param_only.php.inc

diff --git a/src/Fixer/Commenting/ParamReturnAndVarTagMalformsFixer.php b/src/Fixer/Commenting/ParamReturnAndVarTagMalformsFixer.php
index 80ec64980..b8ce0148d 100644
--- a/src/Fixer/Commenting/ParamReturnAndVarTagMalformsFixer.php
+++ b/src/Fixer/Commenting/ParamReturnAndVarTagMalformsFixer.php
@@ -13,6 +13,7 @@
 use SplFileInfo;
 use Symplify\CodingStandard\Fixer\AbstractSymplifyFixer;
 use Symplify\CodingStandard\TokenRunner\Contract\DocBlock\MalformWorkerInterface;
+use Symplify\CodingStandard\TokenRunner\DocBlock\MalformWorker\DeadParamMalformWorker;
 use Symplify\CodingStandard\TokenRunner\DocBlock\MalformWorker\InlineVariableDocBlockMalformWorker;
 use Symplify\CodingStandard\TokenRunner\DocBlock\MalformWorker\InlineVarMalformWorker;
 use Symplify\CodingStandard\TokenRunner\DocBlock\MalformWorker\MissingParamNameMalformWorker;
@@ -51,6 +52,7 @@ public function __construct(
         SuperfluousReturnNameMalformWorker $superfluousReturnNameMalformWorker,
         SuperfluousVarNameMalformWorker $superfluousVarNameMalformWorker,
         SwitchedTypeAndNameMalformWorker $switchedTypeAndNameMalformWorker,
+        DeadParamMalformWorker $deadParamMalformWorker,
         private readonly TokenReverser $tokenReverser
     ) {
         $this->malformWorkers = [
@@ -63,6 +65,7 @@ public function __construct(
             $superfluousReturnNameMalformWorker,
             $superfluousVarNameMalformWorker,
             $switchedTypeAndNameMalformWorker,
+            $deadParamMalformWorker,
         ];
     }
 
@@ -123,6 +126,17 @@ public function fix(SplFileInfo $fileInfo, Tokens $tokens): void
                 continue;
             }
 
+            // doc block became empty after removing dead lines → remove it completely,
+            // including the whitespace that followed it, to avoid leaving a blank line
+            if ($this->isEmptyDocBlock($docContent)) {
+                $tokens->clearAt($index);
+                if (isset($tokens[$index + 1]) && $tokens[$index + 1]->isWhitespace()) {
+                    $tokens->clearAt($index + 1);
+                }
+
+                continue;
+            }
+
             $tokens[$index] = new Token([T_DOC_COMMENT, $docContent]);
         }
     }
@@ -137,4 +151,9 @@ public function getPriority(): int
     {
         return -37;
     }
+
+    private function isEmptyDocBlock(string $docContent): bool
+    {
+        return Strings::replace($docContent, '#/\*\*|\*/|\*|\s#', '') === '';
+    }
 }
diff --git a/src/TokenRunner/DocBlock/MalformWorker/DeadParamMalformWorker.php b/src/TokenRunner/DocBlock/MalformWorker/DeadParamMalformWorker.php
new file mode 100644
index 000000000..57c65286e
--- /dev/null
+++ b/src/TokenRunner/DocBlock/MalformWorker/DeadParamMalformWorker.php
@@ -0,0 +1,41 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Symplify\CodingStandard\TokenRunner\DocBlock\MalformWorker;
+
+use Nette\Utils\Strings;
+use PhpCsFixer\DocBlock\DocBlock;
+use PhpCsFixer\Tokenizer\Token;
+use PhpCsFixer\Tokenizer\Tokens;
+use Symplify\CodingStandard\TokenRunner\Contract\DocBlock\MalformWorkerInterface;
+
+/**
+ * Removes dead param annotation lines that only contain a variable name and no type,
+ * e.g. "param $value" - such line carries no information and can be removed.
+ */
+final class DeadParamMalformWorker implements MalformWorkerInterface
+{
+    /**
+     * @see https://regex101.com/r/Hk4lFc/1
+     */
+    private const string PARAM_WITHOUT_TYPE_REGEX = '#@(?:psalm-|phpstan-)?param\s+\$\w+\s*$#';
+
+    /**
+     * @param Tokens<Token> $tokens
+     */
+    public function work(string $docContent, Tokens $tokens, int $position): string
+    {
+        $docBlock = new DocBlock($docContent);
+
+        foreach ($docBlock->getLines() as $line) {
+            if (! Strings::match($line->getContent(), self::PARAM_WITHOUT_TYPE_REGEX)) {
+                continue;
+            }
+
+            $line->remove();
+        }
+
+        return $docBlock->getContent();
+    }
+}
diff --git a/tests/Fixer/Commenting/ParamReturnAndVarTagMalformsFixer/Fixture/dead_param.php.inc b/tests/Fixer/Commenting/ParamReturnAndVarTagMalformsFixer/Fixture/dead_param.php.inc
new file mode 100644
index 000000000..ebb6c1e9a
--- /dev/null
+++ b/tests/Fixer/Commenting/ParamReturnAndVarTagMalformsFixer/Fixture/dead_param.php.inc
@@ -0,0 +1,22 @@
+<?php
+
+/**
+ * @param string $name
+ * @param $age
+ */
+function withDeadParam(string $name, $age)
+{
+}
+
+?>
+-----
+<?php
+
+/**
+ * @param string $name
+ */
+function withDeadParam(string $name, $age)
+{
+}
+
+?>
diff --git a/tests/Fixer/Commenting/ParamReturnAndVarTagMalformsFixer/Fixture/dead_param_only.php.inc b/tests/Fixer/Commenting/ParamReturnAndVarTagMalformsFixer/Fixture/dead_param_only.php.inc
new file mode 100644
index 000000000..4233abab6
--- /dev/null
+++ b/tests/Fixer/Commenting/ParamReturnAndVarTagMalformsFixer/Fixture/dead_param_only.php.inc
@@ -0,0 +1,18 @@
+<?php
+
+/**
+ * @param $value
+ */
+function onlyDeadParam($value)
+{
+}
+
+?>
+-----
+<?php
+
+function onlyDeadParam($value)
+{
+}
+
+?>
diff --git a/tests/Fixer/Commenting/ParamReturnAndVarTagMalformsFixer/Fixture/wrong4.php.inc b/tests/Fixer/Commenting/ParamReturnAndVarTagMalformsFixer/Fixture/wrong4.php.inc
index 5687d4d5b..233af839e 100644
--- a/tests/Fixer/Commenting/ParamReturnAndVarTagMalformsFixer/Fixture/wrong4.php.inc
+++ b/tests/Fixer/Commenting/ParamReturnAndVarTagMalformsFixer/Fixture/wrong4.php.inc
@@ -36,7 +36,6 @@ function someFunction($instanceof)
 }
 
 /**
- * @param $value
  *
  * @return The normalized array value
  */
diff --git a/tests/Fixer/Commenting/ParamReturnAndVarTagMalformsFixer/Fixture/wrong9.php.inc b/tests/Fixer/Commenting/ParamReturnAndVarTagMalformsFixer/Fixture/wrong9.php.inc
index b97d1b4f1..a70cc1617 100644
--- a/tests/Fixer/Commenting/ParamReturnAndVarTagMalformsFixer/Fixture/wrong9.php.inc
+++ b/tests/Fixer/Commenting/ParamReturnAndVarTagMalformsFixer/Fixture/wrong9.php.inc
@@ -15,7 +15,6 @@ function someFunction($argument, $argument2, $exceptionMessageFactory, $items)
 <?php
 
 /**
- * @param $argument
  * @param string $argument2
  * @param ExceptionMessageFactoryInterface|null $exceptionMessageFactory
  * @param string[] $items