Improve phpdoc completion

Author: AJenbo

example.php

@@ -1391,18 +1391,10 @@ public function getBody(): string { return ''; }
 
 class ForeachKeyDemo {
     /**
-     * Object keys: SplObjectStorage<Request, HttpResponse>
-     *
-     * @param \SplObjectStorage<Request, HttpResponse> $storage
+     * @
      */
     public function objectKeys(\SplObjectStorage $storage): void {
-        // $req resolves to Request, $res resolves to HttpResponse
-        foreach ($storage as $req => $res) {
-            $req->getUri();     // Resolved: Request::getUri()
-            $req->method;       // Resolved: Request::$method
-            $res->statusCode;   // Resolved: HttpResponse::$statusCode
-            $res->getBody();    // Resolved: HttpResponse::getBody()
-        }
+        throw new MyCoolExceptionThatsInTheFunction();
     }
 
     public function weakMapKeys(): void {
@@ -1764,6 +1756,155 @@ public function demo(): void {
 $response->status;  // Resolved: string
 $response->code;    // Resolved: int
 
+// ─── Smart @throws Completion ───────────────────────────────────────────────
+//
+// When typing `@` inside a docblock for a function/method, PHPantomLSP
+// analyses the function body for `throw new ExceptionType(…)` statements
+// that are NOT caught by an enclosing try/catch block.  It then suggests:
+//
+//   @throws ExceptionType
+//
+// for each uncaught exception, filtering out types already documented.
+// If the exception class isn't imported, an auto-import `use` statement
+// is added as an additional edit.
+
+class NotFoundException extends \RuntimeException {}
+class ValidationException extends \RuntimeException {}
+class AuthorizationException extends \RuntimeException {}
+
+class ThrowsCompletionDemo
+{
+    /**
+     * Smart @throws: both exceptions are uncaught, so both are suggested.
+     * But only if they are not already hinted.
+     *
+     * @param int $id
+     * @return array
+     * @throws NotFoundException
+     * @throws ValidationException
+     */
+    public function findOrFail(int $id): array
+    {
+        if ($id < 0) {
+            throw new ValidationException('ID must be positive');
+        }
+        $result = $this->lookup($id);
+        if ($result === null) {
+            throw new NotFoundException('Record not found');
+        }
+        return $result;
+    }
+
+    /**
+     * Caught exceptions are excluded: RuntimeException is caught,
+     * so only AuthorizationException is suggested.
+     *
+     * @throws AuthorizationException
+     */
+    public function safeOperation(): void
+    {
+        $this->checkPermissions(); // may throw AuthorizationException
+
+        try {
+            throw new \RuntimeException('transient error');
+        } catch (\RuntimeException $e) {
+            // handled — not suggested in @throws
+        }
+
+        if (!$this->isAuthorized()) {
+            throw new AuthorizationException('Forbidden');
+        }
+    }
+
+    /**
+     * Multi-catch: both InvalidArgumentException and RuntimeException
+     * are caught, so only LogicException is suggested.
+     *
+     * @throws \LogicException
+     */
+    public function multiCatchDemo(): void
+    {
+        try {
+            throw new \InvalidArgumentException('bad');
+            throw new \RuntimeException('runtime');
+        } catch (\InvalidArgumentException | \RuntimeException $e) {
+            // both caught
+        }
+
+        throw new \LogicException('uncaught');
+    }
+
+    // ── Propagated @throws from called methods ──────────────────────
+
+    /**
+     * Calling $this->safeOperation() propagates its @throws tag.
+     * Typing `@` here suggests:
+     *
+     * @throws AuthorizationException
+     */
+    public function delegatedWork(): void
+    {
+        $this->safeOperation();
+    }
+
+    /**
+     * Multiple called methods propagate their @throws independently.
+     *
+     * @throws AuthorizationException (propagated from lookup via findOrFail's body)
+     * @throws NotFoundException      (propagated from safeOperation)
+     */
+    public function fullProcess(int $id): void
+    {
+        $this->safeOperation();
+        $result = $this->lookup($id);
+        if ($result === null) {
+            throw new NotFoundException('not found');
+        }
+    }
+
+    // ── throw $this->method() — return type detection ───────────────
+
+    /**
+     * `throw $this->makeException()` detects the return type of the
+     * called method and suggests it as @throws.
+     *
+     * @throws ValidationException
+     */
+    public function throwExpression(): void
+    {
+        throw $this->makeException();
+    }
+
+    /**
+     * @return ValidationException
+     */
+    private function makeException(): ValidationException
+    {
+        return new ValidationException('factory-produced error');
+    }
+
+    /**
+     * `throw self::createError()` also works with static calls.
+     * Typing `@` here suggests:
+     *   @throws AuthorizationException   (return type of createError)
+     *
+     * @throws AuthorizationException
+     */
+    public function throwStaticExpression(): void
+    {
+        throw self::createError();
+    }
+
+    private static function createError(): AuthorizationException
+    {
+        return new AuthorizationException('static factory');
+    }
+
+    private function lookup(int $id): ?array { return null; }
+    private function checkPermissions(): void {}
+    private function isAuthorized(): bool { return true; }
+}
+
 // Intersection with \stdClass (makes properties writable)
 /** @var object{name: string, value: int}&\stdClass $obj */
 $obj = getUnknownValue();

src/completion/handler.rs

@@ -46,24 +46,11 @@ impl Backend {
         if let Some(content) = content {
             let classes = classes.unwrap_or_default();
 
-            // ── PHPDoc tag completion ────────────────────────────────
-            // When the user types `@` inside a `/** … */` docblock,
-            // offer context-aware PHPDoc / PHPStan tag suggestions.
-            if let Some(prefix) =
-                crate::completion::phpdoc::extract_phpdoc_prefix(&content, position)
-            {
-                let context = crate::completion::phpdoc::detect_context(&content, position);
-                let items = crate::completion::phpdoc::build_phpdoc_completions(
-                    &content, &prefix, context, position,
-                );
-                if !items.is_empty() {
-                    return Ok(Some(CompletionResponse::Array(items)));
-                }
-            }
-
             // Gather the current file's `use` statement mappings and namespace
             // so the class_loader can resolve short names like `Resource` to
             // their fully-qualified equivalents like `Klarna\Rest\Resource`.
+            // These are loaded early because PHPDoc `@throws` completion
+            // needs them for auto-import edits.
             let file_use_map: HashMap<String, String> = if let Ok(map) = self.use_map.lock() {
                 map.get(&uri).cloned().unwrap_or_default()
             } else {
@@ -76,6 +63,26 @@ impl Backend {
                 None
             };
 
+            // ── PHPDoc tag completion ────────────────────────────────
+            // When the user types `@` inside a `/** … */` docblock,
+            // offer context-aware PHPDoc / PHPStan tag suggestions.
+            if let Some(prefix) =
+                crate::completion::phpdoc::extract_phpdoc_prefix(&content, position)
+            {
+                let context = crate::completion::phpdoc::detect_context(&content, position);
+                let items = crate::completion::phpdoc::build_phpdoc_completions(
+                    &content,
+                    &prefix,
+                    context,
+                    position,
+                    &file_use_map,
+                    &file_namespace,
+                );
+                if !items.is_empty() {
+                    return Ok(Some(CompletionResponse::Array(items)));
+                }
+            }
+
             // ── Named argument completion ───────────────────────────
             // When the cursor is inside the parentheses of a function or
             // method call, offer parameter names as `name:` completions.