Module Dashboard Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require cvepdb-cms/module-dashboard
   

   Add the service provider to config/app.php under providers:

   Cvepdb\Dashboard\DashboardServiceProvider::class,
   

2. Publish Configuration

   php artisan vendor:publish --provider="Cvepdb\Dashboard\DashboardServiceProvider" --tag="config"
   

   This generates config/dashboard.php. Review and customize:

   • Default dashboard widgets
   • Widget visibility rules
   • Cache settings

3. First Use Case: Displaying the Dashboard Add the dashboard blade directive to your layout:

   @dashboard
   

   Or manually render a widget:

   use Cvepdb\Dashboard\Widgets\RecentCvesWidget;
   
   $widget = new RecentCvesWidget();
   echo $widget->render();
   

4. Key Configuration

   • Set dashboard.default_widgets to control which widgets load by default.
   • Configure dashboard.cache to enable/disable widget caching (recommended for production).

Implementation Patterns

Widget Development

1. Creating Custom Widgets Extend Cvepdb\Dashboard\AbstractWidget:

   namespace App\Dashboard\Widgets;
   
   use Cvepdb\Dashboard\AbstractWidget;
   
   class CustomCveStatsWidget extends AbstractWidget
   {
       public function render()
       {
           return view('dashboard.widgets.custom-cve-stats', [
               'stats' => $this->getStats(),
           ]);
       }
   
       protected function getStats()
       {
           return Cve::stats();
       }
   }
   

2. Registering Widgets Bind your widget to the container in a service provider:

   $this->app->bind('dashboard.widgets.custom-cve-stats', function ($app) {
       return new \App\Dashboard\Widgets\CustomCveStatsWidget();
   });
   

3. Dynamic Widget Loading Use the Dashboard facade to load widgets dynamically:

   use Cvepdb\Dashboard\Facades\Dashboard;
   
   $widgets = Dashboard::load(['recent-cves', 'custom-cve-stats']);
   

Layout Integration

1. Dashboard Sections Use @dashboard.section to create named sections:

   @dashboard.section('security-metrics')
       @foreach($widgets as $widget)
           {!! $widget->render() !!}
       @endforeach
   @enddashboard
   

2. Conditional Widgets Leverage visibility rules in config/dashboard.php:

   'visibility' => [
       'recent-cves' => function () {
           return auth()->user()->can('view_cves');
       },
   ],
   

Data Fetching

1. Eager Loading Data Preload widget data in a controller:

   public function dashboard()
   {
       $widgets = Dashboard::load(['recent-cves', 'vulnerability-trends']);
       $widgets->each->loadData(); // Calls $widget->loadData() if defined
       return view('dashboard', compact('widgets'));
   }
   

2. Caching Strategies Cache widget data for 5 minutes:

   public function loadData()
   {
       return Cache::remember("dashboard_{$this->getCacheKey()}", now()->addMinutes(5), function () {
           return $this->fetchFreshData();
       });
   }
   

Gotchas and Tips

Common Pitfalls

1. Widget Registration Order

   • Widgets registered later may override earlier ones if they share the same name.
   • Fix: Use unique widget IDs or namespace them (e.g., app.custom-cve-stats).

2. Cache Invalidation

   • Widget data may stale if not invalidated after related model updates.
   • Fix: Implement Cvepdb\Dashboard\Contracts\CacheableWidget and call:

     Dashboard::invalidateCache('widget-name');
     

3. Blade Directives Conflicts

   • @dashboard may conflict with other packages using @ directives.
   • Fix: Use the facade method instead:

     echo Dashboard::render();
     

Debugging Tips

1. Widget Debug Mode Enable in config/dashboard.php:

   'debug' => env('APP_DEBUG', false),
   

   • Logs widget load times and data sources.

2. Widget Isolation

   • Test widgets in isolation by temporarily disabling others in config/dashboard.php:

     'default_widgets' => ['recent-cves'], // Only load this widget
     

3. Performance Profiling

   • Use Laravel Debugbar to profile widget load times:

     use Barryvdh\Debugbar\Facades\Debugbar;
     
     public function loadData()
     {
         Debugbar::info('Widget Data Load', ['source' => 'database']);
         return Model::query()->get();
     }
     

Extension Points

1. Custom Widget Events

   • Listen for widget events to trigger actions:

     Dashboard::listen('widget.rendered', function ($widget) {
         // Log or process widget output
     });
     

2. Widget Middleware

   • Apply middleware to widgets via the middleware method:

     class CustomWidget extends AbstractWidget
     {
         public function middleware()
         {
             return [\App\Http\Middleware\CheckPermission::class];
         }
     }
     

3. Internationalization

   • Translate widget labels and descriptions:

     public function getLabel()
     {
         return trans('dashboard.widgets.recent_cves.label');
     }
     

   • Publish language files:

     php artisan vendor:publish --tag=dashboard-lang