From a717536de67457d1f9ff15b9c07bfe5f8c95140e Mon Sep 17 00:00:00 2001
From: Tomas Votruba <tomas.vot@gmail.com>
Date: Thu, 2 Jul 2026 15:16:50 +0200
Subject: [PATCH 1/3] Skip @param comment text mistaken as switched type

---
 .../src/Fixer/Commenting/SwitchedTypeAndNameFixer.php     | 2 +-
 .../SwitchedTypeAndNameFixer/Fixture/skip_comment.php.inc | 8 ++++++++
 2 files changed, 9 insertions(+), 1 deletion(-)
 create mode 100644 packages/coding-standard/tests/Fixer/Commenting/SwitchedTypeAndNameFixer/Fixture/skip_comment.php.inc

diff --git a/packages/coding-standard/src/Fixer/Commenting/SwitchedTypeAndNameFixer.php b/packages/coding-standard/src/Fixer/Commenting/SwitchedTypeAndNameFixer.php
index 59bd632ff7..8b4f306bd2 100644
--- a/packages/coding-standard/src/Fixer/Commenting/SwitchedTypeAndNameFixer.php
+++ b/packages/coding-standard/src/Fixer/Commenting/SwitchedTypeAndNameFixer.php
@@ -21,7 +21,7 @@ final class SwitchedTypeAndNameFixer extends AbstractDocBlockFixer
     /**
      * @see https://regex101.com/r/4us32A/1
      */
