Laravel Livewire Panel Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require alp-develop/laravel-livewire-panel
   php artisan panel:install
   

   Follow prompts for URL prefix (e.g., admin), CSS theme (Bootstrap 5/Tailwind), and gate driver.

2. First Page: Create a Livewire component with the panel layout:

   // app/Livewire/Dashboard.php
   namespace App\Livewire;
   use Livewire\Attributes\Layout;
   use Livewire\Component;
   
   #[Layout('panel::layouts.app')]
   class Dashboard extends Component {
       public function render() { return view('livewire.dashboard'); }
   }
   

3. Route Registration:

   // routes/web.php
   use AlpDevelop\LivewirePanel\Http\Middleware\PanelAuthMiddleware;
   
   Route::middleware(['web', PanelAuthMiddleware::class])
        ->prefix('admin')
        ->name('panel.admin.')
        ->group(function () {
            Route::get('/', \App\Livewire\Dashboard::class)->name('home');
        });
   

4. Access Panel: Visit /admin/login to authenticate, then /admin to see your dashboard.

Where to Look First

• Documentation: Start with Installation and Components.
• Artisan Commands: Use php artisan panel:list to inspect installed panels.
• Configuration: Check config/panel.php for theme, guard, and CDN settings.

First Use Case

Build a dashboard widget to display key metrics:

php artisan panel:make-widget stats-card --panel=admin

Edit the generated widget in app/Livewire/Admin/Widgets/StatsCard.php and add it to your dashboard:

// app/Livewire/Dashboard.php
public function render() {
    return view('livewire.dashboard', [
        'widgets' => [
            StatsCard::class,
        ],
    ]);
}

Implementation Patterns

Core Workflows

1. Panel Configuration:

   • Use php artisan panel:install for interactive setup.
   • Override defaults in config/panel.php:

     'panels' => [
         'admin' => [
             'theme' => 'tailwind',
             'guard' => 'web',
             'prefix' => 'admin',
             'cdn' => ['chartjs', 'sweetalert'],
         ],
     ],
     

2. Module-Based Development:

   • Create a module:

     php artisan panel:make-module users --panel=admin
     

   • Register routes in routes/panel.php:

     Route::panel('admin')->group(function () {
         Route::resource('users', \App\Livewire\Admin\UsersController::class);
     });
     

3. Widget Integration:

   • Add widgets to a page:

     #[Layout('panel::layouts.app')]
     class Dashboard extends Component {
         public function render() {
             return view('livewire.dashboard', [
                 'widgets' => [
                     StatsCard::class,
                     RecentActivity::class,
                 ],
             ]);
         }
     }
     

4. Navigation Management:

   • Config Mode: Define navigation in config/panel.php:

     'navigation' => [
         'admin' => [
             'items' => [
                 ['label' => 'Dashboard', 'route' => 'panel.admin.home'],
                 ['label' => 'Users', 'route' => 'panel.admin.users.index'],
             ],
         ],
     ],
     

   • Modules Mode: Use panel:make-module and register navigation in the module’s NavigationProvider.

5. Authentication:

   • Customize login/register views:

     php artisan panel:make-component login --panel=admin
     

   • Extend gate logic in app/Providers/PanelServiceProvider.php:

     Panel::extend('admin', function ($app) {
         return new CustomPanelGate();
     });
     

Integration Tips

• Livewire Components:

  • Extend PanelComponent for shared functionality:

    use AlpDevelop\LivewirePanel\Livewire\PanelComponent;
    
    class Dashboard extends PanelComponent {
        // Inherits panelId, panel(), and other helpers
    }
    

  • Use #[Locked] to protect properties from Livewire’s reactivity:

    #[Locked]
    public string $panelId;
    

• Theming:

  • Override CSS variables in resources/css/panel.css:

    :root {
        --panel-primary: #6366f1;
        --panel-secondary: #10b981;
    }
    

  • Publish theme assets:

    php artisan vendor:publish --tag=panel-themes
    

• CDN Libraries:

  • Enable/disable in config/panel.php:

    'cdn' => [
        'chartjs' => true,
        'sweetalert' => false,
    ],
    

  • Add custom CDN entries:

    'cdn' => [
        'custom' => [
            'url' => 'https://cdn.example.com/script.js',
            'integrity' => 'sha384-...',
        ],
    ],
    

• Localization:

  • Add translations to resources/lang/{locale}/panel.php:

    return [
        'dashboard' => [
            'title' => 'Tablero',
            'welcome' => 'Bienvenido',
        ],
    ];
    

  • Use in views:

    {{ __('panel::dashboard.title') }}
    

• Plugins:

  • Create a plugin:

    php artisan panel:make-plugin notifications --panel=admin
    

  • Register navigation:

    public function registerNavigation() {
        return [
            'label' => 'Notifications',
            'route' => 'panel.admin.notifications',
            'icon' => 'bell',
        ];
    }
    

• Events:

  • Listen to panel events (e.g., PanelLoggedIn):

    use AlpDevelop\LivewirePanel\Events\PanelLoggedIn;
    
    PanelLoggedIn::listen(function ($event) {
        \Log::info("User {$event->user->id} logged in to panel {$event->panelId}");
    });
    

• Testing:

  • Use PanelTestCase for panel-specific tests:

    use AlpDevelop\LivewirePanel\Testing\PanelTestCase;
    
    class DashboardTest extends PanelTestCase {
        public function test_dashboard_loaded() {
            $this->actingAs($user)
                 ->panel('admin')
                 ->get('/admin')
                 ->assertOk();
        }
    }
    

Gotchas and Tips

Pitfalls

1. Route Naming:

   • Issue: Forgetting to prefix route names with panel.{panelId}. (e.g., panel.admin.home).
   • Fix: Use the panel_route() helper or to_panel() macro:

     Route::get('/', Dashboard::class)->name('panel.admin.home');
     // or
     Route::get('/', fn() => redirect()->to_panel('admin', 'home'));
     

2. Middleware Order:

   • Issue: PanelAuthMiddleware must be after web middleware in the stack.
   • Fix: Ensure routes use:

     Route::middleware(['web', PanelAuthMiddleware::class])->group(...);
     

3. Livewire Hydration:

   • Issue: Widgets or components not re-rendering due to hydration timing.
   • Fix: Use wire:ignore for static content or trigger updates via this->dispatch('refresh').

4. CSS Conflicts:

   • Issue: Custom CSS overriding panel styles.
   • Fix: Scope custom styles with .panel-custom-* or use !important sparingly. Inspect the generated CSS variables (e.g., --panel-primary).

5. Dark Mode Persistence:

   • Issue: Dark mode toggle not persisting across sessions.
   • Fix: Ensure dark_mode_show_on_auth is true in config/panel.php and the dark-mode-toggle component is included in auth layouts.

6. Navigation Search:

   • Issue: Search results not translating labels/descriptions.
   • Fix: Ensure translations are added to resources/lang/{locale}/panel.php under navigation.search.*.

7. CDN Loading:

   • Issue: CDN scripts failing to load or duplicate loading.
   • Fix: Use data-navigate-once attribute (handled automatically by the package) and verify CDN URLs in config/panel.php.

8. Multi-Panel Conflicts:

   • Issue: Routes or assets bleeding between panels.
   • Fix: Always specify --panel={id} in artisan commands and use Panel::for('admin')->... in code.

9. Rate Limiting:

   • Issue: Unexpected rate-limiting on login/register.
   • Fix: Adjust rate_limiting in config/panel.php