Inject $loop variable in foreach and forelse blocks

Author: AJenbo

docs/todo/blade.md

@@ -60,22 +60,6 @@ of the file rather than inside a `@php` / `<?php` block. All code
 actions that produce text edits need their ranges translated, and
 actions that generate new code need to be aware of Blade structure.
 
-Remaining work in this phase:
-
-### `$loop` variable injection
-
-The preprocessor injects `$errors` and `$__env` in the prologue, but
-does not yet inject a `$loop` variable inside `@foreach` blocks:
-
-```php
-/** @var object{index: int, iteration: int, remaining: int, count: int, first: bool, last: bool, even: bool, odd: bool, depth: int, parent: ?object} $loop */
-$loop = (object)[];
-```
-
-### Additional test coverage
-
-- `$loop->` inside a `@foreach` (blocked on `$loop` variable injection)
-
 ---
 
 ## Phase 2: Component Support

src/blade/preprocessor.rs

@@ -162,11 +162,13 @@ pub fn preprocess(content: &str) -> (String, BladeSourceMap) {
                                 replacement = " if (true): ".to_string();
                                 next_mode = Mode::Html;
                             }
+                        } else if matches!(directive, "foreach" | "forelse") {
+                            replacement = format!(" {} ", translate_directive(directive));
+                            next_mode = Mode::DirectiveArgs(": /** @var object{index: int, iteration: int, remaining: int, count: int, first: bool, last: bool, even: bool, odd: bool, depth: int, parent: ?object} $loop */ $loop = (object)[];");
+                            paren_depth = 0;
                         } else if matches!(
                             directive,
                             "if" | "elseif"
-                                | "foreach"
-                                | "forelse"
                                 | "for"
                                 | "while"
                                 | "switch"
@@ -446,6 +448,29 @@ mod tests {
         );
     }
 
+    #[test]
+    fn test_preprocess_foreach_loop_variable() {
+        let content = "@foreach($items as $item)\n{{ $loop->first }}\n@endforeach\n";
+        let (php, _) = preprocess(content);
+        assert!(php.contains("$loop"), "should inject $loop variable: {}", php);
+        assert!(
+            php.contains("object{index: int"),
+            "should have typed $loop: {}",
+            php
+        );
+        // $loop should be declared before its usage
+        let loop_decl = php.find("$loop = (object)[];").unwrap();
+        let loop_use = php.rfind("$loop").unwrap();
+        assert!(loop_use > loop_decl, "$loop usage after declaration: {}", php);
+    }
+
+    #[test]
+    fn test_preprocess_forelse_loop_variable() {
+        let content = "@forelse($items as $item)\n{{ $loop->index }}\n@empty\n@endforelse\n";
+        let (php, _) = preprocess(content);
+        assert!(php.contains("$loop = (object)[];"), "forelse should also inject $loop: {}", php);
+    }
+
     #[test]
     fn test_preprocess_echo_with_string_braces() {
         let content = "{{ \"}} \" }}";