Laravel Maestro

Enterprise-grade Laravel intelligence for VS Code — zero helper files, instantaneous completions, visual Eloquent inspectors, and full PhpStorm-class IDE support for modern Laravel applications.

Features

⚡ Intelligent Auto-Import & Namespace Resolver

• Quick Fix Code Actions (Cmd+. / Ctrl+.) — instant lightbulb suggestions to import unimported models, enums, facades, resources, and services (Import 'App\Models\User') or expand inline (\App\Models\User).
• One-Click Import (Cmd+Alt+I / Ctrl+Alt+I) — instantly imports the class under cursor, with automatic disambiguation QuickPick if multiple matches exist.
• Batch Auto-Import All (Cmd+Alt+Shift+I / Ctrl+Alt+Shift+I) — scans the active PHP file and imports all missing class references in a single atomic pass.
• PSR-12 Alphabetical Sorting — automatically inserts new use statements alphabetically in the existing use block without creating duplicates.
• Same-Namespace & Scope Aware — intelligently ignores classes defined in the current file or within the same namespace.
• 38+ Official Laravel Facades — built-in knowledge of all official Laravel Facades (DB, Cache, Route, Auth, Log, Storage, Queue, Mail, Event, Schema, Http, etc.) and support classes (Str, Arr, Collection, Carbon, Rule).

🗄 Eloquent Visual Model Inspector & Schema Manager

• Visual Model Inspector (Model UI) — inspect table schema, columns, SQL types, and primary keys with a single click.
• Live Metric Badges — real-time header count chips for total columns, fillable fields, relationships, and active casts.
• Instant Column Facet Filters — one-click filter pills ([All], [Fillable], [Nullable], [Casts], [Keys]) for rapid column discovery.
• Interactive Fillable Manager — toggle fillable columns with checkboxes and sync directly to $fillable array or #[Fillable] PHP attribute (with Cmd+S shortcut).
• Attribute Casts Manager — configure and write model casts (boolean, datetime, decimal, json, AsArrayObject, AsEnumCollection, etc.) with dirty-state accents and live preview.
• Interactive Relationship Builder — generate relationship methods (hasOne, hasMany, belongsTo, belongsToMany, hasOneThrough, hasManyThrough, morphTo, morphOne, morphMany, morphToMany, morphedByMany) with real-time PHP code preview and automatic AST insertion.
• Direct Navigation Toolbar — instant jumps to Model PHP file, Factory, Policy, Migration, API Resource, and live Tinker Pad.

📦 Universal API Resource Generator (generateResource)

• Schema-Aware Attributes — automatically generates JsonResource classes with mapped $this->attribute fields.
• Eager-Load Safe Relations — detects model relationships and generates eager-load transformations (e.g. OrderResource::collection($this->whenLoaded('items')), new OrderResource($this->whenLoaded('order'))).
• Domain & Modular Architecture Support — automatically detects Domain-Driven Design structures (e.g. app/Domain/Sales/Models/...) and generates matching resources in app/Domain/Sales/Http/Resources/....
• Virtual Autocomplete Docblocks — automatically includes /** @mixin \App\Models\ModelName */ docblock for virtual property autocomplete.

🛣 Routing Intelligence & Route Explorer

• Interactive Route Explorer Webview — full filterable route table with method badges, URI parameters, middleware chips, and target actions.
• Static Call-Chain Fallback Parser — static AST parser supporting chained/array route groups (prefix, name, middleware, controller), Route::match, nested resources, and automatic /api prefix mounts when PHP runtime extraction is unavailable.
• Click-to-Filter Middleware — click any middleware badge in the route table to instantly filter to all routes using that middleware stack.
• Syntax-Highlighted Actions — color-distinguished controller and method targets (Controller cyan, @ gray, method gold).
• Universal PHP Class Resolver — instant jump to controller classes across custom workspace files, domain modules, and Composer vendor packages (Filament, Livewire, Sanctum, Horizon, Telescope, etc.).
• route()/to_route() completion — autocomplete all named routes with method badges, URI previews, and parameter info.
• Hover documentation — hover over any route string to see methods, action, middleware stack, and parameters.
• Go-to-Definition — Cmd+Click / Ctrl+Click on 'UserController@index' or a route name jumps to the exact file and line.
• CodeLens — ghost [GET /users] annotations above each controller method.
• Workspace-wide rename — rename a route name in one step; all usages updated atomically with single-undo.

🗄 Eloquent Virtualization

