Filament Refresh Sidebar Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require jeffersongoncalves/filament-refresh-sidebar
   

2. Publish the config (if needed):

   php artisan vendor:publish --provider="JeffersonGoncalves\FilamentRefreshSidebar\FilamentRefreshSidebarServiceProvider"
   

3. Register the plugin in your AppServiceProvider or Filament panel configuration:

   use JeffersonGoncalves\FilamentRefreshSidebar\FilamentRefreshSidebarPlugin;
   
   FilamentRefreshSidebarPlugin::make()
       ->register();
   

First Use Case

Trigger a sidebar refresh when a model is updated or deleted. For example, in a resource controller:

use JeffersonGoncalves\FilamentRefreshSidebar\Facades\FilamentRefreshSidebar;

public function afterSave(Model $record): void
{
    FilamentRefreshSidebar::refresh();
}

Implementation Patterns

Common Workflows

1. Dynamic Badges: Use the package to refresh badges tied to real-time data (e.g., unread notifications, pending tasks).

   FilamentRefreshSidebar::refreshBadge('notifications');
   

2. Conditional Refresh: Refresh only specific sidebar items based on logic:

   if ($this->isAdmin()) {
       FilamentRefreshSidebar::refreshItem('admin-dashboard');
   }
   

3. Event-Based Refresh: Bind to Laravel events (e.g., ModelSaved, ModelDeleted) in an event listener:

   public function handle(ModelSaved $event)
   {
       FilamentRefreshSidebar::refresh();
   }
   

4. Custom Polling Interval: Configure refresh intervals in config/filament-refresh-sidebar.php:

   'polling_interval' => 30, // seconds
   

Integration Tips

• Filament Resources: Use afterSave, afterDelete, or afterRestore hooks in resource controllers.
• Livewire Components: Trigger refreshes in updated() or dehydrated() methods:

  public function dehydrated(): array
  {
      FilamentRefreshSidebar::refresh();
      return parent::dehydrated();
  }
  

• API Endpoints: Call the refresh via HTTP (if exposed):

  Route::post('/refresh-sidebar', [FilamentRefreshSidebar::class, 'refresh']);
  

Gotchas and Tips

Pitfalls

1. Race Conditions: Avoid calling refresh() too frequently in rapid successions (e.g., bulk actions). Use a queue or debounce logic:

   if (!FilamentRefreshSidebar::isRefreshing()) {
       FilamentRefreshSidebar::refresh();
   }
   

2. Caching Issues: If using Filament’s cache, clear it after refreshes to avoid stale data:

   Filament::cache()->forget('sidebar-items');
   

3. Overhead: Excessive refreshes can degrade performance. Monitor with:

   FilamentRefreshSidebar::getRefreshCount(); // Debugging
   

Debugging

• Log Refreshes: Enable debug mode in config:

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

• Check Events: Verify events are firing with Laravel’s event logging:

  php artisan event:list
  

Extension Points

1. Custom Refresh Logic: Extend the RefreshSidebar class to add custom logic:

   class CustomRefreshSidebar extends RefreshSidebar
   {
       public function refreshAdminItems()
       {
           // Custom logic
       }
   }
   

2. WebSocket Integration: Use Laravel Echo/Pusher to trigger refreshes from frontend events:

   Echo.channel('sidebar-updates')
       .listen('SidebarUpdated', () => {
           window.FilamentRefreshSidebar.refresh();
       });
   

3. Conditional Refreshes: Override the shouldRefresh() method to add custom conditions:

   FilamentRefreshSidebar::shouldRefresh(function () {
       return Auth::user()->hasRole('admin');
   });