Laravel Import Grouper

A powerful VS Code extension that automatically groups and organizes Laravel/PHP import statements for cleaner, more maintainable code.

✨ Features

• 🔄 Auto-grouping: Automatically groups imports from the same namespace
• 💾 Auto-save integration: Groups imports when you save PHP files (configurable)
• 👁️ Preview mode: See changes before applying them
• 📊 Status bar indicator: Shows when imports can be grouped
• 🎨 Smart sorting: Prioritizes Laravel/Illuminate imports
• 🏷️ Alias support: Handles as aliases correctly
• 💡 Lightbulb hints: Click the 💡 on any groupable import — no command palette needed
• 📐 PSR-12 separator: Blank line between vendor and App imports automatically
• 📋 Import statistics: See a summary of your imports at a glance
• 🔖 Laravel version filter: Only activates on projects that meet minimum version
• ⚙️ Highly configurable: Customize sorting strategy, grouping style, and more

🚀 Quick Start

1. Install the extension
2. Open any PHP file with imports
3. Use Ctrl+Shift+I (or Cmd+Shift+I on Mac) to group imports
4. Or let it automatically group on save!

📝 Examples

Before:

use App\Models\User;
use App\Models\Post;
use App\Models\Comment;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Auth;
use Illuminate\Support\Facades\DB;

After (default — inline style):

use Illuminate\Http\Request;
use Illuminate\Support\Facades\{Auth, DB};

use App\Models\{Comment, Post, User};

After (multiline style):

use Illuminate\Http\Request;
use Illuminate\Support\Facades\{
    Auth,
    DB,
};

use App\Models\{
    Comment,
    Post,
    User,
};

With Aliases:

// Before
use App\Models\User as UserModel;
use App\Models\Post as PostModel;

// After
use App\Models\{Post as PostModel, User as UserModel};

⌨️ Commands & Shortcuts

Note: Use Cmd instead of Ctrl on Mac.
All commands are also available via right-click context menu.

⚙️ Configuration

Access settings via File > Preferences > Settings and search for "Laravel Import Grouper".

laravelImportGrouper.autoGroupOnSave

• Type: boolean · Default: true
• Automatically group imports when saving PHP files

laravelImportGrouper.minClassesForGrouping

• Type: number · Default: 2
• Minimum classes needed from same namespace to create a grouped import

laravelImportGrouper.sortStrategy

• Type: string · Default: "custom"
• Options: "alphabetical" · "length" · "custom"
• Controls how namespaces are ordered

laravelImportGrouper.sortOrder

• Type: array · Default: ["Illuminate", "Laravel", "App"]
• Priority order when sortStrategy is "custom"

laravelImportGrouper.separateVendorFromApp

• Type: boolean · Default: true
• Adds a blank line between vendor imports and App imports (PSR-12 style)

laravelImportGrouper.vendorPrefixes

• Type: array · Default: ["Illuminate", "Laravel", "Symfony", "Carbon", "Spatie"]
• Namespace prefixes treated as vendor/third-party

laravelImportGrouper.multilineGroupStyle

• Type: string · Default: "inline"
• Options: "inline" → {Post, User} · "multiline" → each class on its own line

laravelImportGrouper.enableVersionFilter

• Type: boolean · Default: true
• Only run on Laravel projects meeting the minimum version

laravelImportGrouper.minimumLaravelVersion

• Type: string · Default: "11.0.0"
• Minimum Laravel version required (reads from composer.json)

laravelImportGrouper.enableStatusBar

• Type: boolean · Default: true
• Show status bar indicator when imports can be grouped

laravelImportGrouper.showPreview

• Type: boolean · Default: true
• Show preview panel before applying changes

💡 Smart Features

Lightbulb Code Action

A 💡 lightbulb appears automatically next to any import that can be grouped. Click it to group without opening the command palette.

Vendor / App Separation (PSR-12)

use Illuminate\Http\Request;       // vendor block
use Spatie\Permission\Models\Role;

use App\Models\User;               // app block (separated by blank line)
use App\Services\UserService;

Inline Comment Preservation

use App\Models\User; // main user model  ← preserved after grouping

Multi-line Import Parsing

The extension correctly handles imports already written in multi-line format and re-groups them.

Import Statistics

Run Show Import Statistics from the command palette to see:

📦 Total: 12  |  ✅ Grouped: 3  |  🔧 Can group: 6  |  📁 Namespaces: 4  |  🏆 Top: App\Models: 5

Single-step Undo

The entire grouping operation is applied as one WorkspaceEdit, so a single Ctrl+Z reverts everything.

🔧 Troubleshooting

Extension not working?

1. Make sure you're in a PHP file (.php extension)
2. Check that imports follow standard PHP use syntax
3. Verify VS Code language mode is set to PHP

Version filter blocking the extension?

Run Check Laravel Version from the command palette to see what version was detected, or Toggle Version Filter to disable the check entirely.

Auto-save too aggressive?

{ "laravelImportGrouper.autoGroupOnSave": false }

Want different sorting?

{
  "laravelImportGrouper.sortStrategy": "alphabetical"
}

Want multiline grouped style?

{
  "laravelImportGrouper.multilineGroupStyle": "multiline"
}

🤝 Contributing

Found a bug or have a feature request? Open an issue.

📋 Changelog

v0.0.5 — Refactor & New Features

Bug Fixes

• ✅ Inline comments (e.g. // primary model) are now preserved after grouping
• ✅ Multi-line imports (use App\Models\{\n User,\n Post\n}) are now parsed correctly
• ✅ Undo is now a single step (Ctrl+Z) instead of multi-step — uses WorkspaceEdit
• ✅ Preview opens in a clean side panel with PHP syntax highlight (no more dirty untitled file)

New Features

• 💡 Lightbulb Code Action — 💡 appears on groupable imports, no command palette needed
• 📊 Show Import Statistics command — summary of total, grouped, groupable, and top namespaces
• 🔀 Vendor/App blank line separator — PSR-12 compliant, configurable via separateVendorFromApp
• 🎯 Sort Strategy — choose alphabetical, length, or custom
• 📐 Multiline Group Style — choose between inline or multiline output format
• ⚙️ Config Validation — warns on startup if config values are invalid
• 🔔 Diagnostic Hints — groupable imports show a hint marker (dotted underline) in the editor

Config Added

• separateVendorFromApp
• vendorPrefixes
• sortStrategy
• multilineGroupStyle

v0.0.4 — Critical Bug Fix

• ✅ Fixed: class declarations were accidentally being removed
• ✅ Fixed: trait use statements inside classes (e.g. use HasFactory, Notifiable;) were being moved to the import section

v0.0.3 and earlier

• Initial release with basic import grouping, auto-save, status bar, and alias support

📄 License

MIT License — feel free to use in your projects!

Happy coding! 🚀
Made with ❤️ for the Laravel community