Filament Storage Monitor Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require achyutn/filament-storage-monitor
   

   Ensure your composer.json meets the requirements (PHP 8.2+, Filament 4.x/5.x).

2. Registration: Add the plugin to your Filament panel in app/Providers/Filament/AdminPanelProvider.php:

   FilamentStorageMonitor::make()
       ->addDisk('/mnt/data') // Defaults to system disk
   

3. First Use Case: Immediately see disk usage for your root partition in the Filament dashboard sidebar. No additional configuration is needed for basic functionality.

Where to Look First

• Widget Placement: The monitor appears in the Filament dashboard sidebar by default. Check resources/views/vendor/filament-storage-monitor for customization hooks.
• Configuration: The FilamentStorageMonitor::make() method is chainable. Start with:

  ->addDisk('/path/to/disk', label: 'Custom Label')
  ->thresholds([70, 90]) // Percentage warnings
  ->colorScheme('red-yellow-green') // Customize colors
  

Implementation Patterns

Core Workflows

1. Monitoring Multiple Disks: Combine system disks and Laravel storage disks:

   FilamentStorageMonitor::make()
       ->addDisk('/mnt/data', label: 'Data')
       ->laravelDisk('public', label: 'Media')
       ->laravelDisk('s3', label: 'Cloud Backup');
   

2. Dynamic Thresholds: Use closures for runtime thresholds (e.g., fetch from DB):

   ->thresholds(fn () => [
       config('storage.min_warning'),
       config('storage.max_warning')
   ])
   

3. Health-Based Styling: Leverage Filament’s built-in styling:

   ->colorScheme('red-yellow-green')
   ->healthThresholds([70, 90]) // Override default 80/90
   

Integration Tips

• Filament Widgets: Embed the monitor in a custom widget:

  use AchyutN\FilamentStorageMonitor\Widgets\StorageMonitor;
  
  StorageMonitor::make()
      ->disk('/mnt/data')
      ->mountIn('custom.widgets');
  

• Panel-Specific Configuration: Override defaults per panel (e.g., staging vs. production):

  $panel->plugins([
      FilamentStorageMonitor::make()
          ->thresholds([85, 95]) // Stricter for staging
  ]);
  

• Localization: Translate labels and messages via Filament’s localization system:

  ->label(__('storage.monitor.label'))
  ->warningMessage(__('storage.monitor.warning'))
  

Gotchas and Tips

Pitfalls

1. Permission Issues:

   • Ensure the PHP process has read access to monitored disks. Test with:

     php artisan storage:monitor --test
     

   • Debug with storage_get_fs_usage() in Tinker:

     \AchyutN\FilamentStorageMonitor\Support\Facades\StorageMonitor::getFsUsage('/mnt/data');
     

2. Laravel Disk Misconfiguration:

   • If using laravelDisk(), verify the disk is properly configured in config/filesystems.php. Missing disks will throw silent errors.

3. Caching:

   • Disk usage is cached by default (1 minute). Disable with:

     ->cacheDuration(0)
     

   • Clear cache manually if data appears stale:

     php artisan cache:clear
     

Debugging

• Log Output: Enable debug logs in config/filament-storage-monitor.php:

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

  Check storage/logs/filament-storage-monitor.log.

• Common Errors:

  • DiskNotFoundException: Verify disk paths exist and are accessible.
  • InvalidArgumentException: Check threshold values (must be 0 < x < 100).

Extension Points

1. Custom Styling: Override Blade templates in resources/views/vendor/filament-storage-monitor:

   @extends('filament-storage-monitor::widget')
   @section('usage-bar')
       <!-- Custom SVG/HTML -->
   @endsection
   

2. Event Hooks: Listen for storage events (e.g., low disk space alerts):

   use AchyutN\FilamentStorageMonitor\Events\StorageThresholdExceeded;
   
   StorageThresholdExceeded::subscribe(function ($event) {
       Log::warning("Disk {$event->disk} at {$event->usage}% usage!");
   });
   

3. API Access: Fetch raw data via a custom route:

   Route::get('/storage-monitor/data', function () {
       return response()->json(
           \AchyutN\FilamentStorageMonitor\Facades\StorageMonitor::getAllDisksUsage()
       );
   });
   

Pro Tips

• Exclude Disks: Skip system disks (e.g., /boot) with:

  ->excludeDisks(['/boot', '/tmp'])
  

• Real-Time Updates: Combine with Filament’s polling:

  ->pollingInterval(30) // Refresh every 30 seconds
  

• Dark Mode Support: Use Filament’s dark mode variables in CSS:

  .filament-storage-monitor {
      --filament-storage-monitor-bg: {{ Filament\Support\Facades\Filament::getCurrentPanel()?->darkMode ? '#2d3748' : '#ffffff' }};
  }