Type hint completion in definitions

Author: AJenbo

example.php

@@ -353,6 +353,32 @@ function handleIntersection(User&Loggable $entity): void {
 $r = new Response(200);                   // → Response(${1:$statusCode})
 
 
+// ── Type Hint Completion in Definitions ─────────────────────────────────────
+// When typing a type hint inside a function/method definition, return type,
+// or property declaration, PHPantomLSP offers PHP native scalar types
+// (string, int, float, bool, …) alongside class-name completions.
+// Constants and standalone functions are excluded since they're invalid
+// in type positions.
+
+// Try triggering completion after the `(` or `,` in these signatures:
+function typeHintDemo(User $user, string $name): User { return $user; }
+//                    ↑ type hint  ↑ scalar      ↑ return type
+
+// Union types, nullable types, and intersection types also work:
+function unionDemo(string|int $value, ?User $maybe): User|null { return $maybe; }
+//                 ↑ after |   ↑ after ?             ↑ after |
+
+// Property type hints after visibility modifiers:
+// (see Model class below — `public readonly string $uuid`)
+
+// Promoted constructor parameters with modifiers:
+// (see Customer class below — `private readonly string $email`)
+
+// Closures and arrow functions:
+$typedClosure = function(User $u): string { return $u->getName(); };
+$typedArrow = fn(int $x): float => $x * 1.5;
+
+
 // ── parent:: Completion ─────────────────────────────────────────────────────
 // Open AdminUser's constructor and toArray() in scaffolding below for
 // parent:: examples (inherited methods, overridden methods, constants).

src/completion/handler.rs

@@ -219,6 +219,57 @@ impl Backend {
                 }
             }
 
+            // ── Type hint completion in definitions ─────────────────
+            // When the cursor is at a type-hint position inside a
+            // function/method parameter list, return type, or property
+            // declaration, offer PHP native scalar types alongside
+            // class-name completions (but NOT constants or standalone
+            // functions, which are invalid in type positions).
+            //
+            // This check MUST run before named-argument detection so
+            // that typing inside a function *definition* like
+            // `function foo(Us|)` offers type completions rather than
+            // named-argument suggestions for a same-named function.
+            if let Some(th_ctx) = crate::completion::type_hint_completion::detect_type_hint_context(
+                &content, position,
+            ) {
+                let partial_lower = th_ctx.partial.to_lowercase();
+                let mut items: Vec<CompletionItem> =
+                    crate::completion::type_hint_completion::PHP_NATIVE_TYPES
+                        .iter()
+                        .filter(|t| t.to_lowercase().starts_with(&partial_lower))
+                        .enumerate()
+                        .map(|(idx, t)| CompletionItem {
+                            label: t.to_string(),
+                            kind: Some(CompletionItemKind::KEYWORD),
+                            detail: Some("PHP built-in type".to_string()),
+                            insert_text: Some(t.to_string()),
+                            filter_text: Some(t.to_string()),
+                            sort_text: Some(format!("0_{:03}", idx)),
+                            ..CompletionItem::default()
+                        })
+                        .collect();
+
+                let (class_items, class_incomplete) = self.build_class_name_completions(
+                    &file_use_map,
+                    &file_namespace,
+                    &th_ctx.partial,
+                    &content,
+                    false, // not a `new` context
+                );
+                items.extend(class_items);
+
+                if !items.is_empty() {
+                    return Ok(Some(CompletionResponse::List(CompletionList {
+                        is_incomplete: class_incomplete,
+                        items,
+                    })));
+                }
+                // Even when empty, return early so we don't fall through
+                // to named-arg or class+constant+function completion.
+                return Ok(None);
+            }
+
             // ── Named argument completion ───────────────────────────
             // When the cursor is inside the parentheses of a function or
             // method call, offer parameter names as `name:` completions.

src/completion/mod.rs

@@ -14,6 +14,8 @@
 /// - **catch_completion**: Smart exception type completion inside `catch()` clauses
 /// - **conditional_resolution**: PHPStan conditional return type resolution at call sites
 /// - **type_narrowing**: instanceof / assert / custom type guard narrowing
+/// - **type_hint_completion**: Type completion inside function/method parameter lists,
+///   return types, and property declarations (offers native PHP types + class names)
 /// - **variable_resolution**: Variable type resolution via assignment scanning
 /// - **closure_resolution**: Closure and arrow-function parameter resolution
 ///
@@ -31,6 +33,7 @@ pub mod named_args;
 pub mod phpdoc;
 pub mod resolver;
 pub mod target;
+pub(crate) mod type_hint_completion;
 pub mod type_narrowing;
 pub mod use_edit;
 pub mod variable_completion;