Complete known required arguments

Author: AJenbo

example.php

@@ -2221,3 +2221,58 @@ function getTimeout(): int
 if (MAX_RETRIES > 0) {  // → jumps to define('MAX_RETRIES', ...)
     echo APP_VERSION;   // → jumps to define('APP_VERSION', ...)
 }
+
+// ─── Callable Snippet Insertion ─────────────────────────────────────────────
+//
+// When completing methods, functions, or `new ClassName`, the LSP inserts
+// a snippet with parentheses and tab-stops for each **required** parameter.
+// Optional and variadic parameters are omitted — use signature help to
+// fill those in.
+//
+// Method examples:
+//   $user->setName(|)         — setName(string $name) → snippet: setName(${1:\$name})
+//   $user->toArray()          — toArray() has no params → snippet: toArray()
+//   $user->addRoles(|)        — addRoles(string ...$roles) variadic → snippet: addRoles()
+//
+// Function examples:
+//   createUser(|)             — createUser(string $name, …) → snippet: createUser(${1:\$name})
+//   Built-in stubs like json_decode get empty parens: json_decode()
+//
+// `new ClassName` examples (same-namespace classes get full constructor params):
+//   new User(|,|)             — __construct(string $name, string $email) → User(${1:\$name}, ${2:\$email})
+//   new Response(|)           — __construct(int $statusCode, …) → Response(${1:\$statusCode})
+//   Classes from classmap/stubs just get empty parens: new DateTime()
+
+class CallableSnippetDemo
+{
+    public function methodSnippets(User $user, Response $response): void
+    {
+        // Try completing after `->` — each inserts a snippet with required params:
+        $user->setName($name);   // Inserted: setName(${1:$name})        — 1 required param
+        $user->toArray();        // Inserted: toArray()                  — no params
+        $user->addRoles();       // Inserted: addRoles()                 — variadic only
+        $response->getBody();    // Inserted: getBody()                  — no params
+    }
+
+    public function staticSnippets(): void
+    {
+        // Static method calls also get snippets:
+        User::findByEmail($email);    // Inserted: findByEmail(${1:$email})   — 1 required param
+        Model::find($id);             // Inserted: find(${1:$id})             — 1 required param
+    }
+
+    public function newSnippets(): void
+    {
+        // `new` inserts class name + constructor params as snippet:
+        $u = new User($name, $email)          // Inserted: User(${1:$name}, ${2:$email}) — 2 required
+        $r = new Response($statusCode);       // Inserted: Response(${1:$statusCode})    — 1 required
+        $a = new AdminUser($name, $email);    // Inserted: AdminUser(${1:$name}, ${2:$email}, ${3:$role})
+    }
+
+    public function parentConstructorSnippet(): void
+    {
+        // parent::__construct also gets snippets when inside a subclass.
+        // See AdminUser::__construct for an example:
+        //   parent::__construct(${1:$name}, ${2:$email})
+    }
+}

src/completion/builder.rs

@@ -12,6 +12,43 @@ use crate::Backend;
 use crate::types::Visibility;
 use crate::types::*;
 
+/// Build an LSP snippet string for a callable (function, method, or constructor).
+///
+/// Required parameters are included as numbered tab stops with their
+/// PHP variable name as placeholder text.  Optional and variadic
+/// parameters are omitted — they can be filled in via signature help.
+///
+/// The returned string uses LSP snippet syntax and **must** be paired
+/// with `InsertTextFormat::SNIPPET` on the `CompletionItem`.
+///
+/// # Examples
+///
+/// | call                                       | result                              |
+/// |--------------------------------------------|-------------------------------------|
+/// | `("reset", &[])`                           | `"reset()$0"`                       |
+/// | `("makeText", &[req($text), opt($long)])`  | `"makeText(${1:\\$text})$0"`        |
+/// | `("add", &[req($a), req($b)])`             | `"add(${1:\\$a}, ${2:\\$b})$0"`     |
+pub(crate) fn build_callable_snippet(name: &str, params: &[ParameterInfo]) -> String {
+    let required: Vec<&ParameterInfo> = params.iter().filter(|p| p.is_required).collect();
+
+    if required.is_empty() {
+        format!("{name}()$0")
+    } else {
+        let placeholders: Vec<String> = required
+            .iter()
+            .enumerate()
+            .map(|(i, p)| {
+                // Escape `$` in parameter names so it is treated as a
+                // literal character rather than a snippet tab-stop /
+                // variable reference.
+                let escaped_name = p.name.replace('$', "\\$");
+                format!("${{{}:{}}}", i + 1, escaped_name)
+            })
+            .collect();
+        format!("{name}({})$0", placeholders.join(", "))
+    }
+}
+
 // Re-export use-statement helpers so existing `use crate::completion::builder::{…}`
 // imports continue to work.
 pub(crate) use super::use_edit::{build_use_edit, find_use_insert_position};
@@ -169,7 +206,8 @@ impl Backend {
                 label,
                 kind: Some(CompletionItemKind::METHOD),
                 detail: Some(format!("Class: {}", target_class.name)),
-                insert_text: Some(method.name.clone()),
+                insert_text: Some(build_callable_snippet(&method.name, &method.parameters)),
+                insert_text_format: Some(InsertTextFormat::SNIPPET),
                 filter_text: Some(method.name.clone()),
                 deprecated: if method.is_deprecated {
                     Some(true)