Track array value types from variable-key assignments

Author: AJenbo

docs/CHANGELOG.md

@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **Array value type tracking from variable-key assignments.** When an array is built incrementally with variable keys inside a loop (`$arr[$key] = $value`), the element type is now tracked. Subsequent `foreach` iteration, bracket access, and null-coalescing (`$arr[$key] ?? null`) all resolve the correct element type instead of falling back to bare `array`.
 - **`Conditionable::when()` / `unless()` chain resolution.** Chained calls after `when()` or `unless()` on Eloquent Builder, Collection, and any class using the `Conditionable` trait now resolve correctly. Previously the unresolved `TWhenReturnType` template parameter in the return type broke chain continuation, so `Builder::where(...)->when(...)->get()` lost type information after `when()`.
 - **`whereHas` / `whereDoesntHave` closure parameter from relation traversal.** The closure parameter in `whereHas`, `orWhereHas`, `whereDoesntHave`, `orWhereDoesntHave`, `withWhereHas`, and related methods is now typed as `Builder<RelatedModel>` instead of `Builder<CallingModel>`. The relation name string (first argument) is resolved by walking the model's relationship methods. Dot-notation chains like `whereHas('category.articles', fn($q) => ...)` follow each segment to the final related model. Works for static calls (`Brand::whereHas(...)`), builder instance calls (`$query->whereHas(...)`), and body-inferred relationships (no `@return` annotation). Falls back to the calling model's builder when the relation cannot be resolved.
 - **Eloquent `where{PropertyName}()` dynamic methods.** Calls like `User::whereBrandId(42)` and `$query->whereLangCode('en')` now resolve instead of producing `unknown_member` diagnostics. For each known column on an Eloquent model (from `$casts`, `$attributes`, `$fillable`/`$guarded`/`$hidden`/`$appends`, `$dates`, timestamps, and `@property` annotations), a virtual `where{StudlyCase}()` method is synthesized on both the model (as a static method) and the Builder (as an instance method). Each method accepts a `mixed` value parameter and returns `Builder<ConcreteModel>`, so chains like `Bakery::whereFlour('rye')->whereApricot(true)->get()` resolve end-to-end.

docs/todo.md

@@ -23,7 +23,6 @@ within the same impact tier.
 
 | #   | Item                                                                                                                                             | Impact      | Effort      |
 | --- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- | ----------- |
-| T22 | [Array value type tracking from loop assignments](todo/type-inference.md#t22-array-value-type-tracking-from-loop-assignments)                    | Medium      | Medium      |
 | T23 | [`class-string<T>` static method dispatch](todo/type-inference.md#t23-class-stringt-static-method-dispatch)                                     | Medium      | Medium      |
 | T21 | [Bidirectional template inference](todo/type-inference.md#t21-bidirectional-template-inference-upperlower-bounds) (closure return type → generic) | Medium      | Medium-High |
 | H10 | [`return.unusedType` — remove unused type from return union](todo/phpstan-actions.md#h10-returnunusedtype--remove-unused-type-from-return-union) | Medium      | Medium      |

docs/todo/type-inference.md

@@ -488,37 +488,6 @@ simpler, but basic reconciliation can work with strings too).
 
 ---
 
-## T22. Array value type tracking from loop assignments
-**Impact: Medium · Effort: Medium**
-
-When a variable is initialized as `$arr = []` and then populated
-inside a loop with `$arr[$key] = $value`, PHPantom loses the element
-type entirely — it resolves `$arr` as bare `array`. Iterating the
-array in a subsequent `foreach` then produces `unresolved_member_access`
-on every element access.
-
-Examples from triage:
-
-- `$bundleProductCounts[$id] = ['bundle' => $productBundle, 'count' => 1]`
-  in a loop, then `$bundleProductCount['bundle']->parentProduct()` in
-  a second loop. (`ProductSupplyAmountChangeListener:56,58`.)
-- `$warehouseOrderLines[$key] = $orderLine` (where `$orderLine` is
-  `PCNPurchaseOrderLine`) in a loop, then
-  `$warehouseOrderLines[$key] ?? null` resolves as just `null` instead
-  of `PCNPurchaseOrderLine|null`. (`PCNService:1073,1077`.)
-
-The second example also requires the null-coalescing operator (`??`)
-to produce a union of both sides rather than only the fallback.
-
-**Implementation:** when processing an assignment like
-`$arr[$expr] = $rhs`, record the RHS type as the array's value type.
-When the same variable is accessed in a `foreach` or via bracket
-access, use the recorded value type for the element. For `$a ?? $b`,
-the result type should be `type($a) | type($b)` with `null` removed
-from the left side.
-
----
-
 ## T23. `class-string<T>` static method dispatch
 **Impact: Medium · Effort: Medium**
 

example.php

@@ -3180,6 +3180,38 @@ public function demo(): void
 }
 
 
+
+// ── Loop Array Build (variable-key assignment tracking) ─────────────────────
+
+class LoopArrayBuildDemo
+{
+    /** @param list<Pen> $pens */
+    public function demo(array $pens): void
+    {
+        // Variable-key assignment inside a loop: `$arr[$var] = $value`
+        // PHPantom tracks the RHS type as the array's element type.
+        $indexed = [];
+        foreach ($pens as $i => $pen) {
+            $key = $pen->color();
+            $indexed[$key] = $pen;
+        }
+
+        // Foreach over the built array resolves element members
+        foreach ($indexed as $item) {
+            $item->write();               // Pen method via element type tracking
+        }
+
+        // Bracket access resolves element type
+        $indexed['red']->color();         // Pen method
+
+        // Null-coalescing with guard clause
+        $found = $indexed['blue'] ?? null;
+        if ($found === null) { return; }
+        $found->write();                  // narrowed to Pen
+    }
+}
+
+
 // ═══════════════════════════════════════════════════════════════════════════
 // ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
 // ┃  SCAFFOLDING — Supporting definitions below this line.              ┃
@@ -5791,6 +5823,20 @@ function runDemoAssertions(): void
         assert($tgMixed instanceof Pen, 'Else branch of is_array() must be Pen');
     }
 
+    // ── Loop array build (variable-key assignment) ──────────────────────
+    $labPens = [new Pen('red'), new Pen('blue')];
+    $labIndexed = [];
+    foreach ($labPens as $labPen) {
+        $labKey = $labPen->color();
+        $labIndexed[$labKey] = $labPen;
+    }
+    assert($labIndexed['red'] instanceof Pen, 'Variable-key array element must be Pen');
+    foreach ($labIndexed as $labItem) {
+        assert($labItem instanceof Pen, 'Foreach over variable-key array must yield Pen');
+    }
+    $labFound = $labIndexed['blue'] ?? null;
+    assert($labFound instanceof Pen, 'Null-coalesce on variable-key array must resolve to Pen');
+
     echo "All assertions passed.\n";
 }
 

