Laravel Navigation

Lightweight Ctrl+Hover preview + Ctrl+Click (Go to Definition) for Laravel projects in VS Code / Cursor.

No PHP process. No Artisan. No background indexing. No file watchers.
Work happens only when you hover, Ctrl+Click, or Find All References.

Screenshots

Hover preview card with brand (laravel-navigation 1.0.1) and a feedback link:

Table of contents

1. Why this extension
2. Install
3. Quick start
4. Hover card
5. Supported navigation (full list)
6. Behaviour details
7. Architecture
8. Performance / lightweight rules
9. Limitations
10. Develop locally
11. Project structure
12. Troubleshooting
13. Roadmap

1. Why this extension

Many Laravel helpers (view(), route(), config(), env(), …) are strings, not PHP symbols.
Intelephense / LSP often cannot jump to Blade, .env, or named routes reliably.

Heavy extensions (e.g. Laravel Extra Intellisense) boot your app via PHP in the background and can freeze the machine.

laravel-navigation solves navigation with:

• file conventions (app/Models, resources/views, routes/, …)
• composer.json + vendor/composer/autoload_psr4.php (for Illuminate\…)
• capped, cached disk reads

2. Install

From Marketplace (recommended)

1. Open Extensions (Ctrl+Shift+X / Cmd+Shift+X).
2. Search Laravel Navigation.
3. Install Laravel Navigation by Prakash Tank.

Or from the command line:

code --install-extension prakashtank.laravel-navigation
# or
cursor --install-extension prakashtank.laravel-navigation

After install: Ctrl+Shift+P → Developer: Reload Window.

From VSIX

cd /path/to/extension
npm install
npm run compile
npm run package

Then Extensions → ⋯ → Install from VSIX…, or:

cursor --install-extension laravel-navigation-1.0.1.vsix --force
# or
code --install-extension laravel-navigation-1.0.1.vsix --force

From source (Extension Development Host)

npm install
npm run compile

Press F5 → open a Laravel app in the new window.

Disable conflicting heavy tools

If the IDE hangs, disable Laravel Extra Intellisense (it spawns PHP against your app).

Keep PHP Intelephense for generic PHP / vendor IntelliSense; this extension focuses on Laravel string + convention navigation.

3. Quick start

1. Open a Laravel project (folder that contains artisan).
2. Open a PHP or Blade file.
3. Hover a supported symbol → preview card.
4. Ctrl+Click (or F12) → jump to target file / line.
5. On a named route: Shift+F12 → Find All References (capped scan).

4. Hover card

Each successful resolve shows a hover card:

Click the filename in the card → opens the target in a new editor tab at the right line.

5. Supported navigation (full list)

5.1 Models

5.2 Views / Blade

5.3 Config

Hover: shows resolved Value (literal, or value of env('…') inside that config line).

5.4 Env

Hover: shows Value: from .env.

5.5 Routes (named / reverse)

Find All References (Shift+F12) on a route name: finds usages in routes/, app/, resources/views/ (capped).

5.6 Controllers

5.7 Classes, services, traits, Illuminate

5.8 Laravel conventions

5.9 Methods on $this / typed variables

5.10 Eloquent relations

Supported relation helpers (parsed):
belongsTo, belongsToMany, hasOne, hasMany, hasManyThrough, hasOneThrough, morphTo, morphOne, morphMany, morphToMany, morphedByMany, …

5.11 Assets, Vite, translations

Locale is taken from config('app.locale') / fallback_locale when readable; otherwise en.

6. Behaviour details

Laravel root detection

Walks up from the current file (max depth 12) looking for:

1. artisan, or
2. composer.json + app/ + config/

Result is cached per directory.

use import expansion

Short names like MetaWebhookService are expanded via top-of-file use App\Services\MetaWebhookService; (first ~120 lines) before path resolve.

Env / config values

• .env parsed with size cap; comments / quotes handled simply.
• Config nested keys use bracket-scope walking so services.stripe.key does not match the wrong 'key'.
• If config value is env('X') or env('X', 'default'), hover shows the .env value (or default).

Route index

Scans routes/**/*.php (max 40 files), indexes ->name('…'), group name/prefix, and Route::resource / apiResource actions; caches by file mtimes.

7. Architecture

VS Code / Cursor
   │  Hover / Ctrl+Click / Find References
   ▼
extension.ts
   ├── DefinitionProvider
   ├── HoverProvider        (preview + value + feedback button)
   └── ReferenceProvider    (named routes only)
            │
            ▼
   detect/symbolDetector.ts   → kind + value (+ member)
            │
            ▼
   resolve/resolveSymbol.ts   → Location (+ displayValue)
            │
            ├── resolvers/*   (view, config, env, route, class, …)
            ├── laravel/psr4.ts, routeIndex.ts, project.ts
            └── utils/*       (cache, preview, fileFinder, phpHelpers)

Principle: detect cheaply on the current line → resolve with convention paths → only then optional capped reads.

8. Performance / lightweight rules

If the machine still hangs, check other extensions (Extra Intellisense, SonarLint) — not this one’s idle path.

9. Limitations

• Not a full PHP language server — complex type inference, generics, macros: use Intelephense.
• $obj->method() only when $obj type is clear nearby (param hint / @var / new).
• Relations need a real function posts() body with *Many(*::class) etc.; magic attributes without methods may miss.
• Config values that are multi-line arrays / complex expressions may not display a simple Value.
• Vendor resolve depends on vendor/ being installed (composer install).
• Find References is only for named routes (not every symbol).
• Env / config hover shows the live value from .env / config. Treat that as local-only; do not share screenshots that include secrets.

10. Develop locally

npm install
npm run compile    # tsc → out/
npm run watch      # optional
npm run package    # → laravel-navigation-1.0.1.vsix

Debug: F5 (launch config in .vscode/launch.json).

Requirements: Node 18+, VS Code / Cursor engines ^1.80.0.

11. Project structure

extension/
├── package.json
├── tsconfig.json
├── README.md                 ← this file
├── LICENSE
├── src/
│   ├── extension.ts          # activate providers + commands
│   ├── detect/
│   │   └── symbolDetector.ts
│   ├── resolve/
│   │   └── resolveSymbol.ts
│   ├── providers/
│   │   ├── definitionProvider.ts
│   │   ├── hoverProvider.ts
│   │   └── referenceProvider.ts
│   ├── resolvers/
│   │   ├── modelResolver.ts
│   │   ├── viewResolver.ts
│   │   ├── configResolver.ts
│   │   ├── envResolver.ts
│   │   ├── routeResolver.ts
│   │   ├── controllerResolver.ts
│   │   ├── classResolver.ts
│   │   ├── localMethodResolver.ts
│   │   ├── relationResolver.ts
│   │   └── assetLangResolver.ts
│   ├── laravel/
│   │   ├── project.ts        # find artisan root
│   │   ├── paths.ts
│   │   ├── psr4.ts           # app + vendor Illuminate
│   │   └── routeIndex.ts
│   └── utils/
│       ├── cache.ts          # LRU
│       ├── fileFinder.ts
│       ├── phpHelpers.ts
│       └── preview.ts
└── out/                      # compiled JS

12. Troubleshooting

13. Roadmap

Possible later (still lightweight):

• More Blade directives (@push, @error, …)
• Livewire / Volt component jump
• Policy method ↔ model ability mapping
• Optional mask for secret env values in hover