Support array element access

Author: AJenbo

example.php

@@ -670,3 +670,26 @@ function handleIntersection(User&Loggable $entity): void
 foreach ($admins as $admin) {
     $admin->grantPermission('x'); // $admin resolved to AdminUser via array<int, AdminUser>
 }
+
+
+// ── Array Access Element Types ──────────────────────────────────────────────
+
+/** @var list<User> $users */
+$users = getUnknownValue();
+$users[0]->getEmail();           // element resolved to User via list<User>
+
+/** @var User[] $members */
+$members = getUnknownValue();
+$members[0]->getName();          // element resolved to User via User[]
+
+/** @var array<int, AdminUser> $admins */
+$admins = getUnknownValue();
+$admins[0]->grantPermission('x'); // element resolved to AdminUser via array<int, AdminUser>
+$key = 0;
+$admins[$key]->grantPermission('y'); // variable key works too
+
+$admin = $admins[0];
+$admin->grantPermission('z');    // assigned from array access → AdminUser
+
+$user = $users[0];
+$user->getEmail();               // assigned from array access → User

src/completion/resolver.rs

@@ -18,6 +18,7 @@
 /// - [`super::conditional_resolution`]: PHPStan conditional return type
 ///   resolution at call sites.
 use crate::Backend;
+use crate::docblock;
 use crate::types::*;
 
 use super::conditional_resolution::{
@@ -191,6 +192,26 @@ impl Backend {
             return vec![];
         }
 
+        // ── Array-element access: `$var[]` ──
+        // When the subject ends with `[]`, the user wrote `$var[0]->` or
+        // `$var[$key]->`.  Resolve the base variable's generic/iterable
+        // type and extract the element type.
+        if let Some(base_var) = subject.strip_suffix("[]")
+            && base_var.starts_with('$')
+        {
+            let resolved = Self::resolve_array_element_type(
+                base_var,
+                content,
+                cursor_offset,
+                current_class,
+                all_classes,
+                class_loader,
+            );
+            if !resolved.is_empty() {
+                return resolved;
+            }
+        }
+
         // ── Variable like `$var` — resolve via assignments / parameter hints ──
         if subject.starts_with('$') {
             // When the cursor is inside a class, use the enclosing class
@@ -243,6 +264,43 @@ impl Backend {
     ///
     /// Returns all candidate classes when the return type is a union
     /// (e.g. `A|B`).
+    /// Resolve the element type of an array/list variable accessed with `[]`.
+    ///
+    /// Given a base variable name like `$admins`, searches backward from
+    /// `cursor_offset` for a `@var` / `@param` docblock annotation that
+    /// declares a generic iterable type (e.g. `array<int, AdminUser>`,
+    /// `list<User>`, `User[]`).  Extracts the element type and resolves
+    /// it to `ClassInfo`.
+    fn resolve_array_element_type(
+        base_var: &str,
+        content: &str,
+        cursor_offset: u32,
+        current_class: Option<&ClassInfo>,
+        all_classes: &[ClassInfo],
+        class_loader: &dyn Fn(&str) -> Option<ClassInfo>,
+    ) -> Vec<ClassInfo> {
+        let current_class_name = current_class.map(|c| c.name.as_str()).unwrap_or("");
+
+        // Search backward from the cursor for a @var/@param annotation on
+        // this variable that includes a generic type.
+        let raw_type = match docblock::find_iterable_raw_type_in_source(
+            content,
+            cursor_offset as usize,
+            base_var,
+        ) {
+            Some(t) => t,
+            None => return vec![],
+        };
+
+        // 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 vec![],
+        };
+
+        Self::type_hint_to_classes(&element_type, current_class_name, all_classes, class_loader)
+    }
+
     pub(super) fn resolve_call_return_types(
         call_body: &str,
         text_args: &str,

src/completion/variable_resolution.rs

@@ -944,6 +944,34 @@ impl Backend {
                 }
                 return;
             }
+            // Check RHS is an array access: `$var = $arr[0]` or `$var = $arr[$key]`
+            // Resolve the base array's generic/iterable type and extract
+            // the element type.
+            if let Expression::ArrayAccess(array_access) = assignment.rhs {
+                // The base expression must be a simple variable (e.g. `$admins`).
+                if let Expression::Variable(Variable::Direct(base_dv)) = array_access.array {
+                    let base_var = base_dv.name.to_string();
+                    // Search backward from this assignment for a @var/@param
+                    // annotation on the base variable with a generic type.
+                    let assign_offset = assignment.span().start.offset as usize;
+                    if let Some(raw_type) = docblock::find_iterable_raw_type_in_source(
+                        content,
+                        assign_offset,
+                        &base_var,
+                    ) && let Some(element_type) =
+                        docblock::types::extract_generic_value_type(&raw_type)
+                    {
+                        let resolved = Self::type_hint_to_classes(
+                            &element_type,
+                            current_class_name,
+                            all_classes,
+                            class_loader,
+                        );
+                        push_results(results, resolved, conditional);
+                    }
+                }
+                return;
+            }
             // Check RHS is a function call: `$var = someFunction(…)`
             // Look up the function's return type and resolve to a class.
             if let Expression::Call(call) = assignment.rhs {

src/subject_extraction.rs

@@ -59,6 +59,32 @@ pub(crate) fn skip_balanced_parens_back(chars: &[char], pos: usize) -> Option<us
     None
 }
 
+/// Skip backwards past a balanced bracket group `[…]` in a char slice.
+///
+/// `pos` must point one past the closing `]`.  Returns the index of the
+/// opening `[`, or `None` if brackets are unbalanced.
+pub(crate) fn skip_balanced_brackets_back(chars: &[char], pos: usize) -> Option<usize> {
+    if pos == 0 || chars[pos - 1] != ']' {
+        return None;
+    }
+    let mut depth: u32 = 0;
+    let mut j = pos;
+    while j > 0 {
+        j -= 1;
+        match chars[j] {
+            ']' => depth += 1,
+            '[' => {
+                depth -= 1;
+                if depth == 0 {
+                    return Some(j);
+                }
+            }
+            _ => {}
+        }
+    }
+    None
+}
+
 /// Check if the `new` keyword (followed by whitespace) appears immediately
 /// before the identifier starting at position `ident_start`.
 ///
@@ -185,6 +211,22 @@ pub(crate) fn extract_arrow_subject(chars: &[char], arrow_pos: usize) -> String
     // (past any `?` and whitespace).
     end = i;
 
+    // ── Array access: detect `]` ──
+    // e.g. `$admins[0]->`, `$admins[$key]->`
+    // Skip backwards past balanced `[…]` and extract the variable before it.
+    if i > 0
+        && chars[i - 1] == ']'
+        && let Some(bracket_open) = skip_balanced_brackets_back(chars, i)
+    {
+        // Now extract whatever is before the `[` — typically a variable.
+        let before_bracket = extract_simple_variable(chars, bracket_open);
+        if !before_bracket.is_empty() {
+            // Return subject with `[]` suffix so the resolver knows
+            // this is an array-element access.
+            return format!("{}[]", before_bracket);
+        }
+    }
+
     // ── Function / method call or `new` expression: detect `)` ──
     // e.g. `app()->`, `$this->getService()->`, `Class::make()->`,
     //      `new Foo()->`, `(new Foo())->`

tests/completion_variable_names.rs

@@ -1912,18 +1912,18 @@ async fn test_completion_variables_at_eof_with_actual_example_php() {
     let backend = create_test_backend();
     let uri = Url::parse("file:///example_eof.php").unwrap();
 
-    let base_content = std::fs::read_to_string("example.php")
-        .expect("example.php must exist in the project root");
-    
+    let base_content =
+        std::fs::read_to_string("example.php").expect("example.php must exist in the project root");
+
     // Scenario: user appends "$" on a new line at the end.
     // base_content already ends with "\n", so we just append "$\n".
     let text = format!("{}$\n", base_content);
     let line_count = text.lines().count() as u32;
-    
+
     // The `$` is on the last non-empty line (line_count - 2, since
     // trailing \n produces an empty final line that .lines() drops,
     // but the `$` line is the last element returned by .lines()).
-    let dollar_line = line_count - 1;  // 0-indexed, last line from .lines()
+    let dollar_line = line_count - 1; // 0-indexed, last line from .lines()
 
     let items = complete_at(&backend, &uri, &text, dollar_line, 1).await;