Filament Feature Showcase Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require helios-live/filament-feature-showcase
   

   Publish the package assets and config:

   php artisan vendor:publish --provider="HeliosLive\FilamentFeatureShowcase\FeatureShowcaseServiceProvider" --tag="filament-feature-showcase-config"
   php artisan vendor:publish --provider="HeliosLive\FilamentFeatureShowcase\FeatureShowcaseServiceProvider" --tag="filament-feature-showcase-assets"
   

2. Configuration Edit config/filament-feature-showcase.php to define:

   • versions: Array of changelog entries (title, description, date, features).
   • button_position: 'top-right' (default), 'top-left', or 'bottom-right'.
   • modal_width: 'lg' (default), 'xl', or 'full'.

3. First Use Case Add the plugin to your Filament admin panel in app/Providers/Filament/AdminPanelProvider.php:

   public function panel(Panel $panel): Panel
   {
       return $panel
           ->plugins([
               \HeliosLive\FilamentFeatureShowcase\Plugin::make(),
           ]);
   }
   

   Visit your Filament dashboard—the "What's New" button will appear immediately.

Implementation Patterns

Version Management Workflow

1. Structuring Releases Define versions in config/filament-feature-showcase.php as an array:

   'versions' => [
       [
           'title' => 'v2.0.0 - June 2026',
           'date' => '2026-06-01',
           'features' => [
               ['title' => 'New Dark Mode', 'description' => 'Toggle dark mode in settings.'],
               ['title' => 'API Rate Limiting', 'description' => 'Enhanced request handling.'],
           ],
       ],
       // Older versions...
   ],
   

   • Tip: Use Carbon\Carbon::now()->format('Y-m-d') for dynamic dates.

2. Dynamic Version Loading Fetch versions from a database or API:

   // In a service or config loader
   $versions = Version::query()->orderBy('released_at', 'desc')->get();
   config(['filament-feature-showcase.versions' => $versions->toArray()]);
   

3. Conditional Display Hide the button for specific users/roles via middleware or a custom plugin method:

   Plugin::make()
       ->visible(fn () => auth()->user()->hasRole('admin')),
   

4. Localization Translate version titles/descriptions using Filament’s localization:

   'title' => __('filament-feature-showcase::versions.v2.title'),
   

   Publish language files:

   php artisan vendor:publish --tag="filament-feature-showcase-lang"
   

Integration Tips

1. Custom Styling Override the modal’s Tailwind classes in resources/css/filament/filament-feature-showcase.css:

   .filament-feature-showcase-modal {
       --width: 100%;
   }
   

2. Event-Based Triggers Show the modal programmatically (e.g., after login):

   use HeliosLive\FilamentFeatureShowcase\Facades\FeatureShowcase;
   
   FeatureShowcase::showModal();
   

3. Version Badges Display a version label in the sidebar via a custom widget:

   Widget::make()
       ->columnSpanFull()
       ->content(fn () => FeatureShowcase::renderVersionLabel()),
   

4. Dark Mode Compatibility Ensure the modal respects Filament’s dark mode:

   'dark_mode' => true, // Add to config
   

Gotchas and Tips

Pitfalls

1. Caching Issues

   • Problem: Changes to config/filament-feature-showcase.php may not reflect immediately due to Laravel caching.
   • Fix: Clear the config cache:

     php artisan config:clear
     

     Or use config_cache middleware in app/Http/Kernel.php for development.

2. Asset Loading Conflicts

   • Problem: If the plugin’s CSS/JS fails to load, check for duplicate asset tags or missing mix-manifest.json entries.
   • Fix: Verify the filament-feature-showcase section in resources/js/filament/app.js:

     import '@helios-live/filament-feature-showcase/dist/filament-feature-showcase.js';
     

3. Version Ordering

   • Problem: Versions may not display chronologically if date fields are malformed.
   • Fix: Use Carbon for consistent date formatting:

     'date' => Carbon::parse('2026-06-01')->format('Y-m-d'),
     

4. Plugin Initialization Race

   • Problem: The plugin may not render if Filament’s panel loads asynchronously.
   • Fix: Ensure the plugin is registered after Filament’s core assets:

     // In AdminPanelProvider
     ->plugins([
         \Filament\Panel::make()->plugins(), // Core plugins first
         \HeliosLive\FilamentFeatureShowcase\Plugin::make(),
     ]),
     

Debugging Tips

1. Log Version Data Dump the loaded versions to debug:

   \Log::info('Feature Showcase Versions:', config('filament-feature-showcase.versions'));
   

2. Inspect Modal Content Use browser dev tools to check if the modal HTML/JS is injected. Look for:

   <div class="filament-feature-showcase-modal" x-data="...">
   

3. Disable JavaScript Test the plugin with JS disabled to ensure critical features (like the button) still work.

Extension Points

1. Custom Modal Content Override the modal template by publishing and modifying:

   php artisan vendor:publish --tag="filament-feature-showcase-views"
   

   Edit resources/views/vendor/filament-feature-showcase/modal.blade.php.

2. API-Driven Versions Extend the Version model or service to fetch data from an external API:

   class VersionService {
       public function fetchLatestVersion() {
           return Http::get('https://api.example.com/releases/latest')->json();
       }
   }
   

3. Analytics Tracking Track modal interactions (e.g., clicks) via a custom event listener:

   FeatureShowcase::onModalShown(function () {
       event(new FeatureShowcaseViewed(auth()->id()));
   });
   

4. Multi-Tenant Support Scope versions per tenant by overriding the config loader:

   config(['filament-feature-showcase.versions' => Tenant::current()->versions]);