Implement method template support

Author: AJenbo

example.php

@@ -850,3 +850,119 @@ function test() {
         $this->cached->getEmail();   // $cached has type T → User
     }
 }
+
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Method-Level @template Support
+// ═══════════════════════════════════════════════════════════════════════════
+//
+// PHPantomLSP resolves method-level @template parameters from call-site
+// arguments.  The canonical pattern:
+//
+//   @template T
+//   @param class-string<T> $class
+//   @return T
+//
+// When you call such a method with `SomeClass::class`, the return type
+// is resolved to `SomeClass` — enabling full completion on the result.
+
+// ── Service Locator / DI Container Pattern ──────────────────────────────────
+
+class ServiceLocator {
+    /**
+     * @template T
+     * @param class-string<T> $id
+     * @return T
+     */
+    public function get(string $id): object
+    {
+        // ...
+    }
+}
+
+$locator = new ServiceLocator();
+$locator->get(User::class)->getEmail();          // Resolved: User
+$locator->get(UserProfile::class)->setBio('hi'); // Resolved: UserProfile
+
+
+// ── Entity Manager / Repository Pattern ─────────────────────────────────────
+
+class EntityManager {
+    /**
+     * @template TEntity
+     * @param class-string<TEntity> $entityClass
+     * @return TEntity
+     */
+    public function find(string $entityClass): object
+    {
+        // ...
+    }
+
+    /**
+     * @template TEntity
+     * @param class-string<TEntity> $entityClass
+     * @return TEntity|null
+     */
+    public function findOrNull(string $entityClass): ?object
+    {
+        // ...
+    }
+}
+
+$em = new EntityManager();
+$em->find(User::class)->getName();               // Resolved: User
+$em->find(AdminUser::class)->grantPermission(''); // Resolved: AdminUser
+$em->findOrNull(Response::class)?->getBody();    // Resolved: ?Response
+
+// Inline chain (no intermediate variable):
+$em->find(UserProfile::class)->getDisplayName(); // Resolved: UserProfile
+
+
+// ── Static Method with @template ────────────────────────────────────────────
+
+class Factory {
+    /**
+     * @template T
+     * @param class-string<T> $class
+     * @return T
+     */
+    public static function create(string $class): object
+    {
+        return new $class();
+    }
+}
+
+Factory::create(User::class)->getEmail();        // Resolved: User
+
+
+// ── Standalone Function with @template ──────────────────────────────────────
+
+/**
+ * @template T
+ * @param class-string<T> $class
+ * @return T
+ */
+function resolve(string $class): object
+{
+    return new $class();
+}
+
+resolve(AdminUser::class)->grantPermission('x'); // Resolved: AdminUser
+$user = resolve(User::class);
+$user->getEmail();                               // Resolved: User
+
+
+// ── @template with $this-> context ──────────────────────────────────────────
+
+class AbstractRepository2 {
+    /**
+     * @template T
+     * @param class-string<T> $class
+     * @return T
+     */
+    public function load(string $class): object { return new $class(); }
+
+    public function demo(): void {
+        $this->load(User::class)->getEmail();    // Resolved: User
+    }
+}

src/docblock/mod.rs

@@ -41,6 +41,7 @@ pub use tags::{
     extract_var_type, extract_var_type_with_name, find_inline_var_docblock,
     find_iterable_raw_type_in_source, find_var_raw_type_in_source, get_docblock_text_for_node,
     has_deprecated_tag, resolve_effective_type, should_override_type,
+    synthesize_template_conditional,
 };
 
 // Conditional return types

src/docblock/tags.rs

@@ -14,6 +14,8 @@ use mago_syntax::ast::*;
 
 use crate::types::{AssertionKind, MethodInfo, ParameterInfo, TypeAssertion, Visibility};
 
+use crate::types::{ConditionalReturnType, ParamCondition};
+
 use super::types::{clean_type, is_scalar, split_type_token, strip_nullable};
 
 // ─── Public API ─────────────────────────────────────────────────────────────
@@ -875,6 +877,137 @@ pub fn extract_generics_tag(docblock: &str, tag: &str) -> Vec<(String, Vec<Strin
     results
 }
 
