Filament Flux Pro Laravel Package

Getting Started

Minimal Steps

1. Install Dependencies:

   composer require jeffersongoncalves/filament-flux-pro
   

   Ensure jeffersongoncalves/filament-flux is installed and registered first.

2. Configure Authentication: Add Flux Pro credentials to auth.json (never commit this file) and update composer.json with the Flux Pro repository.

3. Run Installation Command:

   php artisan filament-flux-pro:install --panel=admin
   

   This patches Tailwind config, publishes the config file, and warns about missing prerequisites.

4. Activate Flux:

   php artisan flux:activate
   npm run build
   php artisan view:clear
   

5. Register Plugin: In your Panel provider:

   ->plugin(FilamentFluxProPlugin::make()->useEverywhere())
   

First Use Case

Replace a basic DatePicker with FluxDatePicker in a Resource:

use Jeffersongoncalves\FilamentFluxPro\Forms\Components\FluxDatePicker;

FluxDatePicker::make('published_at')
    ->fluxMode('single')
    ->required();

Implementation Patterns

Form Fields Integration

Rebinding Existing Fields: Enable useEverywhere() to automatically replace Filament’s native fields (e.g., DatePicker → FluxDatePicker). Disable specific fields if needed:

->plugin(FilamentFluxProPlugin::make()->useEverywhere([
    'fileUpload' => false,
]))

Dynamic Data Binding: Use closures for dynamic options (e.g., FluxAutocomplete):

FluxAutocomplete::make('user_id')
    ->fluxOptionsResolver(fn ($search) => User::where('name', 'like', "%{$search}%")->pluck('name', 'id')->toArray());

Widgets and Charts

Subclassing Abstract Widgets: Extend FluxLineChartWidget to create custom charts:

class RevenueChart extends FluxLineChartWidget {
    protected function getData(): array {
        return Revenue::query()->get()->map(fn ($r) => ['date' => $r->created_at, 'value' => $r->amount])->toArray();
    }
}

Table Integration: Use FluxChartColumn for sparklines in tables:

FluxChartColumn::make('sales_trend')
    ->fluxData(fn ($record) => $record->last7DaysSales())
    ->fluxColor(fn ($record) => $record->trend > 0 ? 'green' : 'red');

Schema Components

Nested Components: Combine FluxTabs with Flux Pro fields:

FluxTabs::make('Post')
    ->tabs([
        Tab::make('Content')->schema([
            FluxEditor::make('body'),
        ]),
    ]);

Conditional Rendering: Use FluxPopover for tooltips or modals:

{{ FluxPopover::trigger(
    triggerHtml: '<flux:button>Help</flux:button>',
    contentHtml: '<flux:text>Detailed instructions...</flux:text>',
) }}

Page Concerns

Kanban Board: Extend FluxKanbanPage for drag-and-drop task management:

class TasksKanban extends FluxKanbanPage {
    protected function getKanbanColumns(): array {
        return [
            KanbanColumnDefinition::make('Backlog'),
            KanbanColumnDefinition::make('In Progress'),
        ];
    }
}

Command Palette: Enable globally in the plugin:

->plugin(FilamentFluxProPlugin::make()->enableCommandPalette())

Gotchas and Tips

Common Pitfalls

1. Missing auth.json:

   • Error: RuntimeException during installation if Flux Pro credentials are missing.
   • Fix: Add auth.json to the project root and ensure it’s in .gitignore.

2. Forgetting filament-flux:

   • Error: RuntimeException if jeffersongoncalves/filament-flux isn’t registered.
   • Fix: Register FilamentFluxPlugin before FilamentFluxProPlugin.

3. Tailwind Scanning Issues:

   • After installing, run npm run build and php artisan view:clear to ensure Flux Pro’s Tailwind classes are processed.

4. Flux Pro License:

   • The wrapper is MIT-licensed, but livewire/flux-pro is proprietary. Ensure your license is valid.

Debugging Tips

• Console Errors: Check browser console for Flux Pro-specific errors (e.g., missing dependencies). Run npm run dev to rebuild assets.

• Field State: Flux Pro fields dehydrate data differently (e.g., FluxComposer returns ['text' => ..., 'attachments' => ...]). Cast model attributes accordingly:

  protected $casts = [
      'message' => 'array',
  ];
  

• Custom CSS: Flux Pro uses Tailwind v4. Override styles in resources/css/filament/panel/theme.css:

  @tailwind base;
  @tailwind components;
  @tailwind utilities;
  @layer components {
      @import 'flux-pro';
  }
  

Extension Points

1. Custom Flux Options: Override getOptions() in chart widgets or use fluxConfig() on fields:

   FluxLineChartWidget::make()
       ->fluxConfig(['colors' => ['blue', 'green']]);
   

2. Dynamic Column Definitions: Fetch KanbanColumnDefinition data dynamically:

   getKanbanColumns(): array {
       return Status::all()->map(fn ($status) =>
           KanbanColumnDefinition::make($status->name)
               ->color($status->color)
       );
   }
   

3. Sanitization: Use HtmlSanitizer for FluxEditor content:

   FluxEditor::make('content')->fluxSanitize();
   

   Customize allowed tags in config/filament-flux-pro.php:

   'editor' => [
       'allowed_tags' => ['<strong>', '<em>', '<a>'],
   ],
   

4. File Uploads: Configure FluxFileUpload with Laravel storage disks:

   FluxFileUpload::make('avatar')
       ->fluxDisk('s3')
       ->fluxDirectory('avatars')
       ->fluxVisibility('public');
   

Performance

• Lazy-Loading: For large datasets in FluxAutocomplete, implement server-side search with pagination:

  ->fluxOptionsResolver(fn ($search) => User::where('name', 'like', "%{$search}%")->paginate(10)->pluck('name', 'id'));
  

• Chart Optimization: Limit data points in FluxChartColumn:

  ->fluxData(fn ($record) => $record->last30DaysSales()->take(10));