Add Blade diagnostics and improve template intelligence

Author: AJenbo

docs/CHANGELOG.md

@@ -52,6 +52,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **Blade diagnostics in `analyze` command.** Blade template files now receive full diagnostics (unknown members, unknown classes, unused variables, etc.) when running `phpantom_lsp analyze`. Previously, the analyzer passed raw Blade template content to diagnostic collectors instead of the preprocessed virtual PHP, so no diagnostics were produced.
+- **Blade unknown-member diagnostic positions.** Unknown-member diagnostics in Blade files now point to the correct line in the original template instead of the virtual PHP line number.
 - **Spurious function auto-imports.** Import statements like `use function is_array;` were misidentified as function declarations, polluting the completion list with phantom entries that inserted incorrect imports.
 - **Duplicate `use function` insertion.** Accepting a function completion no longer inserts a `use function` statement when the exact import already exists in the file.
 - **Function import conflict handling.** When a different function with the same short name is already imported, completing a namespaced function now inserts the fully-qualified name instead of the ambiguous short name.

docs/todo/bugs.md

@@ -21,3 +21,14 @@ handle this automatically.
 **Tests:** Assertion lines were removed from
 `tests/psalm_assertions/method_call.php` (out of scope until
 upstream stubs land).
+
+
+## B17. Blade `$loop` variable triggers unused-variable false positive
+
+The Blade preprocessor injects `$loop = new \stdClass();` inside
+`@foreach` / `@forelse` blocks to provide completion for the magic
+`$loop` variable. When the template does not actually reference
+`$loop`, the unused-variable diagnostic flags it. The injected
+assignment should either be suppressed from unused-variable checks
+(e.g. by marking it as a synthetic definition) or the preprocessor
+should only inject it when `$loop` is actually used in the block.

examples/laravel/README.md

@@ -10,6 +10,7 @@ features against a real Laravel installation.
 - **View navigation.** Go-to-definition for `view('welcome')` and `View::make('admin.users.index')` (resolves to Blade templates in `resources/views/`).
 - **Route navigation.** Go-to-definition for `route('home')` (resolves to `->name('home')` in route files).
 - **Translation navigation.** Go-to-definition for `__('messages.welcome')`, `trans('auth.failed')`, and `trans_choice(...)` (resolves to `lang/` PHP files).
+- **Blade template intelligence.** Variable completion and hover in `{{ }}` expressions (shown as `e()` calls), go-to-definition on `@include`/`@extends` view references, `@forelse`/`@empty` directives, implicit `$loop` variable in `@foreach`/`@forelse`, implicit `$message` in `@error`, implicit `$value` in `@session`, `@verbatim` block handling, and standalone `@var` docblocks for type narrowing.
 
 ## Getting started
 

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

@@ -21,27 +21,57 @@
         <p>Email: {{ $user->email }}</p>
     @endif
 
-    {{-- Foreach with model completion — $posts->byNewest() uses PostCollection --}}
-    @foreach($posts->byNewest() as $post)
+    {{-- @error injects an implicit $message variable --}}
+    @error('email')
+        <div class="alert">{{ $message }}</div>
+    @enderror
+
+    {{-- @session injects an implicit $value variable --}}
+    @session('status')
+        <div class="success">{{ $value }}</div>
+    @endsession
+
+    {{-- @forelse with @empty — supported since recently --}}
+    @forelse($posts->published()->byNewest() as $post)
+        {{-- Standalone @var docblock for type narrowing in foreach --}}
+        @php /** @var \App\Models\BlogPost $post */ @endphp
         <article>
-            <h2>{{ $post->title }}</h2>
+            <h2>{{ $post->getTitle() }}</h2>
             <p>By {{ $post->author->name }}</p>
             <span>{{ $post->created_at->diffForHumans() }}</span>
+
+            {{-- $loop variable is injected automatically in foreach/forelse --}}
+            @if($loop->first)
+                <span class="badge">Featured</span>
+            @endif
+            @if(!$loop->last)
+                <hr>
+            @endif
         </article>
