Add support iterable value type and some basic generics

Author: AJenbo

example.php

@@ -648,3 +648,25 @@ function handleIntersection(User&Loggable $entity): void
 } else {
     $l->grantPermission('y');    // negated else → AdminUser
 }
+
+
+// ── Generics / Foreach Element Types ────────────────────────────────────────
+
+/** @var list<User> $users */
+$users = getUnknownValue();
+foreach ($users as $user) {
+    $user->getEmail();           // $user resolved to User via list<User>
+    $user->getName();
+}
+
+/** @var User[] $members */
+$members = getUnknownValue();
+foreach ($members as $member) {
+    $member->getStatus();        // $member resolved to User via User[]
+}
+
+/** @var array<int, AdminUser> $admins */
+$admins = getUnknownValue();
+foreach ($admins as $admin) {
+    $admin->grantPermission('x'); // $admin resolved to AdminUser via array<int, AdminUser>
+}

src/completion/variable_resolution.rs

@@ -10,6 +10,10 @@
 ///   - Conditional branches (if/else, try/catch, loops) — collects all
 ///     possible types when the variable is assigned differently in each
 ///     branch.
+///   - Foreach value variables: when iterating over a variable annotated
+///     with a generic iterable type (e.g. `@var list<User>`, `@param
+///     list<User>`, `User[]`), the foreach value variable is resolved to
+///     the element type.
 ///
 /// Type narrowing (instanceof, assert, custom type guards) is delegated
 /// to the [`super::type_narrowing`] module.  Closure/arrow-function scope
@@ -471,19 +475,33 @@ impl Backend {
                         }
                     }
                 },