src/completion/variable/resolution.rs

@@ -3074,8 +3074,8 @@ pub(in crate::completion) fn check_expression_for_assignment<'b>(
             }
 
             let key = extract_array_key_for_shape(array_access.index);
-            // Skip numeric-only keys and unresolvable indices.
             if let Some(key) = key {
+                // ── String-literal key: merge into array shape ──
                 let rhs_ctx = ctx.with_cursor_offset(assignment.span().start.offset);
                 let resolved =
                     super::rhs_resolution::resolve_rhs_expression(assignment.rhs, &rhs_ctx);
@@ -3099,6 +3099,34 @@ pub(in crate::completion) fn check_expression_for_assignment<'b>(
                 let new_rt = ResolvedType::from_type_string(PhpType::parse(&merged));
                 results.clear();
                 results.push(new_rt);
+            } else {
+                // ── Non-literal key (variable, numeric, expression) ──
+                // Track the RHS type as the array's value type so that
+                // subsequent `foreach` iteration and bracket access
+                // resolve element members.  This handles patterns like
+                // `$arr[$id] = $orderLine` inside a loop.
+                let rhs_ctx = ctx.with_cursor_offset(assignment.span().start.offset);
+                let resolved =
+                    super::rhs_resolution::resolve_rhs_expression(assignment.rhs, &rhs_ctx);
+                let value_type = if !resolved.is_empty() {
+                    ResolvedType::type_strings_joined(&resolved)
+                } else {
+                    "mixed".to_string()
+                };
+                let base_string = results.last().map(|rt| rt.type_string.to_string());
+                let base = base_string.as_deref().unwrap_or("array");
+                // When the base already has a shape type from prior
+                // string-keyed assignments, do not overwrite it with
+                // a generic element type — shapes take precedence.
+                if base.starts_with("array{") {
+                    return;
+                }
+                // Infer the key type from the index expression.
+                let key_type = infer_array_key_type(array_access.index, &rhs_ctx);
+                let merged = merge_keyed_type(base, &key_type, &value_type);
+                let new_rt = ResolvedType::from_type_string(PhpType::parse(&merged));
+                results.clear();
+                results.push(new_rt);
             }
             return;
         }
@@ -3287,6 +3315,141 @@ fn merge_push_type(base: &str, value_type: &str) -> String {
     format!("list<{}>", elem_types.join("|"))
 }
 