-    @endforeach
+    @empty
+        <p>No posts found.</p>
+    @endforelse
 
-    {{-- Route and translation helpers --}}
+    {{-- Route and translation helpers (Ctrl+Click navigates to definition) --}}
     <nav>
+        {{-- Go-to-definition works on view references in @include, @extends --}}
         <a href="{{ route('home') }}">{{ __('messages.welcome') }}</a>
         <a href="{{ route('admin.users.index') }}">{{ trans('auth.failed') }}</a>
     </nav>
 
-    {{-- Includes and nested views --}}
+    {{-- @include: Ctrl+Click navigates to the included view --}}
     @include('emails.order_shipped', ['post' => $posts->first()])
 
+    {{-- @verbatim: content inside is skipped by the preprocessor --}}
+    @verbatim
+        <p>This {{ $blade }} syntax is not processed</p>
+    @endverbatim
+
     {{-- Conditional rendering with config --}}
     @if(config('app.debug'))
         <pre>Debug mode is on (env: {{ config('app.env') }})</pre>
     @endif
+
+    @yield('content')
 </body>
 </html>

src/analyse.rs

@@ -311,6 +311,22 @@ pub async fn run(options: AnalyseOptions) -> i32 {
                             None => continue, // file that failed to read
                         };
 
+                        // For Blade files, use the preprocessed virtual PHP
+                        // content instead of the raw Blade template.  The
+                        // virtual content was produced by `update_ast` in
+                        // Phase 1 and stored in `blade_virtual_content`.
+                        let blade_content;
+                        let content = if crate::blade::is_blade_file(uri) {
+                            if let Some(vc) = backend.blade_virtual_content.read().get(uri.as_str()) {
+                                blade_content = vc.clone();
+                                &blade_content
+                            } else {
+                                content
+                            }
+                        } else {
+                            content
+                        };
+
                         // Activate ONE parse cache for the entire file so
                         // all collectors share the same parsed AST.  Each
                         // collector's own `with_parse_cache` call becomes
@@ -479,6 +495,16 @@ pub async fn run(options: AnalyseOptions) -> i32 {
                             }
                         }
 
