Add Blade foreach variable resolution for standalone @var docblocks

Author: AJenbo

docs/CHANGELOG.md

@@ -17,6 +17,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **Blade hover positions.** Hover ranges in `.blade.php` files are now translated back to original Blade coordinates, so the editor highlights the correct symbol under the cursor.
 - **Standalone `@var` completion.** Variables typed only via a standalone `/** @var Type $var */` docblock (with no preceding assignment) now resolve for member completion and go-to-definition. This fixes completion inside Blade templates that use `@php /** @var \App\Models\Foo $var */ @endphp`.
+- **Foreach loop variable resolution in Blade.** Loop variables (e.g. `$user` in `@foreach($users->active() as $user)`) now resolve their element type correctly when the iterable is typed via a standalone `@var` docblock. Template parameter bounds (e.g. `@template TModel of BlogAuthor`) are substituted through the inheritance chain.
 
 ### Changed
 

docs/todo/bugs.md

@@ -8,6 +8,16 @@ pipeline so it produces correct data. Downstream consumers
 to second-guess upstream output.
 
 
+## B17. Blade `{{` hover shows inner expression instead of `e()`
+
+Hovering on the `{{` delimiter in a Blade template should show
+hover info for the implicit `e()` (htmlspecialchars) call that
+Blade compiles to. Currently it shows hover for the expression
+inside the echo (e.g. `config(...)`) because the position mapping
+offsets into the virtual PHP content rather than recognising the
+delimiter itself.
+
+
 ## B16. PDOStatement fetch mode-dependent return types
 
 **Blocked on:** [phpstorm-stubs#1882](https://github.com/JetBrains/phpstorm-stubs/pull/1882)

examples/laravel/resources/views/emails/order_shipped.blade.php

@@ -0,0 +1,16 @@
+{{-- Demonstrates variable completion inside included partials --}}
+@php
+/**
+ * @bladestan-signature
+ * @var ?\App\Models\BlogPost $post
+ */
+@endphp
+
+<div style="font-family: sans-serif; padding: 20px;">
+    <h2>{{ __('messages.welcome') }}</h2>
+
+    @if($post)
+        <p>{{ $post->getTitle() }} has been published!</p>
+        <p>Published: {{ $post->created_at->diffForHumans() }}</p>
+    @endif
+</div>

examples/laravel/resources/views/welcome.blade.php

@@ -19,7 +19,6 @@
     @if($user)
         <p>Hello, {{ $user->name }}!</p>
         <p>Email: {{ $user->email }}</p>
-        <p>Status: {{ $user->status->label() }}</p>
     @endif
 
     {{-- Foreach with model completion — $posts->byNewest() uses PostCollection --}}
@@ -38,7 +37,7 @@
     </nav>
 
     {{-- Includes and nested views --}}
-    @include('emails.order_shipped', ['order' => $order ?? null])
+    @include('emails.order_shipped', ['post' => $posts->first()])
 
     {{-- Conditional rendering with config --}}
     @if(config('app.debug'))

src/blade/preprocessor.rs

@@ -377,6 +377,25 @@ mod tests {
         );
     }
 
+    #[test]
+    fn test_preprocess_foreach() {
+        let content = r#"@php
+/**
+ * @var \App\Models\AuthorCollection $users
+ */
+@endphp
+
+@foreach($users->active()->byName() as $user)
+    <p>{{ $user->name }}</p>
+@endforeach
+"#;
+        let (php, _) = preprocess(content);
+        for (i, line) in php.lines().enumerate() {
+            eprintln!("{:2}: {}", i, line);
+        }
+        assert!(php.contains("$user->name"));
+    }
+
     #[test]
     fn test_preprocess_multiline_directive() {
         let content = "@include('vendor.fbRemarket', [\n    'facebook_pixel_id' => Config::get('services.facebook.pixel_id'),\n])\n\n@include('vendor.googleRemarket')";

src/completion/variable/forward_walk.rs

@@ -6115,6 +6115,55 @@ fn process_foreach<'b>(foreach: &'b Foreach<'b>, scope: &mut ScopeState, ctx: &F
         return;
     }
 
