Filament Versions Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require awcodes/filament-versions
   

2. Register the Plugin: In your PanelProvider (e.g., app/Providers/Filament/AdminPanelProvider.php), add:

   use Awcodes\Versions\VersionsPlugin;
   
   public function panel(Panel $panel): Panel
   {
       return $panel
           ->plugins([
               VersionsPlugin::make(),
           ]);
   }
   

3. Theme Integration (if not using a custom theme): Add this to your theme CSS file (e.g., resources/css/filament/filament.css):

   @source '../../../../vendor/awcodes/filament-versions/resources/**/*.blade.php';
   

First Use Case

Display default framework versions (Laravel, PHP, Filament) in the Filament sidebar navigation footer. No additional configuration is needed beyond installation.

Implementation Patterns

Core Workflows

1. Default Integration:

   • Automatically displays Laravel, PHP, and Filament versions in the sidebar footer.
   • Works out-of-the-box after plugin registration.

2. Dashboard Widget:

   • Add the widget to your dashboard or custom pages:

     ->widgets([
         \Awcodes\Versions\VersionsWidget::class,
     ])
     

3. Custom Version Items:

   • Implement VersionProvider for custom versions (e.g., API clients, libraries):

     class MyCustomVersionProvider implements VersionProvider {
         public function getName(): string { return 'My Library'; }
         public function getVersion(): string { return '2.3.1'; }
     }
     

   • Register in the plugin:

     VersionsPlugin::make()
         ->items([new MyCustomVersionProvider()])
     

4. Conditional Rendering:

   • Disable the navigation view (sidebar footer) entirely:

     VersionsPlugin::make()
         ->hasNavigationView(false)
     

   • Disable default items (Laravel/PHP/Filament) while keeping custom ones:

     VersionsPlugin::make()
         ->hasDefaults(false)
     

Integration Tips

• Styling Control: Use the widgetColumnSpan and widgetSort methods to adjust widget placement:

  VersionsPlugin::make()
      ->widgetColumnSpan('full') // Full-width widget
      ->widgetSort(2)            // Position in dashboard
  

• Localization: The package includes translations (e.g., laravel, php, filament). Extend via Filament’s translation system if needed.
• Top Navigation Panels: If using topNavigation, the sidebar widget appears at the bottom of page content. No extra config is required.

Gotchas and Tips

Pitfalls

1. Theme Dependency:

   • Issue: Without a custom theme, the package’s Blade views won’t compile.
   • Fix: Follow Filament’s theme setup guide before installing.
   • Workaround: For quick testing, use the @source directive in your existing theme CSS.

2. Version Provider Conflicts:

   • Issue: Custom VersionProvider names/versions may clash with defaults (e.g., naming a custom item "Laravel").
   • Fix: Use unique names (e.g., Laravel Framework) and validate versions programmatically:

     public function getVersion(): string {
         return version_compare($this->getVersion(), '10.0.0', '>=') ? '10.x' : $this->getVersion();
     }
     

3. Widget Visibility:

   • Issue: Widget may not appear if topNavigation is enabled and hasNavigationView(false) isn’t set.
   • Fix: Explicitly configure the plugin for your panel type:

     // For sidebar panels
     ->hasNavigationView(true)
     // For top-nav panels
     ->hasNavigationView(false)
     

4. CSS Isolation:

   • Issue: Tailwind classes in the package might conflict with your theme.
   • Fix: Override styles in your theme CSS:

     .versions-widget { @apply your-custom-styles; }
     

Debugging

• Missing Versions: Check if VersionProvider implementations are correctly registered in the plugin. Use dd() in getVersion() to verify values.
• Widget Not Rendering: Ensure the widget is added to the widgets() array in your Panel configuration.
• Blade Compilation Errors: Verify the @source directive path is correct (relative to your theme CSS file).

Extension Points

1. Dynamic Versions: Fetch versions dynamically (e.g., from an API) by overriding getVersion():

   public function getVersion(): string {
       return file_get_contents('https://api.example.com/version');
   }
   

2. Conditional Items: Use closures to conditionally include items:

   ->items(fn () => [
       new MyCustomVersionProvider(),
       env('APP_ENV') === 'local' ? new DebugVersionProvider() : null,
   ])
   

3. Custom Styling Hooks: Extend the package’s Blade components by copying the views to your theme and modifying them (e.g., resources/views/vendor/awcodes/versions/...).

Performance

• Avoid Overhead: The package is lightweight, but custom VersionProvider implementations with heavy logic (e.g., network calls) may impact load times. Cache results if needed:

  public function getVersion(): string {
      return cache()->remember('my_library_version', now()->addHours(1), fn() => '2.3.1');
  }