Filament Command Palette Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require usamamuneerchaudhary/filament-command-palette
   

2. Register the plugin in your Panel provider:

   use Usamamuneerchaudhary\CommandPalette\FilamentCommandPalettePlugin;
   
   public function panel(Panel $panel): Panel
   {
       return $panel
           ->plugins([
               FilamentCommandPalettePlugin::make(),
           ]);
   }
   

3. Test the palette by pressing Cmd+K (Mac) or Ctrl+K (Windows/Linux). The default palette includes navigation to resources, pages, and Filament’s built-in actions.

First Use Case: Quick Resource Navigation

• Open the palette (Cmd+K).
• Type the name of a resource (e.g., "User").
• Select the resource from the filtered results to navigate directly to its list page.

Implementation Patterns

Core Workflows

1. Registering Custom Commands

Add commands via the config file (config/command-palette.php):

'custom_commands' => [
    fn () => [
        \Usamamuneerchaudhary\CommandPalette\Support\CommandItem::make(
            'Generate Report',
            route('reports.generate'),
            'Reports',
            icon: 'heroicon-o-chart-bar',
        ),
        \Usamamuneerchaudhary\CommandPalette\Support\CommandItem::make(
            'Switch Tenant',
            route('tenants.switch'),
            'Tenants',
            icon: 'heroicon-o-users',
        ),
    ],
],

Best Practice: Group commands by category (e.g., "Reports", "Tenants") for better UX.

2. Dynamic Command Registration

Extend the plugin in a service provider to register commands dynamically:

use Usamamuneerchaudhary\CommandPalette\FilamentCommandPalettePlugin;

public function register()
{
    FilamentCommandPalettePlugin::registerCustomCommands(
        fn () => [
            CommandItem::make(
                'Create ' . $this->resource->modelLabel(),
                $this->resource->getUrl('create'),
                'Resources',
            ),
        ]
    );
}

3. Integration with Filament Resources

Add a custom action to a resource and expose it in the palette:

use Filament\Resources\Resource;
use Usamamuneerchaudhary\CommandPalette\Support\CommandItem;

public function getPages(): array
{
    return [
        // ... existing pages
    ];
}

public function registerCustomCommands(): void
{
    FilamentCommandPalettePlugin::registerCustomCommands(
        fn () => [
            CommandItem::make(
                'Bulk Delete',
                $this->getUrl('bulk-delete'),
                'Actions',
                icon: 'heroicon-o-trash',
            ),
        ]
    );
}

4. Conditional Command Visibility

Use closures to show/hide commands based on auth, roles, or data:

'custom_commands' => [
    fn () => [
        auth()->user()->can('generate_reports')
            ? CommandItem::make(
                'Generate Report',
                route('reports.generate'),
                'Reports',
            )
            : null,
    ],
],

5. Overriding Views

Publish and customize the palette’s Blade views:

php artisan vendor:publish --tag=command-palette-views

Edit resources/views/vendor/command-palette/partials/palette.blade.php to modify:

• Styling (e.g., dark mode adjustments).
• Layout (e.g., add a footer with links).
• Behavior (e.g., add a "Clear Search" button).

Integration Tips

Avoiding Conflicts

• Keyboard Shortcuts: If Cmd+K conflicts with another tool (e.g., browser dev tools), override the shortcut in config/command-palette.php:

  'key_bindings' => ['mod+shift+k'],
  

• Topbar Button: Disable the topbar button if it clashes with your layout:

  'show_topbar_button' => false,
  

Performance

• Large Command Lists: Limit results per category to avoid UI lag:

  'max_results' => 5, // Default is 10
  

• Dynamic Loading: For >50 commands, consider lazy-loading groups (requires custom view logic).

Testing

• Unit Tests: Mock the CommandItem class to test command registration:

  $command = CommandItem::make('Test', '/test', 'Test');
  $this->assertEquals('Test', $command->label);
  

• E2E Tests: Use Laravel Dusk or Playwright to verify:
  • Keyboard shortcuts open the palette.
  • Commands navigate correctly.

Gotchas and Tips

Pitfalls

1. Filament Version Mismatch

   • The package targets Filament v5 (as per the latest release). If using Filament v4, ensure compatibility or use the v1.1 release.
   • Fix: Check the composer.json of the package for Filament version constraints.

2. Command Duplication

   • Default commands (e.g., "Publish Views") may duplicate with custom commands if not namespaced properly.
   • Fix: Use unique labels or categories for custom commands:

     CommandItem::make('Custom Publish', '/publish', 'Custom Actions'),
     

3. Keyboard Shortcut Overrides

   • Some browsers/OSes may intercept Cmd+K (e.g., Safari’s "Find" feature).
   • Fix: Use mod+shift+k or document the shortcut in your admin guide.

4. View Publishing Issues

   • If views are already published, use --force to overwrite:

     php artisan vendor:publish --tag=command-palette-views --force
     

5. Permission-Based Commands

   • Commands registered via closures may not respect Filament’s gate policies if not wrapped in auth()->user()->can() checks.
   • Fix: Use Filament’s authorize() helper or Laravel’s gates:

     FilamentCommandPalettePlugin::registerCustomCommands(
         fn () => [
             gate('view_reports') ? CommandItem::make(...) : null,
         ]
     );
     

Debugging Tips

1. Log Command Registration Add debug logs to verify commands are registered:

   \Log::debug('Custom commands:', [
       FilamentCommandPalettePlugin::getCustomCommands(),
   ]);
   

2. Inspect Palette HTML Use browser dev tools (Ctrl+Shift+I) to inspect the palette’s DOM structure when it renders. Look for:

   • Missing commands (check if they’re filtered out by permissions).
   • Styling issues (e.g., !important conflicts).

3. Check for JavaScript Errors Open the browser console (F12) and filter for errors when opening the palette. Common issues:

   • Alpine.js conflicts: Ensure no other Filament plugins are overriding Alpine’s event listeners.
   • Missing routes: Verify custom command routes exist (e.g., route('reports.generate')).

4. Disable Other Plugins If the palette fails to load, temporarily disable other Filament plugins to isolate conflicts:

   ->plugins([
       // FilamentCommandPalettePlugin::make(), // Comment out others first
   ]),
   

Extension Points

1. Custom Command Categories Extend the palette to support nested categories (e.g., "Reports → Monthly"):

   • Override the published view (palette.blade.php) to add collapsible groups.
   • Use JavaScript to toggle visibility (Alpine.js example):

     <div x-data="{ open: false }">
         <button @click="open = !open">Reports</button>
         <div x-show="open">
             <!-- Sub-commands -->
         </div>
     </div>
     

2. AI-Powered Suggestions Integrate with an API (e.g., OpenAI) to suggest commands based on user input:

   'custom_commands' => [
       fn () => [
           CommandItem::make(
               'AI Suggest: ' . request('query'),
               route('ai.suggest', ['query' => request('query')]),
               'AI',
           ),
       ],
   ],
   

3. Recent Commands Track and display frequently used commands using Laravel’s cache:

   // In a service provider
   FilamentCommandPalettePlugin::registerCustomCommands(
       fn () => [
           CommandItem::make(
               'Recent: ' . cache()->get('last_command', 'None'),
               '#',
               'Recent',
           ),
       ]
   );
   

4. Multi-Tenant Support Filter commands by tenant in a multi-tenant app:

   'custom_commands' => [
       fn () => [
           tenant('company_id') === 1
               ? CommandItem::make('Company A Dashboard', route('tenants.dashboard'), 'Tenants')
               : null