README

Laravel Spotlight (manggala/laravel-spotlight) is a production-ready, keyboard-first Command Palette (Cmd+K / Ctrl+K) package designed specifically for Laravel applications powered by Inertia.js and React.

💡 Why Laravel Spotlight?

In the Laravel ecosystem, popular command palette tools (like Filament or wire-elements/spotlight) are 100% bound to Livewire and Blade. Applications built with Inertia.js were left without a server-driven command palette package.

Laravel Spotlight bridges this gap by introducing a Server-Driven UI (SDUI) engine. You define commands, model search providers, authorization policies, and route actions entirely in PHP. The package automatically injects authorized payloads into Inertia shared props, rendered seamlessly by a high-performance React modal overlay.

🌟 Key Features

Global Keyboard Shortcut: Toggle modal search anywhere using Cmd + K (macOS) or Ctrl + K (Windows/Linux).
Server-Driven Definition: Define commands fluently in PHP where your routes, models, and policies live.
Instant Client & Async Server Search: Static actions filter instantly (< 10ms); dynamic Eloquent model searches stream asynchronously with debouncing (< 150ms).
Eloquent Model Search Provider: Register searchable models (Users, Orders, Products, Customers) effortlessly.
RBAC & Gate Integration: Automatically respects Laravel Gates, Policies, and Spatie Roles/Permissions.
Categorized Section Grouping: Organize results visually into Navigation, Settings, Actions, and Models.
Accessibility First: 100% WCAG 2.1 AA keyboard navigation (Arrow Up/Down, Enter, Escape focus trapping).
Manggala Ecosystem Interoperability: Auto-indexes setting groups from manggala/laravel-manifest (laravel-settings) and deep-links to dashboards from manggala/laravel-dashboard-builder.

📦 Installation

Install the package via Composer:

composer require manggala/laravel-spotlight

Run the package installation command to publish configuration and Inertia React component views:

php artisan spotlight:install

Optionally publish resources manually:

# Publish configuration file
php artisan spotlight:publish --tag=config

# Publish React component views
php artisan spotlight:publish --tag=views

🚀 Quick Start

1. Registering Static Navigation Commands

Define application commands in your AppServiceProvider or dedicated Service Provider using the fluent Spotlight Facade:

use Manggala\Spotlight\Facades\Spotlight;
use Manggala\Spotlight\Commands\SpotlightCommand;

public function boot(): void
{
    Spotlight::register(
        SpotlightCommand::make('General Settings')
            ->description('Manage application branding, mail, and SMTP configurations')
            ->icon('cog')
            ->group('Navigation')
            ->keywords(['setting', 'config', 'smtp', 'mail', 'site name'])
            ->action(fn () => redirect()->route('settings.general'))
    );

    SpotlightCommand::make('System Cache Clear')
        ->description('Flush application cache, routes, and views')
        ->icon('trash')
        ->group('Actions')
        ->action(function () {
            Artisan::call('optimize:clear');
            return back()->with('success', 'System cache cleared successfully!');
        });
}

2. Dynamic Eloquent Model Search Provider

Search across database models fluently with debounced async queries:

use Manggala\Spotlight\Facades\Spotlight;
use App\Models\User;

Spotlight::search(User::class)
    ->group('Users')
    ->icon('user')
    ->query(function ($query, string $term) {
        return $query->where('name', 'like', "%{$term}%")
                    ->orWhere('email', 'like', "%{$term}%")
                    ->limit(8);
    })
    ->title(fn (User $user) => $user->name)
    ->subtitle(fn (User $user) => $user->email)
    ->avatar(fn (User $user) => $user->avatar_url)
    ->action(fn (User $user) => to_route('users.show', $user));

3. Role & Gate Authorization

Restrict commands based on user permissions or roles:

// Protect with Laravel Gate / Policy ability
SpotlightCommand::make('Financial Reports')
    ->group('Reports')
    ->can('view-financial-reports')
    ->action(fn () => to_route('reports.financial'));

// Protect with Spatie Roles
SpotlightCommand::make('Admin User Management')
    ->group('Administration')
    ->roles(['admin', 'super-admin'])
    ->action(fn () => to_route('admin.users'));

// Custom Closure Condition
SpotlightCommand::make('Pro Feature Dashboard')
    ->when(fn ($user) => $user->isProSubscriber())
    ->action(fn () => to_route('pro.dashboard'));

4. Mounting Frontend Component in Inertia Layout

Include the <SpotlightModal /> overlay component inside your primary Inertia React layout file (e.g. AuthenticatedLayout.tsx):

import React from 'react';
import { SpotlightModal } from '@/Components/SpotlightModal';

export default function AuthenticatedLayout({ children }) {
    return (
        <div className="min-h-screen bg-gray-100 dark:bg-gray-900">
            {/* Your Navigation Bar */}

            <main>{children}</main>

            {/* Global Command Palette Overlay */}
            <SpotlightModal />
        </div>
    );
}

⚙️ Configuration Reference

The published configuration file (config/spotlight.php) allows fine-tuning keybindings and search thresholds:

return [

    /*
    |--------------------------------------------------------------------------
    | Keyboard Shortcut Settings
    |--------------------------------------------------------------------------
    */
    'keybinding' => [
        'shortcut' => 'k', // Triggers Cmd+K or Ctrl+K
        'close_on_escape' => true,
    ],

    /*
    |--------------------------------------------------------------------------
    | Async Search Performance & Throttling
    |--------------------------------------------------------------------------
    */
    'search' => [
        'debounce_ms' => 150,
        'rate_limit_per_minute' => 60,
        'max_results_per_group' => 8,
    ],

    /*
    |--------------------------------------------------------------------------
    | UI & Visual Customization
    |--------------------------------------------------------------------------
    */
    'ui' => [
        'dark_mode' => true,
        'backdrop_blur' => true,
        'placeholder' => 'Type a command or search...',
    ],

];

🛠️ Artisan Commands

Command	Description
`php artisan spotlight:install`	Interactive wizard to publish configuration and Inertia React component views.
`php artisan spotlight:clear`	Clear cached command indexes and registry stores.
`php artisan spotlight:doctor`	Run diagnostic health check on registered commands, gates, and middleware.

🔗 Ecosystem Interoperability

Laravel Spotlight integrates natively with the Manggala Ecosystem:

manggala/laravel-manifest (laravel-settings): Automatically discovers and registers configuration sections so users can search settings (e.g. "SMTP Password", "Maintenance Mode") via Cmd+K.
manggala/laravel-dashboard-builder: Auto-indexes visual dashboards created with the dashboard builder for instant navigation.
manggala/laravel-status-page: Adds quick commands for running system diagnostic checks directly from the command palette.

🧪 Testing & Code Quality

Run the Pest PHP test suite:

vendor/bin/pest

Format code styling with Laravel Pint:

vendor/bin/pint

Run static analysis with Larastan / PHPStan (Level 8):

vendor/bin/phpstan analyse

📜 License

The MIT License (MIT). Please see LICENSE for more information.

manggala / laravel-spotlight

Maintainers

Package info

Statistics

Security