-    private const string NAME_THEN_TYPE_REGEX = '#@((?:psalm-|phpstan-)?(?:param|var))(\s+)(?<name>\$\w+)(\s+)(?<type>(?:[|\\\\\w\[\]]|<[^<>]*>)+)#';
+    private const string NAME_THEN_TYPE_REGEX = '#@((?:psalm-|phpstan-)?(?:param|var))(\s+)(?<name>\$\w+)(\s+)(?<type>(?:[|\\\\\w\[\]]|<[^<>]*>)+)(?=\s*$)#';
 
     public function getDefinition(): FixerDefinitionInterface
     {
diff --git a/packages/coding-standard/tests/Fixer/Commenting/SwitchedTypeAndNameFixer/Fixture/skip_comment.php.inc b/packages/coding-standard/tests/Fixer/Commenting/SwitchedTypeAndNameFixer/Fixture/skip_comment.php.inc
new file mode 100644
index 0000000000..5dec1bc7be
--- /dev/null
+++ b/packages/coding-standard/tests/Fixer/Commenting/SwitchedTypeAndNameFixer/Fixture/skip_comment.php.inc
@@ -0,0 +1,8 @@
+<?php
+
+/**
+ * @param        $extra  Can be used by model to determine what to unlock
+ */
+function test($extra): void
+{
+}

From 0a0ae63e565751bef58a314832f3eec0b6afd52d Mon Sep 17 00:00:00 2001
From: Tomas Votruba <tomas.vot@gmail.com>
Date: Thu, 2 Jul 2026 15:28:51 +0200
Subject: [PATCH 2/3] Add fixtures: union/generic/phpstan swaps and
 type-with-comment skip

---
 .../Fixture/skip_type_with_comment.php.inc    |  8 ++++++
 .../Fixture/wrong5.php.inc                    | 27 +++++++++++++++++++
 2 files changed, 35 insertions(+)
 create mode 100644 packages/coding-standard/tests/Fixer/Commenting/SwitchedTypeAndNameFixer/Fixture/skip_type_with_comment.php.inc
 create mode 100644 packages/coding-standard/tests/Fixer/Commenting/SwitchedTypeAndNameFixer/Fixture/wrong5.php.inc

diff --git a/packages/coding-standard/tests/Fixer/Commenting/SwitchedTypeAndNameFixer/Fixture/skip_type_with_comment.php.inc b/packages/coding-standard/tests/Fixer/Commenting/SwitchedTypeAndNameFixer/Fixture/skip_type_with_comment.php.inc
new file mode 100644
index 0000000000..1308e308b6
--- /dev/null
+++ b/packages/coding-standard/tests/Fixer/Commenting/SwitchedTypeAndNameFixer/Fixture/skip_type_with_comment.php.inc
@@ -0,0 +1,8 @@
+<?php
+
+/**
+ * @param $a string the input value
+ */
+function test($a): void
+{
+}
diff --git a/packages/coding-standard/tests/Fixer/Commenting/SwitchedTypeAndNameFixer/Fixture/wrong5.php.inc b/packages/coding-standard/tests/Fixer/Commenting/SwitchedTypeAndNameFixer/Fixture/wrong5.php.inc
new file mode 100644
index 0000000000..27c59d6eb6
--- /dev/null
+++ b/packages/coding-standard/tests/Fixer/Commenting/SwitchedTypeAndNameFixer/Fixture/wrong5.php.inc
@@ -0,0 +1,27 @@
+<?php
+
+/**
+ * @param $x array<int, string>|null
+ * @phpstan-param $y int
+ * @psalm-var $c list<int>
+ * @var $z Foo\Bar
+ */
+function test($x, $y): void
+{
+}
+
+?>
+-----
+<?php
+
+/**
+ * @param array<int, string>|null $x
+ * @phpstan-param int $y
+ * @psalm-var list<int> $c
+ * @var Foo\Bar $z
+ */
+function test($x, $y): void
+{
+}
+
+?>

From 8698809347a9156525086b7058c8140aadab8e59 Mon Sep 17 00:00:00 2001
From: Tomas Votruba <tomas.vot@gmail.com>
Date: Thu, 2 Jul 2026 15:33:51 +0200
Subject: [PATCH 3/3] Swap type+comment when first token is a real type, keep
 trailing comment

---
 .../Commenting/SwitchedTypeAndNameFixer.php   | 27 ++++++++++++++++---
 .../Fixture/skip_type_with_comment.php.inc    |  8 ------
 .../Fixture/skip_word_before_comment.php.inc  |  8 ++++++
 .../Fixture/wrong6.php.inc                    | 23 ++++++++++++++++
 4 files changed, 54 insertions(+), 12 deletions(-)
 delete mode 100644 packages/coding-standard/tests/Fixer/Commenting/SwitchedTypeAndNameFixer/Fixture/skip_type_with_comment.php.inc
 create mode 100644 packages/coding-standard/tests/Fixer/Commenting/SwitchedTypeAndNameFixer/Fixture/skip_word_before_comment.php.inc
 create mode 100644 packages/coding-standard/tests/Fixer/Commenting/SwitchedTypeAndNameFixer/Fixture/wrong6.php.inc

diff --git a/packages/coding-standard/src/Fixer/Commenting/SwitchedTypeAndNameFixer.php b/packages/coding-standard/src/Fixer/Commenting/SwitchedTypeAndNameFixer.php
index 8b4f306bd2..dc6eeeda7b 100644
--- a/packages/coding-standard/src/Fixer/Commenting/SwitchedTypeAndNameFixer.php
+++ b/packages/coding-standard/src/Fixer/Commenting/SwitchedTypeAndNameFixer.php
@@ -21,7 +21,16 @@ final class SwitchedTypeAndNameFixer extends AbstractDocBlockFixer
     /**
      * @see https://regex101.com/r/4us32A/1
      */
-    private const string NAME_THEN_TYPE_REGEX = '#@((?:psalm-|phpstan-)?(?:param|var))(\s+)(?<name>\$\w+)(\s+)(?<type>(?:[|\\\\\w\[\]]|<[^<>]*>)+)(?=\s*$)#';
+    private const string NAME_THEN_TYPE_REGEX = '#@((?:psalm-|phpstan-)?(?:param|var))(\s+)(?<name>\$\w+)(\s+)(?<type>(?:[|\\\\\w\[\]]|<[^<>]*>)+)(?<rest>\s+\S.*)?$#';
+
+    /**
+     * @var string[]
+     */
+    private const array KNOWN_PRIMITIVE_TYPES = [
+        'string', 'int', 'integer', 'float', 'bool', 'boolean', 'array', 'object', 'callable',
+        'iterable', 'mixed', 'void', 'null', 'false', 'true', 'self', 'static', 'parent',
+        'resource', 'scalar', 'never', 'number', 'double',
+    ];
 
     public function getDefinition(): FixerDefinitionInterface
     {
@@ -51,15 +60,25 @@ protected function processDocContent(string $docContent, Tokens $tokens, int $po
                 continue;
             }
 
-            // skip random words that look like type without autolaoding
-            if (in_array($match['type'], ['The', 'Set'], true)) {
+            // skip plain comment words mistaken for a type, e.g. "@param $a Can be used to..."
+            if (! $this->isKnownType($match['type'])) {
                 continue;
             }
 
-            $newLine = Regex::replace($line->getContent(), self::NAME_THEN_TYPE_REGEX, '@$1$2$5$4$3');
+            $newLine = Regex::replace($line->getContent(), self::NAME_THEN_TYPE_REGEX, '@$1$2$5$4$3$6');
             $line->setContent($newLine);
         }
 
         return $docBlock->getContent();
     }
+
+    private function isKnownType(string $type): bool
+    {
+        // has type syntax: namespace, generics, array brackets or union
+        if (Regex::match($type, '#[\\\\\[\]<>|]#') !== null) {
+            return true;
+        }
+
+        return in_array(strtolower($type), self::KNOWN_PRIMITIVE_TYPES, true);
+    }
 }