+/// Attempt to synthesize a `ConditionalReturnType` from method-level
+/// `@template` annotations.
+///
+/// When a method (or standalone function) declares `@template T`,
+/// `@param class-string<T> $class`, and `@return T`, this creates a
+/// conditional return type that resolves `T` from the call-site argument.
+///
+/// For example, given:
+/// ```text
+/// @template T
+/// @param class-string<T> $class
+/// @return T
+/// ```
+/// Calling `find(User::class)` will resolve the return type to `User`.
+///
+/// Returns `None` when:
+///   - No template params are provided
+///   - The return type does not reference a template param
+///   - No `@param class-string<T>` annotation is found for the template param
+///   - An existing conditional return type is already present (pass `true`
+///     for `has_existing_conditional` to skip synthesis)
+pub fn synthesize_template_conditional(
+    docblock: &str,
+    template_params: &[String],
+    return_type: Option<&str>,
+    has_existing_conditional: bool,
+) -> Option<ConditionalReturnType> {
+    // Don't override an existing conditional return type.
+    if has_existing_conditional {
+        return None;
+    }
+
+    if template_params.is_empty() {
+        return None;
+    }
+
+    let ret = return_type?;
+
+    // Strip nullable prefix so that `?T` matches template param `T`.
+    let stripped = ret.strip_prefix('?').unwrap_or(ret);
+
+    // Check if the (stripped) return type is one of the template params.
+    if !template_params.iter().any(|t| t == stripped) {
+        return None;
+    }
+
+    // Find a `@param class-string<T> $paramName` annotation for this
+    // template param, and extract the parameter name (without `$`).
+    let param_name = find_class_string_param_name(docblock, stripped)?;
+
+    Some(ConditionalReturnType::Conditional {
+        param_name,
+        condition: ParamCondition::ClassString,
+        // `then_type` is unused for ClassString — the resolver extracts
+        // the class name directly from the argument (e.g. `User::class`
+        // → `"User"`).
+        then_type: Box::new(ConditionalReturnType::Concrete("mixed".into())),
+        // `else_type` is used when the argument is not a `::class`
+        // literal — `mixed` will produce `None` from resolution, which
+        // lets the caller fall back to the plain return type.
+        else_type: Box::new(ConditionalReturnType::Concrete("mixed".into())),
+    })
+}
+
+/// Search a docblock for a `@param class-string<T> $paramName` annotation
+/// where `T` matches the given `template_name`.
+///
+/// Returns the parameter name **without** the `$` prefix, or `None` if no
+/// matching annotation is found.
+///
+/// Handles common type variants:
+///   - `class-string<T>`
+///   - `?class-string<T>` (nullable)
+///   - `class-string<T>|null` (union with null)
+fn find_class_string_param_name(docblock: &str, template_name: &str) -> Option<String> {
+    let inner = docblock
+        .trim()
+        .strip_prefix("/**")
+        .unwrap_or(docblock)
+        .strip_suffix("*/")
+        .unwrap_or(docblock);
+
+    let pattern = format!("class-string<{}>", template_name);
+
+    for line in inner.lines() {
+        let trimmed = line.trim().trim_start_matches('*').trim();
+
+        if let Some(rest) = trimmed.strip_prefix("@param") {
+            let rest = rest.trim_start();
+            if rest.is_empty() {
+                continue;
+            }
+
+            // Extract the full type token (respects `<…>` nesting).
+            let (type_token, remainder) = split_type_token(rest);
+
+            // Check if the type token contains `class-string<T>`.
+            // We strip `?` prefix and check for the pattern.
+            let check = type_token.strip_prefix('?').unwrap_or(type_token);
+            // Also handle `class-string<T>|null` — split on `|` and
+            // check each part.
+            let matches = check.split('|').any(|part| part.trim() == pattern);
+
+            if !matches {
+                continue;
+            }
+
+            // The next token after the type should be `$paramName`.
+            // However, `split_type_token` splits at the closing `>`,
+            // so if the type is `class-string<T>|null`, the remainder
+            // will be `|null $class`.  Skip any union continuation
+            // (`|part`) before looking for the `$` variable name.
+            let mut search = remainder;
+            while let Some(rest) = search.strip_prefix('|') {
+                // Skip `|unionPart` — the next whitespace-delimited
+                // token is the union type, not the variable name.
+                let rest = rest.trim_start();
+                let (_, after) = split_type_token(rest);
+                search = after;
+            }
+            if let Some(var_name) = search.split_whitespace().next()
+                && let Some(name) = var_name.strip_prefix('$')
+            {
+                return Some(name.to_string());
+            }
+        }
+    }
+
+    None
+}
+
 /// Split a comma-separated generic argument list, respecting `<…>` and `(…)`
 /// nesting.  Returns cleaned argument strings.
 ///

src/parser/classes.rs

@@ -389,6 +389,25 @@ impl Backend {
                             docblock::get_docblock_text_for_node(ctx.trivias, ctx.content, method)
                                 .and_then(docblock::extract_conditional_return_type);
 
+                        // If no explicit conditional return type was found,
+                        // try to synthesize one from method-level @template
+                        // annotations.  For example:
+                        //   @template T
+                        //   @param class-string<T> $class
+                        //   @return T
+                        // becomes a conditional that resolves T from the
+                        // call-site argument (e.g. find(User::class) → User).
+                        let conditional = conditional.or_else(|| {
+                            let doc = docblock_text?;
+                            let tpl_params = docblock::extract_template_params(doc);
+                            docblock::synthesize_template_conditional(
+                                doc,
+                                &tpl_params,
+                                effective.as_deref(),
+                                false,
+                            )
+                        });
+
                         let deprecated = docblock_text.is_some_and(docblock::has_deprecated_tag);
 
                         (effective, conditional, deprecated)

src/parser/functions.rs

@@ -54,6 +54,25 @@ impl Backend {
                             let conditional =
                                 docblock_text.and_then(docblock::extract_conditional_return_type);
 
+                            // If no explicit conditional return type was found,
+                            // try to synthesize one from function-level @template
+                            // annotations.  For example:
+                            //   @template T
+                            //   @param class-string<T> $class
+                            //   @return T
+                            // becomes a conditional that resolves T from the
+                            // call-site argument (e.g. resolve(User::class) → User).
+                            let conditional = conditional.or_else(|| {
+                                let doc = docblock_text?;
+                                let tpl_params = docblock::extract_template_params(doc);
+                                docblock::synthesize_template_conditional(
+                                    doc,
+                                    &tpl_params,
+                                    effective.as_deref(),
+                                    false,
+                                )
+                            });
+
                             let assertions = docblock_text
                                 .map(docblock::extract_type_assertions)
                                 .unwrap_or_default();