+/// Merge a keyed element type into an existing type string to produce
+/// an `array<KeyType, ValueType>` type.
+///
+/// Similar to [`merge_push_type`] but preserves the key type from the
+/// index expression instead of assuming sequential integer keys.
+///
+/// When the base already has a generic value type (e.g.
+/// `array<string, User>`), the new value type is unioned with it and
+/// key types are unioned as well.
+///
+/// Examples:
+/// - `merge_keyed_type("array", "string", "User")` → `"array<string, User>"`
+/// - `merge_keyed_type("array<string, User>", "string", "Admin")`
+///   → `"array<string, User|Admin>"`
+/// - `merge_keyed_type("array<string, User>", "int", "Admin")`
+///   → `"array<string|int, User|Admin>"`
+fn merge_keyed_type(base: &str, key_type: &str, value_type: &str) -> String {
+    use crate::php_type::PhpType;
+
+    let parsed_base = PhpType::parse(base);
+
+    // Collect existing key types from the base.
+    let mut key_types: Vec<String> = Vec::new();
+    if let Some(existing_key) = parsed_base.extract_key_type(false) {
+        let s = existing_key.to_string();
+        if !s.is_empty() {
+            key_types.push(s);
+        }
+    }
+    // Add the new key type.
+    let new_key_parsed = PhpType::parse(key_type);
+    for member in new_key_parsed.union_members() {
+        let s = member.to_string();
+        if !s.is_empty() && !key_types.contains(&s) {
+            key_types.push(s);
+        }
+    }
+
+    // Collect existing value types from the base.
+    let mut elem_types: Vec<String> = Vec::new();
+    if let Some(existing_elem) = parsed_base.extract_element_type() {
+        for member in existing_elem.union_members() {
+            let s = member.to_string();
+            if !s.is_empty() {
+                elem_types.push(s);
+            }
+        }
+    }
+    // Add the new value type.
+    let new_val_parsed = PhpType::parse(value_type);
+    for member in new_val_parsed.union_members() {
+        let s = member.to_string();
+        if !s.is_empty() && !elem_types.contains(&s) {
+            elem_types.push(s);
+        }
+    }
+
+    if elem_types.is_empty() {
+        return "array".to_string();
+    }
+
+    let val_str = elem_types.join("|");
+    if key_types.is_empty() {
+        // No key type information — use a single-param generic.
+        format!("array<{}>", val_str)
+    } else {
+        format!("array<{}, {}>", key_types.join("|"), val_str)
+    }
+}
+
+/// Infer the key type of an array-access index expression.
+///
+/// Returns `"string"` for expressions that are known to produce
+/// strings (string literals, method calls returning `string`, string
+/// variables), `"int"` for integer expressions, and `"int|string"`
+/// when the type cannot be determined.
+fn infer_array_key_type(index: &Expression<'_>, ctx: &VarResolutionCtx<'_>) -> String {
+    // Fast path: literal values.
+    match index {
+        Expression::Literal(Literal::Integer(_)) => return "int".to_string(),
+        Expression::Literal(Literal::String(_)) => return "string".to_string(),
+        _ => {}
+    }
+
+    // Resolve the expression type through the standard pipeline.
+    let resolved = super::rhs_resolution::resolve_rhs_expression(index, ctx);
+    if !resolved.is_empty() {
+        let joined = ResolvedType::type_strings_joined(&resolved);
+        let key_str = joined.to_string();
+        // Normalise the resolved type to a valid array key type.
+        // PHP array keys are always int or string; bool and null are
+        // coerced to int, float is truncated to int.
+        if is_int_like_key(&key_str) {
+            return "int".to_string();
+        }
+        if key_str == "string" || key_str == "non-empty-string" || key_str == "class-string" {
+            return "string".to_string();
+        }
+        if key_str == "int|string" || key_str == "string|int" || key_str == "array-key" {
+            return "int|string".to_string();
+        }
+        // If the resolved type is a known scalar that PHP coerces
+        // to a key type, map it.  Otherwise fall through to the
+        // default.
+        if key_str == "mixed" {
+            return "int|string".to_string();
+        }
+        // For anything else (e.g. a class-string<T>, or a union),
+        // return as-is if it is composed entirely of int/string
+        // subtypes; otherwise fall back.
+        return key_str;
+    }
+
+    "int|string".to_string()
+}
+
+/// Returns `true` when the type string represents a PHP type that
+/// is always coerced to `int` when used as an array key.
+fn is_int_like_key(ty: &str) -> bool {
+    matches!(
+        ty,
+        "int"
+            | "float"
+            | "bool"
+            | "true"
+            | "false"
+            | "null"
+            | "positive-int"
+            | "negative-int"
+            | "non-negative-int"
+            | "non-positive-int"
+            | "non-zero-int"
+    )
+}
+
 // ── Array function type preservation helpers ─────────────────────────
 
 /// Extract the first positional argument expression from an