Fix false-positive unused $loop in Blade and update Laravel demos

Author: AJenbo

docs/CHANGELOG.md

@@ -39,9 +39,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **`array_reduce`, `array_sum`, and `array_product` return type inference.** `array_reduce()` resolves to the type of its initial value argument. `array_sum()` and `array_product()` resolve to `int|float`.
 - **Machine-readable CLI output.** Both `analyze` and `fix` accept a `--format` flag with `table`, `github`, and `json` options. When `GITHUB_ACTIONS` is set, table output automatically includes GitHub annotations.
 - **Magic property diagnostics.** New `report-magic-properties` option under `[diagnostics]` in `.phpantom.toml`. When enabled, classes with `__get` that also have virtual properties (from `@property` docblock tags, Laravel Eloquent column inference, or other providers) will flag unknown property access instead of silently allowing it.
+- **Inline diagnostic suppression.** `// @phpantom-ignore code` on the same line or the line above suppresses the specified diagnostic. Multiple codes can be comma-separated. A bare `// @phpantom-ignore` suppresses all diagnostics on the target line.
 
 ### Changed
 
+- **Replace FQCN with import.** Now replaces all occurrences of the same FQCN throughout the file in one action, not just the one under the cursor. A new "Replace all FQCNs with imports" action appears when the file contains multiple distinct FQCNs, replacing all of them at once (skipping those with import conflicts).
 - **LSP responsiveness.** Hover, go-to-definition, signature help, code actions, rename, and other handlers now run on background threads. Slow requests no longer block other requests or cancellations.
 - **Faster analysis.** Analysis time cut significantly on large projects.
 - **Editing responsiveness.** Classes evicted from the cache after a file edit are now eagerly re-populated in dependency order.
@@ -55,6 +57,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **Blade diagnostics in `analyze` command.** Blade template files now receive full diagnostics (unknown members, unknown classes, unused variables, etc.) when running `phpantom_lsp analyze`.
 - **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.
+- **False-positive unused `$loop` in Blade templates.** The `$loop` variable injected by `@foreach`/`@forelse` is no longer flagged as unused when the template body doesn't reference it.
 - **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,14 +21,3 @@ 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/app/Models/AuthorCollection.php

@@ -2,12 +2,14 @@
 
 namespace App\Models;
 
+use Illuminate\Database\Eloquent\Collection;
+
 /**
  * @template TKey of array-key
  * @template TModel of BlogAuthor
- * @extends \Illuminate\Database\Eloquent\Collection<TKey, TModel>
+ * @extends Collection<TKey, TModel>
  */