diff --git a/packages/coding-standard/tests/Fixer/Commenting/SwitchedTypeAndNameFixer/Fixture/skip_type_with_comment.php.inc b/packages/coding-standard/tests/Fixer/Commenting/SwitchedTypeAndNameFixer/Fixture/skip_type_with_comment.php.inc
deleted file mode 100644
index 1308e308b6..0000000000
--- a/packages/coding-standard/tests/Fixer/Commenting/SwitchedTypeAndNameFixer/Fixture/skip_type_with_comment.php.inc
+++ /dev/null
@@ -1,8 +0,0 @@
-<?php
-
-/**
- * @param $a string the input value
- */
-function test($a): void
-{
-}
diff --git a/packages/coding-standard/tests/Fixer/Commenting/SwitchedTypeAndNameFixer/Fixture/skip_word_before_comment.php.inc b/packages/coding-standard/tests/Fixer/Commenting/SwitchedTypeAndNameFixer/Fixture/skip_word_before_comment.php.inc
new file mode 100644
index 0000000000..9dcaf85774
--- /dev/null
+++ b/packages/coding-standard/tests/Fixer/Commenting/SwitchedTypeAndNameFixer/Fixture/skip_word_before_comment.php.inc
@@ -0,0 +1,8 @@
+<?php
+
+/**
+ * @param $result The result value returned by the callback
+ */
+function test($result): void
+{
+}
diff --git a/packages/coding-standard/tests/Fixer/Commenting/SwitchedTypeAndNameFixer/Fixture/wrong6.php.inc b/packages/coding-standard/tests/Fixer/Commenting/SwitchedTypeAndNameFixer/Fixture/wrong6.php.inc
new file mode 100644
index 0000000000..4ed825ee44
--- /dev/null
+++ b/packages/coding-standard/tests/Fixer/Commenting/SwitchedTypeAndNameFixer/Fixture/wrong6.php.inc
@@ -0,0 +1,23 @@
+<?php
+
+/**
+ * @param $a string the input value
+ * @param $b array<int, string> mapped items
+ */
+function test($a, $b): void
+{
+}
+
+?>
+-----
+<?php
+
+/**
+ * @param string $a the input value
+ * @param array<int, string> $b mapped items
+ */
+function test($a, $b): void
+{
+}
+
+?>