-                Statement::Foreach(foreach) => match &foreach.body {
-                    ForeachBody::Statement(inner) => {
-                        Self::check_statement_for_assignments(inner, ctx, results, true);
-                    }
-                    ForeachBody::ColonDelimited(body) => {
-                        Self::walk_statements_for_assignments(
-                            body.statements.iter(),
-                            ctx,
-                            results,
-                            true,
-                        );
+                Statement::Foreach(foreach) => {
+                    // ── Foreach value type from generic iterables ────
+                    // When the variable we're resolving is the foreach
+                    // *value* variable, try to infer its type from the
+                    // iterated expression's generic type annotation.
+                    //
+                    // Example:
+                    //   /** @var list<User> $users */
+                    //   foreach ($users as $user) { $user-> }
+                    //
+                    // Here `$user` is resolved to `User`.
+                    Self::try_resolve_foreach_value_type(foreach, ctx, results, conditional);
+
+                    match &foreach.body {
+                        ForeachBody::Statement(inner) => {
+                            Self::check_statement_for_assignments(inner, ctx, results, true);
+                        }
+                        ForeachBody::ColonDelimited(body) => {
+                            Self::walk_statements_for_assignments(
+                                body.statements.iter(),
+                                ctx,
+                                results,
+                                true,
+                            );
+                        }
                     }
-                },
+                }
                 Statement::While(while_stmt) => match &while_stmt.body {
                     WhileBody::Statement(inner) => {
                         // ── instanceof narrowing for while-body ──
@@ -575,6 +593,85 @@ impl Backend {
     }
 
     /// Helper: treat a single statement as an iterator of one and recurse.
+    /// Try to resolve the foreach value variable's type from a generic
+    /// iterable annotation on the iterated expression.
+    ///
+    /// When the variable being resolved (`ctx.var_name`) matches the
+    /// foreach value variable and the iterated expression is a simple
+    /// `$variable` whose type is annotated as a generic iterable (via
+    /// `@var list<User> $var` or `@param list<User> $var`), this method
+    /// extracts the element type and pushes the resolved `ClassInfo` into
+    /// `results`.
+    fn try_resolve_foreach_value_type<'b>(
+        foreach: &'b Foreach<'b>,
+        ctx: &VarResolutionCtx<'_>,
+        results: &mut Vec<ClassInfo>,
+        conditional: bool,
+    ) {
+        // Check if the foreach value variable is the one we're resolving.
+        let value_expr = foreach.target.value();
+        let value_var_name = match value_expr {
+            Expression::Variable(Variable::Direct(dv)) => dv.name.to_string(),
+            _ => return,
+        };
+        if value_var_name != ctx.var_name {
+            return;
+        }
+
+        // Extract the iterated expression's source text.
+        let expr_span = foreach.expression.span();
+        let expr_start = expr_span.start.offset as usize;
+        let expr_end = expr_span.end.offset as usize;
+        let expr_text = match ctx.content.get(expr_start..expr_end) {
+            Some(t) => t.trim(),
+            None => return,
+        };
+
+        // Currently we handle simple `$variable` expressions.
+        if !expr_text.starts_with('$') || expr_text.contains("->") || expr_text.contains("::") {
+            return;
+        }
+
+        // Search backward from the foreach for @var or @param annotations
+        // on the iterated variable that include a generic type.
+        let foreach_offset = foreach.foreach.span().start.offset as usize;
+        let raw_type = match docblock::find_iterable_raw_type_in_source(
+            ctx.content,
+            foreach_offset,
+            expr_text,
+        ) {
+            Some(t) => t,
+            None => return,
+        };
+
+        // Extract the generic element type (e.g. `list<User>` → `User`).
+        let element_type = match docblock::types::extract_generic_value_type(&raw_type) {
+            Some(t) => t,
+            None => return,
+        };
+
+        // Resolve the element type to ClassInfo.
+        let resolved = Self::type_hint_to_classes(
+            &element_type,
+            &ctx.current_class.name,
+            ctx.all_classes,
+            ctx.class_loader,
+        );
+
+        if resolved.is_empty() {
+            return;
+        }
+
+        if !conditional {
+            results.clear();
+        }
+        for cls in resolved {
+            if !results.iter().any(|c| c.name == cls.name) {
+                results.push(cls);
+            }
+        }
+    }
+
     pub(super) fn check_statement_for_assignments<'b>(
         stmt: &'b Statement<'b>,
         ctx: &VarResolutionCtx<'_>,

src/docblock/mod.rs

@@ -36,14 +36,14 @@ pub(crate) mod types;
 
 // Tags
 pub use tags::{
-    extract_method_tags, extract_mixin_tags, extract_property_tags, extract_return_type,
-    extract_type_assertions, extract_var_type, extract_var_type_with_name,
-    find_inline_var_docblock, get_docblock_text_for_node, has_deprecated_tag,
-    resolve_effective_type, should_override_type,
+    extract_method_tags, extract_mixin_tags, extract_param_raw_type, extract_property_tags,
+    extract_return_type, extract_type_assertions, 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,
 };
 
 // Conditional return types
 pub use conditional::extract_conditional_return_type;
 
 // Type utilities
-pub use types::clean_type;
+pub use types::{clean_type, extract_generic_value_type};

src/docblock/tags.rs

@@ -279,6 +279,163 @@ pub fn find_inline_var_docblock(
     extract_var_type_with_name(docblock)
 }
 
+/// Search backward through `content` (up to `before_offset`) for any
+/// `/** @var RawType $var_name */` annotation and return the **raw**
+/// (uncleaned) type string — including generic parameters like `<User>`.
+///
+/// This is used by foreach element-type resolution: when iterating over
+/// a variable annotated as `list<User>`, we need the raw `list<User>`
+/// string so that the generic value type (`User`) can be extracted.
+///
+/// Only matches annotations that explicitly name the variable
+/// (e.g. `/** @var list<User> $users */`).
+pub fn find_var_raw_type_in_source(
+    content: &str,
+    before_offset: usize,
+    var_name: &str,
+) -> Option<String> {
+    let search_area = content.get(..before_offset)?;
+
+    for line in search_area.lines().rev() {
+        let trimmed = line.trim();
+
+        // Quick reject: must mention both `@var` and the variable.
+        if !trimmed.contains("@var") || !trimmed.contains(var_name) {
+            continue;
+        }
+
+        // Strip docblock delimiters — handles single-line `/** @var … */`.
+        let inner = trimmed
+            .strip_prefix("/**")
+            .unwrap_or(trimmed)
+            .strip_suffix("*/")
+            .unwrap_or(trimmed);
+        let inner = inner.trim().trim_start_matches('*').trim();
+
+        if let Some(rest) = inner.strip_prefix("@var") {
+            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);
+
+            // The next token must be our variable name.
+            if let Some(name) = remainder.split_whitespace().next()
+                && name == var_name
+            {
+                return Some(type_token.to_string());
+            }
+        }
+    }
+
+    None
+}
+
+/// Extract the raw (uncleaned) type from a `@param` tag for a specific
+/// parameter in a docblock string.
+///
+/// Given a docblock and a parameter name (with `$` prefix), returns the
+/// raw type string including generic parameters.
+///
+/// Example:
+///   docblock containing `@param list<User> $users` with var_name `"$users"`
+///   → `Some("list<User>")`
+pub fn extract_param_raw_type(docblock: &str, var_name: &str) -> Option<String> {
+    let inner = docblock
+        .trim()
+        .strip_prefix("/**")
+        .unwrap_or(docblock)
+        .strip_suffix("*/")
+        .unwrap_or(docblock);
+
+    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);
+
+            // The next token should be the parameter name.
+            if let Some(name) = remainder.split_whitespace().next()
+                && name == var_name
+            {
+                return Some(type_token.to_string());
+            }
+        }
+    }
+
+    None
+}
+
+/// Search backward through `content` (up to `before_offset`) for any
+/// `@var` or `@param` annotation that assigns a raw (uncleaned) type to
+/// `$var_name`.
+///
+/// This combines the logic of [`find_var_raw_type_in_source`] (which looks
+/// for `@var Type $var`) and a backward scan for `@param Type $var` in
+/// method/function docblocks.
+///
+/// Returns the first matching raw type string (including generic parameters
+/// like `list<User>`), or `None` if no annotation is found.
+pub fn find_iterable_raw_type_in_source(
+    content: &str,
+    before_offset: usize,
+    var_name: &str,
+) -> Option<String> {
+    let search_area = content.get(..before_offset)?;
+
+    for line in search_area.lines().rev() {
+        let trimmed = line.trim();
+
+        // Quick reject: must mention the variable name.
+        if !trimmed.contains(var_name) {
+            continue;
+        }
+
+        // Strip docblock delimiters — handles single-line `/** @var … */`
+        // and multi-line `* @param …` lines.
+        let inner = trimmed
+            .strip_prefix("/**")
+            .unwrap_or(trimmed)
+            .strip_suffix("*/")
+            .unwrap_or(trimmed);
+        let inner = inner.trim().trim_start_matches('*').trim();
+
+        // Try @var first, then @param.
+        let rest = if let Some(r) = inner.strip_prefix("@var") {
+            Some(r)
+        } else {
+            inner.strip_prefix("@param")
+        };
+
+        if let Some(rest) = rest {
+            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);
+
+            // The next token must be our variable name.
+            if let Some(name) = remainder.split_whitespace().next()
+                && name == var_name
+            {
+                return Some(type_token.to_string());
+            }
+        }
+    }
+
+    None
+}
+
 /// Extract all `@property` tags from a class-level docblock.
 ///
 /// PHPDoc `@property` tags declare magic properties that are accessible via