-class AuthorCollection extends \Illuminate\Database\Eloquent\Collection
+class AuthorCollection extends Collection
 {
     /** @return static */
     public function active(): static { return $this->filter(fn($a) => $a->active); }

examples/laravel/app/Models/Bakery.php

@@ -3,8 +3,12 @@
 namespace App\Models;
 
 use Illuminate\Database\Eloquent\Attributes\Scope;
+use Illuminate\Database\Eloquent\Builder;
 use Illuminate\Database\Eloquent\Casts\Attribute;
 use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsToMany;
+use Illuminate\Database\Eloquent\Relations\HasMany;
+use Illuminate\Database\Eloquent\Relations\HasOne;
 
 class Bakery extends Model
 {
@@ -42,29 +46,29 @@ protected function casts(): array
         'gluten_free' => false,
     ];
 
-    /** @return \Illuminate\Database\Eloquent\Relations\HasMany<Loaf, $this> */
+    /** @return HasMany<Loaf, $this> */
     public function baguettes(): mixed { return $this->hasMany(Loaf::class); }
 
-    /** @return \Illuminate\Database\Eloquent\Relations\HasOne<Baker, $this> */
+    /** @return HasOne<Baker, $this> */
     public function headBaker(): mixed { return $this->hasOne(Baker::class); }
 
-    /** @return \Illuminate\Database\Eloquent\Relations\BelongsToMany<BakeryRecipe, $this> */
+    /** @return BelongsToMany<BakeryRecipe, $this> */
     public function masterRecipe(): mixed { return $this->belongsToMany(BakeryRecipe::class); }
 
     public function vendor() { return $this->morphTo(); }
 
-    public function scopeTopping(\Illuminate\Database\Eloquent\Builder $query, string $type): void
+    public function scopeTopping(Builder $query, string $type): void
     {
         $query->where('topping', $type);
     }
 
-    public function scopeUnbaked(\Illuminate\Database\Eloquent\Builder $query): void
+    public function scopeUnbaked(Builder $query): void
     {
         $query->where('baked', false);
     }
 
     #[Scope]
-    protected function freshlyBaked(\Illuminate\Database\Eloquent\Builder $query): void
+    protected function freshlyBaked(Builder $query): void
     {
         $query->where('fresh', true);
     }

examples/laravel/app/Models/BlogAuthor.php

@@ -3,34 +3,41 @@
 namespace App\Models;
 
 use Illuminate\Database\Eloquent\Attributes\CollectedBy;
+use Illuminate\Database\Eloquent\Builder;
 use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\HasMany;
+use Illuminate\Database\Eloquent\Relations\HasOne;
 
 #[CollectedBy(AuthorCollection::class)]
 
 /**
- * @method static \Illuminate\Database\Eloquent\Builder<static> withTrashed(bool $withTrashed = true)
- * @method static \Illuminate\Database\Eloquent\Builder<static> onlyTrashed()
+ * @method static Builder<static> withTrashed(bool $withTrashed = true)
+ * @method static Builder<static> onlyTrashed()
  */
 class BlogAuthor extends Model
 {
     protected $fillable = ['name', 'email', 'genre'];
 
+    protected $casts = [
+        'active' => 'bool',
+    ];
+
     protected $guarded = ['id'];
 
     protected $hidden = ['password'];
 
-    /** @return \Illuminate\Database\Eloquent\Relations\HasMany<BlogPost, $this> */
+    /** @return HasMany<BlogPost, $this> */
     public function posts(): mixed { return $this->hasMany(BlogPost::class); }
 
-    /** @return \Illuminate\Database\Eloquent\Relations\HasOne<AuthorProfile, $this> */
+    /** @return HasOne<AuthorProfile, $this> */
     public function profile(): mixed { return $this->hasOne(AuthorProfile::class); }
 
-    public function scopeActive(\Illuminate\Database\Eloquent\Builder $query): void
+    public function scopeActive(Builder $query): void
     {
         $query->where('active', true);
     }
 
-    public function scopeOfGenre(\Illuminate\Database\Eloquent\Builder $query, string $genre): void
+    public function scopeOfGenre(Builder $query, string $genre): void
     {
         $query->where('genre', $genre);
     }

examples/laravel/app/Models/BlogPost.php

@@ -4,13 +4,20 @@
 
 use Illuminate\Database\Eloquent\Attributes\CollectedBy;
 use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
 
 #[CollectedBy(PostCollection::class)]
 class BlogPost extends Model
 {
-    public function getTitle(): string { return ''; }
-    public function getSlug(): string { return ''; }
+    protected $fillable = ['title', 'slug'];
 
-    /** @return \Illuminate\Database\Eloquent\Relations\BelongsTo<BlogAuthor, covariant $this> */
+    protected $casts = [
+        'published' => 'bool',
+    ];
+
+    public function getTitle(): string { return $this->title; }
+    public function getSlug(): string { return $this->slug; }
+
+    /** @return BelongsTo<BlogAuthor, covariant $this> */
     public function author(): mixed { return $this->belongsTo(BlogAuthor::class); }
 }

examples/laravel/app/Models/PostCollection.php

@@ -2,12 +2,14 @@
 
 namespace App\Models;
 
+use Illuminate\Database\Eloquent\Collection;
+
 /**
  * @template TKey of array-key
  * @template TModel of BlogPost
- * @extends \Illuminate\Database\Eloquent\Collection<TKey, TModel>
+ * @extends Collection<TKey, TModel>
  */
-class PostCollection extends \Illuminate\Database\Eloquent\Collection
+class PostCollection extends Collection
 {
     /** @return static */
     public function published(): static { return $this->filter(fn($p) => $p->published); }

examples/laravel/app/Models/Review.php

@@ -4,13 +4,14 @@
 
 use Illuminate\Database\Eloquent\Attributes\CollectedBy;
 use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\HasMany;
 
 #[CollectedBy(ReviewCollection::class)]
 class Review extends Model
 {
     public function getTitle(): string { return ''; }
     public function getRating(): int { return 0; }
 
-    /** @return \Illuminate\Database\Eloquent\Relations\HasMany<Review, $this> */
+    /** @return HasMany<Review, $this> */
     public function replies(): mixed { return $this->hasMany(Review::class); }
 }

examples/laravel/app/Models/ReviewCollection.php

@@ -2,12 +2,14 @@
 
 namespace App\Models;
 
+use Illuminate\Database\Eloquent\Collection;
+
 /**
  * @template TKey of array-key
  * @template TModel
- * @extends \Illuminate\Database\Eloquent\Collection<TKey, TModel>
+ * @extends Collection<TKey, TModel>
  */
-class ReviewCollection extends \Illuminate\Database\Eloquent\Collection
+class ReviewCollection extends Collection
 {
     /** @return array<TKey, TModel> */
     public function topRated(): array { return []; }

src/analyse.rs

@@ -306,7 +306,7 @@ pub async fn run(options: AnalyseOptions) -> i32 {
                         if i >= file_count {
                             break;
                         }
-                        let (uri, content) = match &file_data[i] {
+                        let (uri, original_content) = match &file_data[i] {
                             Some(pair) => (&pair.0, &pair.1),
                             None => continue, // file that failed to read
                         };
@@ -321,10 +321,10 @@ pub async fn run(options: AnalyseOptions) -> i32 {
                                 blade_content = vc.clone();
                                 &blade_content
                             } else {
-                                content
+                                original_content
                             }
                         } else {
-                            content
+                            original_content
                         };
 
                         // Activate ONE parse cache for the entire file so
@@ -495,6 +495,12 @@ pub async fn run(options: AnalyseOptions) -> i32 {
                             }
                         }
 
+                        // ── Apply @phpantom-ignore comment suppression ─────
+                        // Use original_content (not virtual PHP) because
+                        // diagnostic line numbers have already been translated
+                        // back to original file coordinates.
+                        crate::diagnostics::filter_ignored_by_comment(&mut raw, original_content);
+
                         // For Blade files, translate diagnostic ranges from
                         // virtual PHP coordinates back to original Blade
                         // coordinates so line numbers match the source file.