Dashboard Bundle Laravel Package

Getting Started

First Steps

1. Installation Add the package via Composer:

   composer require draw/dashboard-bundle
   

   Publish the bundle’s assets and configuration:

   php artisan vendor:publish --provider="Draw\DashboardBundle\DashboardBundle" --tag=config
   php artisan vendor:publish --provider="Draw\DashboardBundle\DashboardBundle" --tag=assets
   

2. Basic Setup Register the bundle in config/app.php under providers:

   Draw\DashboardBundle\DashboardBundle::class,
   

3. First Dashboard Widget Create a simple widget by extending AbstractWidget:

   namespace App\Dashboard\Widgets;
   
   use Draw\DashboardBundle\Widgets\AbstractWidget;
   
   class ExampleWidget extends AbstractWidget
   {
       public function getTitle(): string
       {
           return 'Example Widget';
       }
   
       public function getContent(): string
       {
           return '<div>Hello, Dashboard!</div>';
       }
   }
   

4. Register the Widget Add it to your dashboard configuration (config/dashboard.php):

   'widgets' => [
       'example' => [
           'class' => \App\Dashboard\Widgets\ExampleWidget::class,
           'position' => 1,
       ],
   ],
   

5. Display the Dashboard Add a route in routes/web.php:

   use Draw\DashboardBundle\Controller\DashboardController;
   
   Route::get('/dashboard', [DashboardController::class, 'index']);
   

Implementation Patterns

Widget Development

• Extending AbstractWidget Override getTitle(), getContent(), and optionally getIcon() for customization. Example:

  class StatsWidget extends AbstractWidget
  {
      public function getContent(): string
      {
          return view('dashboard.widgets.stats')->render();
      }
  }
  

• Dynamic Data Fetching Use dependency injection to fetch data (e.g., repositories, services):

  class UserStatsWidget extends AbstractWidget
  {
      public function __construct(private UserRepository $userRepo) {}
  
      public function getContent(): string
      {
          $stats = $this->userRepo->getStats();
          return view('dashboard.widgets.user_stats', compact('stats'));
      }
  }
  

• Blade Views Store widget views in resources/views/dashboard/widgets/. Example: resources/views/dashboard/widgets/example.blade.php

  <div class="card">
      <h5 class="card-header">{{ $widget->getTitle() }}</h5>
      <div class="card-body">
          {!! $widget->getContent() !!}
      </div>
  </div>
  

Dashboard Layout Customization

• Override Default Template Publish the bundle’s views and extend dashboard.blade.php:

  php artisan vendor:publish --provider="Draw\DashboardBundle\DashboardBundle" --tag=views
  

  Customize the layout in resources/views/vendor/dashboard/dashboard.blade.php.

• Widget Positioning Configure widget order in config/dashboard.php:

  'widgets' => [
      'stats' => ['class' => StatsWidget::class, 'position' => 1],
      'users' => ['class' => UserStatsWidget::class, 'position' => 2],
  ],
  

Authentication & Authorization

• Protect the Dashboard Use Laravel’s middleware in routes/web.php:

  Route::middleware(['auth'])->get('/dashboard', [DashboardController::class, 'index']);
  

• Widget-Level Permissions Implement logic in getContent() or use Laravel’s Gate:

  public function getContent(): string
  {
      if (!auth()->user()->can('view_admin_dashboard')) {
          abort(403);
      }
      return view('...');
  }
  

Integration with Laravel Mix/Webpack

• Custom CSS/JS Extend the bundle’s assets by adding your own files to:

  resources/assets/dashboard/
  

  Compile them alongside your main assets.

Gotchas and Tips

Common Pitfalls

1. Widget Registration Order Widgets are rendered in ascending order of their position value. Ensure unique positions to avoid overlaps.

2. Missing Dependencies If a widget fails silently, check:

   • Constructor dependencies are properly injected (use Laravel’s service container).
   • Views or assets are correctly published.

3. Caching Issues Clear Laravel’s cache after publishing assets or config:

   php artisan cache:clear
   php artisan view:clear
   

4. Blade vs. Raw HTML Use {!! !!} for raw HTML in getContent() to avoid auto-escaping:

   return '<div>' . htmlspecialchars($dynamicData) . '</div>';
   

Debugging Tips

• Log Widget Output Temporarily log getContent() output to debug rendering:

  \Log::debug('Widget content:', ['content' => $this->getContent()]);
  

• Check Published Assets Verify assets are published to public/vendor/dashboard/:

  php artisan vendor:publish --tag=assets --force
  

• Inspect Configuration Dump the loaded config to confirm widget registration:

  dd(config('dashboard'));
  

Extension Points

1. Custom Dashboard Controller Extend DashboardController to add logic (e.g., analytics):

   namespace App\Http\Controllers;
   
   use Draw\DashboardBundle\Controller\DashboardController as BaseDashboardController;
   
   class DashboardController extends BaseDashboardController
   {
       public function index()
       {
           // Custom logic (e.g., track visits)
           return parent::index();
       }
   }
   

2. Dynamic Widget Loading Load widgets dynamically via a service provider:

   public function register()
   {
       $this->app->bind(
           \Draw\DashboardBundle\Contracts\WidgetInterface::class,
           function () {
               return new DynamicWidget();
           }
       );
   }
   

3. Multi-Tenant Dashboards Override widget configuration per tenant by extending the config loader:

   config(['dashboard.widgets' => $this->getTenantWidgets()]);
   

Performance Considerations

• Lazy-Load Heavy Widgets Use JavaScript to load widgets on demand (e.g., via AJAX) for large datasets.
• Cache Widget Data Cache data in getContent() if the widget doesn’t change frequently:

  return Cache::remember("widget_{$this->getTitle()}", now()->addHours(1), function () {
      return view('...')->render();
  });