Support foreach over arrays with array shape element types

Author: AJenbo

docs/CHANGELOG.md

@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **Foreach over arrays with non-class element types.** When iterating over a generic array whose value type is an array shape (e.g. `array<int, array{tool: Pen, count: int}>`), the foreach iteration variable now carries the full shape type. Bracket access on the iteration variable (`$entry['tool']->`) resolves each key to its declared type. Previously the element type was silently dropped when it was not a class name, leaving the iteration variable untyped.
 - **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.

example.php

@@ -1389,6 +1389,25 @@ public function demo(): void
 }
 
 
+// ── Foreach Array Shape Elements ────────────────────────────────────────────
+
+class ForeachArrayShapeDemo
+{
+    /**
+     * @param array<int, array{tool: Pen, count: int}> $inventory
+     */
+    public function demo(array $inventory): void
+    {
+        // When iterating over an array whose value type is an array shape,
+        // the foreach variable carries the shape type so that bracket
+        // access resolves each key to its declared type.
+        foreach ($inventory as $entry) {
+            $entry['tool']->write();      // array{tool: Pen, count: int} → Pen
+        }
+    }
+}
+
+
 // ── Variadic Parameter Foreach ──────────────────────────────────────────────
 
 class VariadicForeachDemo
@@ -5920,6 +5939,13 @@ function runDemoAssertions(): void
         assert($tgMixed instanceof Pen, 'Else branch of is_array() must be Pen');
     }
 
+    // ── Foreach array shape elements ────────────────────────────────────
+    /** @var array<int, array{tool: Pen, count: int}> $fasInventory */
+    $fasInventory = [['tool' => new Pen('red'), 'count' => 3]];
+    foreach ($fasInventory as $fasEntry) {
+        assert($fasEntry['tool'] instanceof Pen, 'Foreach over array shape must resolve key type');
+    }
+
     // ── Loop array build (variable-key assignment) ──────────────────────
     $labPens = [new Pen('red'), new Pen('blue')];
     $labIndexed = [];

src/completion/variable/foreach_resolution.rs

@@ -249,7 +249,13 @@ pub(in crate::completion) fn try_resolve_foreach_value_type<'b>(
     // Extract the generic element type (e.g. `list<User>` → `User`).
     if let Some(ref rt) = raw_type {
         let parsed = crate::php_type::PhpType::parse(rt);
-        if let Some(element_type) = parsed.extract_value_type(true) {
+        // Use `extract_value_type(false)` to include non-class element
+        // types such as array shapes (`array{key: Type}`), scalars, and
+        // generic arrays.  The foreach value variable may be used with
+        // bracket access (`$item['key']->`) or other operations where
+        // a non-class type is meaningful.  `push_foreach_resolved_types_typed`
+        // handles both class and non-class element types.
+        if let Some(element_type) = parsed.extract_value_type(false) {
             push_foreach_resolved_types_typed(element_type, ctx, results, conditional);
             return;
         }
@@ -475,11 +481,21 @@ fn push_foreach_resolved_types_typed(
         ctx.class_loader,
     );
 
-    if resolved.is_empty() {
-        return;
-    }
+    let resolved_types = if resolved.is_empty() {
+        // The element type is not a class (e.g. an array shape like
+        // `array{bundle: Product, count: int}`, a scalar, or a
+        // generic array).  Push a type-only ResolvedType so that
+        // downstream consumers (array bracket access, hover, etc.)
+        // can still see the structured type string and resolve
+        // through it.
+        if matches!(ty, PhpType::Named(n) if n == "mixed") {
+            return;
+        }
+        vec![ResolvedType::from_type_string(ty.clone())]
+    } else {
+        ResolvedType::from_classes_with_hint(resolved, ty.clone())
+    };
 
-    let resolved_types = ResolvedType::from_classes_with_hint(resolved, ty.clone());
     if !conditional {
         results.clear();
     }

tests/integration/completion_variables.rs

@@ -20722,3 +20722,78 @@ async fn test_completion_foreach_variadic_param_standalone_function() {
         _ => panic!("Expected CompletionResponse::Array"),
     }
 }
+
+// ─── Foreach variable type from @param array shape ──────────────────────────
+
+/// When a parameter is annotated with `@param array<int, array{bundle: Product, count: int}>`,
+/// iterating over it with foreach should propagate the value type so that
+/// `$entry['bundle']->` resolves to `Product`.
+#[tokio::test]
+async fn test_foreach_variable_type_from_param_array_shape() {
+    let backend = create_test_backend();
+
+    let uri = Url::parse("file:///foreach_param_shape.php").unwrap();
+    let text = concat!(
+        "<?php\n",                                                                    // 0
+        "class Product {\n",                                                          // 1
+        "    public string $sku;\n",                                                  // 2
+        "    public function parentProduct(): Product { return new self(); }\n",      // 3
+        "}\n",                                                                        // 4
+        "\n",                                                                         // 5
+        "class Listener {\n",                                                         // 6
+        "    /** @param array<int, array{bundle: Product, count: int}> $counts */\n", // 7
+        "    public function handle(array $counts): void {\n",                        // 8
+        "        foreach ($counts as $entry) {\n",                                    // 9
+        "            $entry['bundle']->\n",                                           // 10
+        "        }\n",                                                                // 11
+        "    }\n",                                                                    // 12
+        "}\n",                                                                        // 13
+    );
+
+    let open_params = DidOpenTextDocumentParams {
+        text_document: TextDocumentItem {
+            uri: uri.clone(),
+            language_id: "php".to_string(),
+            version: 1,
+            text: text.to_string(),
+        },
+    };
+    backend.did_open(open_params).await;
+
+    // Cursor at line 10 after `$entry['bundle']->`
+    let completion_params = CompletionParams {
+        text_document_position: TextDocumentPositionParams {
+            text_document: TextDocumentIdentifier { uri },
+            position: Position {
+                line: 10,
+                character: 34,
+            },
+        },
+        work_done_progress_params: WorkDoneProgressParams::default(),
+        partial_result_params: PartialResultParams::default(),
+        context: None,
+    };
+
+    let result = backend.completion(completion_params).await.unwrap();
+    assert!(
+        result.is_some(),
+        "Completion should return results for $entry['bundle']-> inside foreach over array shape param"
+    );
+
+    match result.unwrap() {
+        CompletionResponse::Array(items) => {
+            let labels: Vec<&str> = items.iter().map(|i| i.label.as_str()).collect();
+            assert!(
+                labels.iter().any(|l| l.starts_with("sku")),
+                "Should include 'sku' from Product via array shape foreach. Got: {:?}",
+                labels
+            );
+            assert!(
+                labels.iter().any(|l| l.starts_with("parentProduct")),
+                "Should include 'parentProduct' from Product via array shape foreach. Got: {:?}",
+                labels
+            );
+        }
+        _ => panic!("Expected CompletionResponse::Array"),
+    }
+}