Dashboard Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require baks-dev/dashboard
   php artisan vendor:publish --provider="BaksDev\Dashboard\DashboardServiceProvider" --tag="dashboard-config"
   php artisan vendor:publish --provider="BaksDev\Dashboard\DashboardServiceProvider" --tag="dashboard-migrations"
   php artisan migrate
   

2. Asset Installation

   php artisan baks:assets:install
   npm run dev  # or `npm run build` for production
   

3. First Use Case Register a dashboard widget via a service provider:

   // app/Providers/DashboardServiceProvider.php
   public function register()
   {
       Dashboard::widget('stats', StatsWidget::class);
   }
   

4. Where to Look First

   • Config: config/dashboard.php (widgets, permissions, layout)
   • Widgets: app/Dashboard/Widgets/ (default location for custom widgets)
   • Blade Templates: resources/views/vendor/dashboard/ (overridable templates)
   • CLI Commands: app/Console/Kernel.php (check baks:assets:install and baks:widgets:clear)

Implementation Patterns

Core Workflows

1. Widget Development

   • Extend BaksDev\Dashboard\Contracts\Widget:

     namespace App\Dashboard\Widgets;
     
     use BaksDev\Dashboard\Contracts\Widget;
     
     class StatsWidget implements Widget
     {
         public function render(): string
         {
             return view('dashboard.widgets.stats')->render();
         }
     
         public function title(): string
         {
             return 'System Stats';
         }
     }
     

   • Register via Dashboard::widget() in a service provider.

2. Layout Customization

   • Override default layout by publishing views:

     php artisan vendor:publish --tag="dashboard-views"
     

   • Modify resources/views/dashboard/layout.blade.php.

3. Dynamic Widget Loading

   • Use Dashboard::widgets() to fetch registered widgets dynamically:

     $widgets = Dashboard::widgets()->where('user_id', auth()->id())->get();
     

4. Authorization

   • Attach policies to widgets:

     Dashboard::widget('stats')->authorize(StatsPolicy::class);
     

   • Or use gates:

     Dashboard::widget('stats')->gate('view_dashboard_stats');
     

5. Asset Management

   • Add custom CSS/JS to widgets:

     public function assets(): array
     {
         return [
             'css' => ['/css/widgets/stats.css'],
             'js'  => ['/js/widgets/stats.js'],
         ];
     }
     

6. API Integration

   • Fetch widget data via API routes:

     Route::get('/dashboard/widgets/stats', [StatsWidget::class, 'api']);
     

Integration Tips

• Laravel Mix/Vite: Ensure resources/js/dashboard.js is included in your main JS file.
• Livewire/Alpine: Widgets support interactivity:

  public function render(): string
  {
      return view('dashboard.widgets.livewire-stats', [
          'stats' => LivewireStats::class,
      ]);
  }
  

• Caching: Clear widget cache after changes:

  php artisan baks:widgets:clear
  

Gotchas and Tips

Pitfalls

1. Asset Pipeline Conflicts

   • If widgets fail to load CSS/JS, verify:
     • Assets are published (php artisan baks:assets:install).
     • Mix/Vite is compiled (npm run dev).
     • No duplicate asset paths in assets() method.

2. Widget Registration Order

   • Widgets registered later may override earlier ones. Use unique names:

     Dashboard::widget('app.stats', StatsWidget::class); // Prefix with app namespace
     

3. Permission Caching

   • After adding/removing widget permissions, clear:

     php artisan cache:clear
     php artisan view:clear
     

4. Database Schema Mismatches

   • If migrations fail, check:
     • Doctrine migrations are up-to-date (php artisan doctrine:migrations:migrate).
     • The dashboard_widgets table exists and matches the schema.

5. Blade Template Overrides

   • Overriding views requires publishing before modifying:

     php artisan vendor:publish --tag="dashboard-views"
     

Debugging

• Widget Not Rendering?

  • Check if the widget is registered:

    dd(Dashboard::widgets()->toArray());
    

  • Verify the widget class exists and implements Widget.

• Permission Issues

  • Test with auth()->user()->can('view_dashboard') in a route middleware.

• Asset Loading Failures

  • Inspect browser console for 404 errors on /css/dashboard/*.css.
  • Ensure public_path() is correctly referenced in widget assets.

Configuration Quirks

1. Dashboard Layout

   • Customize columns/rows in config/dashboard.php:

     'layout' => [
         'columns' => 3,
         'rows'    => 2,
     ],
     

2. Widget Persistence

   • Disable user-specific widget storage (e.g., for global dashboards):

     'widgets' => [
         'persist_user_preferences' => false,
     ],
     

3. Fallback Widgets

   • Set default widgets in config:

     'defaults' => [
         'widgets' => ['stats', 'recent-activity'],
     ],
     

Extension Points

1. Custom Widget Storage

   • Override the widget repository:

     Dashboard::setWidgetRepository(CustomWidgetRepository::class);
     

2. Event Listeners

   • Listen for widget events (e.g., WidgetRegistered):

     Dashboard::widget('stats')->listen(function ($widget) {
         event(new StatsWidgetLoaded($widget));
     });
     

3. Middleware

   • Apply middleware to dashboard routes:

     Dashboard::middleware('auth:admin');
     

4. Testing

   • Use the DashboardTestCase trait:

     use BaksDev\Dashboard\Testing\DashboardTestCase;
     
     class StatsWidgetTest extends DashboardTestCase
     {
         public function test_widget_renders()
         {
             $this->assertDashboardWidget('stats');
         }
     }
     

```markdown
## Additional Notes for Laravel Developers
- **Laravel 10+ Compatibility**: Ensure `config/app.php` includes the service provider:
  ```php
  BaksDev\Dashboard\DashboardServiceProvider::class,

• Queue Jobs: Widgets can dispatch jobs:

  public function render(): string
  {
      dispatch(new RefreshStatsJob());
      return view('dashboard.widgets.stats');
  }
  

• Localization: Widgets support localization via setLocale():

  Dashboard::setLocale('ru');
  

• Dark Mode: Toggle via config:

  'theme' => [
      'dark_mode' => env('DASHBOARD_DARK_MODE', false),
  ],