From 0ae4fc34ede130c6e8a73006216587802c2ee233 Mon Sep 17 00:00:00 2001 From: mscherer Date: Wed, 3 Dec 2025 16:36:21 +0100 Subject: [PATCH] Fix: Preserve parameter order when inserting missing @param annotations When multiple missing parameters need to be inserted before an existing parameter (or at the end of a docblock), they were being inserted in reverse order due to how addContentBefore() works - each call inserts before the same position, resulting in a LIFO order. The fix reverses the pendingInserts array before iterating, so the parameters are inserted in the correct signature order. Example: For a method like: function foo(string $a, bool $b, string $c) With only @param string $c documented, the fix now correctly produces: @param string $a @param bool $b @param string $c Instead of the previous incorrect output: @param bool $b @param string $a @param string $c This was causing cascading issues with other sniffs like DocBlockParamAllowDefaultValue and DocBlockParamTypeMismatch, which would detect type mismatches due to the wrong parameter order. --- PhpCollective/Sniffs/Commenting/DocBlockParamSniff.php | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/PhpCollective/Sniffs/Commenting/DocBlockParamSniff.php b/PhpCollective/Sniffs/Commenting/DocBlockParamSniff.php index fff1677..8706a1e 100644 --- a/PhpCollective/Sniffs/Commenting/DocBlockParamSniff.php +++ b/PhpCollective/Sniffs/Commenting/DocBlockParamSniff.php @@ -345,7 +345,9 @@ protected function canAddMissingParams(File $phpcsFile, int $docBlockStartIndex, } } - foreach ($pendingInserts as $pendingParam) { + // Reverse the array since addContentBefore inserts before the same position + // multiple times, which would reverse the order + foreach (array_reverse($pendingInserts) as $pendingParam) { $paramLine = $indent . '* @param ' . $pendingParam['type'] . ' ' . $pendingParam['variable'] . "\n"; $phpcsFile->fixer->addContentBefore($insertBeforeIndex, $paramLine); } @@ -398,7 +400,9 @@ protected function canAddMissingParams(File $phpcsFile, int $docBlockStartIndex, } if ($insertBeforeIndex !== null) { - foreach ($pendingInserts as $pendingParam) { + // Reverse the array since addContentBefore inserts before the same position + // multiple times, which would reverse the order + foreach (array_reverse($pendingInserts) as $pendingParam) { $paramLine = $indent . '* @param ' . $pendingParam['type'] . ' ' . $pendingParam['variable'] . "\n"; $phpcsFile->fixer->addContentBefore($insertBeforeIndex, $paramLine); }