• where* magic methods — whereEmail(), whereNotActive(), etc. synthesized from live DB schema.
• Column property completions — $user->created_at, $user->is_active with type annotations.
• Relationship completions — $user->posts, $user->posts_count (when withCount applied).
• Scope completions — ::active(), ::withPendingOrders() from scopeActive() etc.
• Mass-assignment keys — User::create(['|'] shows all fillable fields with types.
• Variable-type inference — detects $user = User::find($id) and provides context-aware completions on $user->.
• Inlay hints — ghost type annotations on factory()->create([...]) array keys.

🧩 Blade & View Intelligence

• Directive completions — full @if, @foreach, @can, @vite, @class, etc. with snippet expansion.
• <x-component> completions — all components with props, required-prop snippet insertion.
• Component attribute completions — auto-complete <x-alert | with typed props from @props([...]).
• View name completions — @include, @extends, view() autocomplete from discovered views.
• Section name completions — @yield('|') and @push('|') aware of defined sections.
• Blade hover — hover over <x-alert> to see its class, file, and prop types.
• Embedded PHP highlighting — full syntax support inside @php/@if blocks.

⚙️ Config & i18n

• config('|') completion — all dot-notated keys with current values, supporting both root and subtree configuration keys.
• __('|') / trans('|') completion — all translation keys with value previews, preserving parent group prefixes for deeply nested language arrays (messages.auth.failed).
• i18n Quick Fix — select a raw string → "Extract to translation" → writes lang/en/messages.php and replaces the source.
• Config inlay hints — config('app.debug') /* bool */.

🧪 Real-time Laravel Tinker Pad

• Interactive Split Console — run PHP & Eloquent snippets in real-time right inside VS Code without switching to a terminal.
• Tinker Runtime Auto-Aliasing — built-in autoloader automatically resolves short model names (User::first()) and facades (DB::select(...), Schema::...) without needing manual use statements or FQNs.
• Curated High-Utility Snippets — instant snippets for model relations, schema column listings, DB connection, and cache operations.
• SQL Keyword Highlighting & Timing Badges — color-coded query durations (< 2ms green, 2ms - 15ms blue, > 15ms amber) and syntax-highlighted SQL logs.
• Non-Exiting dd() & dump() — dd(...) and dump(...) format output without terminating the PHP process early.
• Interactive Foldable Tree — expand or fold nested arrays, objects, Eloquent models, and collections (<details><summary>) with explicit Model class type indicators (e.g. App\Models\User).
• STDOUT & Timing Badges — view execution time in milliseconds, timestamps, and captured STDOUT streams.

🐳 Universal WSL & Docker Container Support (Sail, DDEV, Lando)

• Zero-Config Auto Detection — automatically detects and configures Laravel Sail, Docker Compose, DDEV, Lando, WSL UNC network paths (\\wsl$\..., \\wsl.localhost\...), or local PHP.
• Containerized Runtime Extractor — runs deep introspection (Eloquent schemas, config, gates, routes) inside your running containers using an in-project cache worker (storage/framework/cache/.maestro_extract.php).
• Direct Container Route Fallback — executes artisan route:list --json directly inside the container or WSL instance without requiring host PHP.
• Environment-Aware Integrated Terminal — running Artisan commands or database migrations automatically routes through ./vendor/bin/sail artisan, vendor\bin\sail.bat artisan, docker compose exec <service> php artisan, wsl php artisan, ddev artisan, or lando artisan.
• Container & WSL-Ready Tinker Pad — execute interactive PHP/Eloquent code snippets and inspect live queries inside your containers or WSL distributions.
• Windows 11 Resilience & Quoting — automatic resolution for Windows PHP installations (Laravel Herd, Scoop, Laragon, Chocolatey, XAMPP), safe quoted execution for paths with spaces in PowerShell and .bat/.cmd wrappers, cross-platform path normalization for Model ⇄ Migration navigation and Livewire components, and offline DB connection guards.

🏗 Interactive Code Generation

All generators use interactive QuickPick/InputBox flows — no terminal required.

🚀 Getting Started

Prerequisites

• VS Code ^1.90.0
• PHP ^8.1 in PATH (or configured via laravelMaestro.phpExecutable)
• A Laravel project with an artisan file in the workspace root

Installation

1. Install from the VS Code Marketplace: ext install laravel-maestro.laravel-maestro
2. Open your Laravel project folder.
3. The extension activates automatically when PHP/Blade files or artisan/composer.json are detected.
4. Watch the status bar for Maestro [12R · 5M] (routes · models).

First Run

The extension performs two indexing passes on activation:

1. Static AST pass (~2–5s): walks all *.php files (excluding vendor/), builds the symbol table.
2. Runtime pass (~3–8s): executes extract.php as a child process to get live routes, DB schema, and config.

⚙️ Configuration

📖 Developer & Technical Documentation

All deep technical, structural, and contribution guidelines are located in the docs/ directory:

• Architecture & Hybrid Indexing — In-depth details on the Static AST Parser, dynamic extractor, workspace contexts, and caching architecture.
• Development Setup Guide — Requirements, local compilation commands, debugging inside VS Code, testing suites, and packaging commands.
• PHP Worker Specification — Complete details on sandboxing, safe bootstrapping, database compatibility, execution constraints, and payload formats of the background PHP worker.
• Custom Helper Extensibility — Documenting how to configure an ide.json file in your project root to register custom helper completions.
• Extending the Extension — Guide on contributing, writing new completion providers, registering new commands, and following performance rules.

📝 Change Log

See CHANGELOG.md for full release history and release notes.

v1.3.0

• Windows Path & Quoting Resiliency: Normalizes path separators for migration ⇄ model navigation, CodeLens, and Livewire/Nova contexts; fixes nested Livewire view-to-component resolution (admin.users.table); quotes PHP paths containing spaces in PowerShell (& operator) and .bat/.cmd wrappers; and tolerates pasted quotes in phpExecutable.
• Eliminated False-Positive Diagnostics: Kebab-case and class-based Blade components, <x-slot>, <x-dynamic-component>, config() subtree keys, Route::view() URIs, and nested translation keys are no longer flagged as unknown.
• Static Call-Chain Route Parser: Comprehensive fallback parser resolves route group hierarchies (prefix, name, middleware, controller), leading attribute chains, Route::match, nested resources, and /api prefix mounts when PHP is unavailable.
• Route Parsing Fixes: Route::apiResource expands to real REST routes, ->only() and ->except() constraints are honored, and parameter names match model names (posts/{post}).
• Translation Indexing Enhancements: Preserves parent keys for nested language arrays (messages.auth.failed), indexes subfolder groups and legacy resources/lang/, and ignores vendor overrides.
• More Accurate Eloquent Indexing: Relationships with chained calls (->hasMany(...)->latest()) are detected, and deleted or renamed classes are cleanly purged from the index.
• Blade @props Fix: Distinguishes required vs. optional props with default values (including nested array defaults).
• Exclude Patterns: vendor/** no longer excludes vendors/, and **/dir/** patterns work across all indexers.
• Docker Tinker Guard: Accurately verifies that your specific Compose service is running, rather than any active container.
• Tooling & Engine: Requires VS Code ^1.90.0 (with @types/vscode ~1.100.0), upgrades toolchain to TypeScript 7 and ESLint 10, and expands test coverage to 322 passing tests (with CRLF and Windows regression suites).

v1.2.0

• Universal WSL & Container Architecture: Zero-config auto-detection for Laravel Sail, Docker Compose, DDEV, Lando, and WSL UNC paths (\\wsl$\..., \\wsl.localhost\...).
• Sandboxed Container Runtime Extraction: Extracts Eloquent schemas, routes, and config inside Docker containers via in-project cache workers (storage/framework/cache/.maestro_extract.php).
• Direct Container Route Fallback: Headless artisan route:list --json extraction executed directly inside running containers or WSL distros.
• Environment-Aware Terminal Runners: Integrated terminal runs Artisan and migrations automatically via ./vendor/bin/sail artisan, vendor\bin\sail.bat artisan, docker compose exec <service> php artisan, wsl php artisan, ddev artisan, or lando artisan.
• Container & WSL Tinker Pad: Real-time evaluation of PHP & Eloquent snippets inside containers and WSL with actionable diagnostics if containers are stopped.
• Windows 11 Route Explorer Resilience: Multi-path PHP discovery (Laravel Herd, Scoop, Laragon, Chocolatey, XAMPP), .bat/.cmd shell wrapper support, 2s DB connection timeout guards, output buffer isolation, and manual webview refresh.

v1.1.0

• Intelligent Auto-Import: QuickFix lightbulb actions, one-click Cmd+Alt+I, batch autoImportAll, PSR-12 sorting, and 38+ Laravel Facades.
• Tinker Pad Runtime Auto-Aliasing: Built-in autoloader resolving User::... and DB::... without manual imports, plus 10 curated snippets and SQL keyword highlighting.
• Eloquent Model Inspector UI/UX: Live metric chips, instant facet filters ([Fillable], [Nullable], [Keys]), dirty cast states, and Cmd+S shortcuts.
• Route Explorer UI/UX: Click-to-filter middleware badges, syntax-highlighted controller actions, and keyboard search hints.
• Critical Audit Fixes: Resolved controller action casing corruption, Tinker Pad premature process exits, and duplicate Blade component edits.

v1.0.0

• Eloquent Model Visual Inspector (Model UI): Schema viewer, fillables, casts, and relationship generator.
• Universal API Resource Generator: Schema-aware attribute mapping, eager-loaded relationships, and navigation.
• Route Explorer Webview: Interactive route table with method filtering, search, and vendor class navigation.
• Zero-Disk Tinker Pad: Real-time scratchpad console with non-exiting dd() and dump().
• Laravel 13 AI & PHP Enums: Scaffolding for AI agents/tools and full enum completions.
• Modern Vector UI/UX: Replaced all emojis with crisp VS Code Codicons and SVGs.

📄 License

Proprietary / Commercial License © Laravel Maestro. All rights reserved. Please refer to LICENSE.md for full terms and conditions.