+                        // For Blade files, translate diagnostic ranges from
+                        // virtual PHP coordinates back to original Blade
+                        // coordinates so line numbers match the source file.
+                        let is_blade = crate::blade::is_blade_file(uri);
+                        let source_map = if is_blade {
+                            backend.blade_source_maps.read().get(uri.as_str()).cloned()
+                        } else {
+                            None
+                        };
+
                         let mut filtered: Vec<FileDiagnostic> = raw
                             .into_iter()
                             .filter_map(|d| {
@@ -490,8 +516,13 @@ pub async fn run(options: AnalyseOptions) -> i32 {
                                     Some(NumberOrString::String(s)) => Some(s.clone()),
                                     _ => None,
                                 };
+                                let line = if let Some(ref map) = source_map {
+                                    map.php_to_blade(d.range.start).line + 1
+                                } else {
+                                    d.range.start.line + 1
+                                };
                                 Some(FileDiagnostic {
-                                    line: d.range.start.line + 1,
+                                    line,
                                     message: d.message,
                                     identifier,
                                     severity: sev,

src/blade/mod.rs

@@ -5,8 +5,8 @@ pub mod source_map;
 use std::path::{Path, PathBuf};
 
 /// Number of lines the Blade preprocessor injects as a prologue
-/// (<?php header, $errors declaration, $__env declaration, etc.).
-pub const PROLOGUE_LINES: u32 = 5;
+/// (<?php header, $errors declaration, $__env declaration, wrapper function, etc.).
+pub const PROLOGUE_LINES: u32 = 6;
 
 /// Check whether a URI refers to a Blade template file.
 pub fn is_blade_file(uri: &str) -> bool {

src/blade/preprocessor.rs

@@ -20,6 +20,11 @@ pub fn preprocess(content: &str) -> (String, BladeSourceMap) {
     virtual_php.push_str("$errors = new \\Illuminate\\Support\\ViewErrorBag();\n");
     virtual_php.push_str("/** @var \\Illuminate\\View\\Factory $__env */\n");
     virtual_php.push_str("$__env = new \\Illuminate\\View\\Factory();\n");
+    // Wrap the template body in a function so that diagnostic
+    // collectors (which only analyse function/method bodies) treat
+    // the Blade content as analysable code.  The closing brace is
+    // appended after the main loop.
+    virtual_php.push_str("function __blade_template() {\n");
 
     let mut in_php_directive_block = false;
     let mut mode = Mode::Html;
@@ -385,6 +390,9 @@ pub fn preprocess(content: &str) -> (String, BladeSourceMap) {
         source_map.adjustments.push(adjustments);
     }
 
+    // Close the wrapper function.
+    virtual_php.push_str("}\n");
+
     (virtual_php, source_map)
 }
 

src/diagnostics/mod.rs

@@ -2711,7 +2711,7 @@ mod tests {
         let content = "Hello World";
         backend.update_ast(uri, content);
 
-        // First 5 lines are prologue.
+        // First 6 lines are prologue (including wrapper function declaration).
         let virtual_php = {
             let vc_handle = backend.blade_virtual_content.read();
             vc_handle
@@ -2720,11 +2720,11 @@ mod tests {
                 .expect("Virtual content should exist")
         };
 
-        // Find start of line 4 (0-indexed).
+        // Find start of line 5 (0-indexed).
         let mut offset = 0;
         let mut lines_seen = 0;
         for (i, ch) in virtual_php.char_indices() {
-            if lines_seen == 4 {
+            if lines_seen == 5 {
                 offset = i;
                 break;
             }
@@ -2737,11 +2737,11 @@ mod tests {
         let range = backend.offset_range_to_lsp_range(uri, content, offset, offset + 5);
         assert!(range.is_none(), "Diagnostic in prologue should be ignored");
 
-        // byte range after prologue (line 5+)
+        // byte range after prologue (line 6+)
         let mut after_offset = 0;
         let mut lines_seen = 0;
         for (i, ch) in virtual_php.char_indices() {
-            if lines_seen == 5 {
+            if lines_seen == 6 {
                 after_offset = i;
                 break;
             }

src/diagnostics/unknown_members/mod.rs

@@ -89,7 +89,6 @@ use crate::types::{AccessKind, ClassInfo, ClassLikeKind};
 use crate::virtual_members::resolve_class_fully_cached;
 
 use super::helpers::{compute_existence_guards, find_innermost_enclosing_class, make_diagnostic};
-use super::offset_range_to_lsp_range;
 
 /// Diagnostic code used for unknown-member diagnostics so that code
 /// actions can match on it.
@@ -554,6 +553,7 @@ impl Backend {
 
                 SubjectOutcome::Resolved(ref base_classes) => {
                     let (result, coarse_diags) = self.check_member_on_resolved_classes(
+                        uri,
                         base_classes,
                         member_name,
                         is_static,
@@ -591,6 +591,7 @@ impl Backend {
                             if let SubjectOutcome::Resolved(ref fresh_classes) = fresh {
                                 // Use the fresh diagnostics instead of the coarse ones.
                                 self.check_member_on_resolved_classes(
+                                    uri,
                                     fresh_classes,
                                     member_name,
                                     is_static,
@@ -642,6 +643,7 @@ impl Backend {
     #[allow(clippy::too_many_arguments)]
     fn check_member_on_resolved_classes(
         &self,
+        uri: &str,
         base_classes: &[Arc<ClassInfo>],
         member_name: &str,
         is_static: bool,
@@ -754,7 +756,8 @@ impl Backend {
         }
 
         // ── Member is unresolved on ALL branches — emit diagnostic ──
-        let range = match offset_range_to_lsp_range(content, start as usize, end as usize) {
+        let range = match self.offset_range_to_lsp_range(uri, content, start as usize, end as usize)
+        {
             Some(r) => r,
             None => return (MemberCheckResult::Ok, diagnostics),
         };