+    // Apply any standalone `/** @var Type $var */` docblocks that precede
+    // the foreach keyword.  These are not separate AST statements (the
+    // parser attaches them as comments to the foreach), so they won't be
+    // processed by `process_expression_statement`.  Without this, variables
+    // typed only via docblock (common in Blade templates) won't be in scope
+    // when the iterable expression is resolved.
+    //
+    // We extract all variables referenced in the foreach expression and
+    // check for @var annotations for each one.
+    let foreach_offset = foreach.foreach.span().start.offset as usize;
+    if let Expression::Variable(Variable::Direct(dv)) = foreach.expression {
+        let var_name = format!("${}", dv.name);
+        if scope.get(dv.name).is_empty()
+            && let Some(var_type) =
+                crate::docblock::find_var_raw_type_in_source(ctx.content, foreach_offset, &var_name)
+        {
+            let resolved = resolve_type_to_resolved_types(
+                &crate::util::resolve_php_type_names(&var_type, ctx.class_loader),
+                ctx,
+            );
+            scope.set(dv.name, resolved);
+        }
+    } else {
+        // For complex expressions like `$users->active()->byName()`,
+        // extract the base variable and resolve its type from @var.
+        let expr_start = foreach.expression.span().start.offset as usize;
+        let expr_end = foreach.expression.span().end.offset as usize;
+        if let Some(expr_text) = ctx.content.get(expr_start..expr_end) {
+            // Extract the base variable (e.g. "$users" from "$users->active()->byName()")
+            if let Some(base_end) = expr_text.find("->").or_else(|| expr_text.find("::")) {
+                let base_var = expr_text[..base_end].trim();
+                if let Some(scope_key) = base_var.strip_prefix('$')
+                    && scope.get(scope_key).is_empty()
+                    && let Some(var_type) = crate::docblock::find_var_raw_type_in_source(
+                        ctx.content,
+                        foreach_offset,
+                        base_var,
+                    )
+                {
+                    let resolved = resolve_type_to_resolved_types(
+                        &crate::util::resolve_php_type_names(&var_type, ctx.class_loader),
+                        ctx,
+                    );
+                    scope.set(scope_key, resolved);
+                }
+            }
+        }
+    }
+
     // Resolve the iterable expression's type.
     let iter_type = resolve_foreach_iterable_type(foreach, scope, ctx);
 
@@ -6514,13 +6563,6 @@ fn bind_foreach_value<'b>(
             }
 
             // Strategy 2: class-based fallback for bare collection names.
-            // Resolve the iterable type to ClassInfo, merge inheritance,
-            // and extract the element type from @extends/@implements generics.
-            // Skip when the extracted element type is an unsubstituted
-            // template parameter (e.g. `TValue` from `ArrayObject<TKey, TValue>`)
-            // — binding it would produce incorrect scope entries that
-            // override the backward scanner's correct resolution via
-            // inline `/** @var */` docblocks.
             let element_via_class = resolve_iterable_element_via_class(it, ctx);
             if let Some(element_type) = element_via_class
                 && !is_unsubstituted_template_param(&element_type)
@@ -6802,7 +6844,19 @@ fn resolve_iterable_element_via_class(
             &merged,
             ctx.class_loader,
         );
-        if element_type.is_some() {
+        if let Some(ref et) = element_type {
+            // When the extracted type is an unsubstituted template parameter
+            // (e.g. `TModel`), resolve it through the class's template bounds
+            // (e.g. `@template TModel of BlogAuthor` → `BlogAuthor`).
+            if let Some(name) = et.base_name()
+                && merged
+                    .template_params
+                    .iter()
+                    .any(|p| p.as_ref() as &str == name)
+                && let Some(bound) = merged.template_param_bounds.get(&crate::atom::atom(name))
+            {
+                return Some(bound.clone());
+            }
             return element_type;
         }
     }