From cc26683e8e18ebb65d61452e2b6f44b41f053a2c Mon Sep 17 00:00:00 2001
From: Stephen Jason Wang <stephenjasonwang@gmail.com>
Date: Tue, 4 Aug 2026 20:28:01 +0800
Subject: [PATCH] fix: strip redundant builder `@param` tags for optional
 scalar defaults (#1785)

---
 src/Method.php       | 46 ++++++++++++++++++++++++++++++++++++++++++++
 tests/MethodTest.php |  3 ---
 2 files changed, 46 insertions(+), 3 deletions(-)

diff --git a/src/Method.php b/src/Method.php
index 9f18129..2525a6d 100644
--- a/src/Method.php
+++ b/src/Method.php
@@ -76,6 +76,8 @@ class Method
         } catch (\Exception $e) {
         }
 
+        $this->removePhpDocParamTagsForOptionalParameters();
+
         //Get the parameters, including formatted default values
         $this->getParameters($method);
 
@@ -248,6 +250,50 @@ class Method
         }
     }
 
+    /**
+     * Remove @param tags for optional reflection parameters so generated stubs match arity
+     * checks in static analysis (optional params still appear in the PHP signature).
+     */
+    protected function removePhpDocParamTagsForOptionalParameters(): void
+    {
+        if (!$this->method instanceof \ReflectionMethod) {
+            return;
+        }
+
+        $declaring = $this->method->getDeclaringClass()->getName();
+        if (
+            $declaring !== \Illuminate\Database\Query\Builder::class
+            && $declaring !== \Illuminate\Database\Eloquent\Builder::class
+        ) {
+            return;
+        }
+
+        foreach ($this->method->getParameters() as $param) {
+            if (!$param->isOptional() || $param->isVariadic()) {
+                continue;
+            }
+            if (!$param->isDefaultValueAvailable()) {
+                continue;
+            }
+
+            $default = $param->getDefaultValue();
+            // Keep @param for null/array defaults (nullable and list defaults stay documented).
+            // Strip only non-null scalars (e.g. $boolean = 'and', $not = false) so tools that
+            // count @param tags do not report false "missing argument" errors on shortened calls.
+            if ($default === null || is_array($default) || !is_scalar($default)) {
+                continue;
+            }
+
+            $varName = '$' . $param->getName();
+            $paramTags = $this->phpdoc->getTagsByName('param');
+            foreach (array_values($paramTags) as $tag) {
+                if ($tag instanceof ParamTag && $tag->getVariableName() === $varName) {
+                    $this->phpdoc->deleteTag($tag);
+                }
+            }
+        }
+    }
+
     /**
      * Normalize the parameters
      *
diff --git a/tests/MethodTest.php b/tests/MethodTest.php
index 0141eb5..24f43b7 100644
--- a/tests/MethodTest.php
+++ b/tests/MethodTest.php
@@ -101,7 +101,6 @@ DOC;
  * @param (\Closure(static): mixed)|string|array|\Illuminate\Contracts\Database\Query\Expression $column
  * @param mixed $operator
  * @param mixed $value
- * @param string $boolean
  * @return \Illuminate\Database\Eloquent\Builder<static>
  * @static
  */
@@ -130,8 +129,6 @@ DOC;
  * Add a "where null" clause to the query.
  *
  * @param string|array|\Illuminate\Contracts\Database\Query\Expression $columns
- * @param string $boolean
- * @param bool $not
  * @return \Illuminate\Database\Eloquent\Builder<static>
  * @static
  */