Filament Flux Pro Laravel Package

Getting Started

Minimal Setup

1. Install Dependencies Run:

   composer require jeffersongoncalves/filament-flux-pro
   

   Ensure auth.json is configured with Flux Pro credentials (never commit this file).

2. Run Installer

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

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

3. Register Plugins In your Panel provider:

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

4. Rebuild Assets

   npm run build
   php artisan view:clear
   

First Use Case

Replace a basic DatePicker in a Resource with FluxDatePicker:

use Jeffersongoncalves\FilamentFluxPro\Forms\Components\FluxDatePicker;

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

Implementation Patterns

Form Fields Integration

Rebinding Existing Fields Enable useEverywhere() to auto-convert standard Filament fields to Flux Pro equivalents:

->plugin(FilamentFluxProPlugin::make()->useEverywhere([
    'datePicker' => true,
    'richEditor' => false, // Disable for specific fields
]))

Dynamic Data Binding Use closures for dynamic options in FluxAutocomplete or FluxPillbox:

FluxAutocomplete::make('user_id')
    ->fluxOptionsResolver(fn ($search) => User::search($search)->pluck('name', 'id'));

Widgets and Charts

Subclassing Chart Widgets Extend FluxLineChartWidget for custom data:

class RevenueChart extends FluxLineChartWidget {
    protected function getData() {
        return Revenue::query()
            ->groupByMonth()
            ->get()
            ->map(fn ($r) => ['date' => $r->month, 'revenue' => $r->total]);
    }
}

Table Integration Add sparklines to table columns:

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

Schema Components

Nested Layouts Combine FluxTabs with Flux Pro fields:

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

Conditional Rendering Use FluxPopover for contextual tooltips:

{{ FluxPopover::trigger(
    triggerHtml: '<flux:button>Details</flux:button>',
    contentHtml: '<flux:text>Advanced info...</flux:text>',
) }}

Page Concerns

Kanban Boards Define columns dynamically:

protected function getKanbanColumns() {
    return [
        KanbanColumnDefinition::make('Backlog'),
        KanbanColumnDefinition::make('In Progress'),
    ];
}

Command Palette Enable globally:

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

Gotchas and Tips

Common Pitfalls

1. Missing filament-flux Plugin Registration fails with a RuntimeException if FilamentFluxPlugin isn’t registered first.

2. License Authentication Forgetting auth.json or incorrect credentials cause silent failures. Test with:

   composer require livewire/flux-pro
   

3. Tailwind Scanning After installing, run npm run build and php artisan view:clear to ensure Flux Pro styles are compiled.

4. State Hydration FluxComposer returns an array (['text' => ..., 'attachments' => ...]) when attachments/mentions are used. Cast to json in your model:

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

Debugging Tips

• Console Errors: Check for Uncaught Error: Class 'FluxXyz' not found if the free filament-flux plugin is missing.
• Styling Issues: Clear cached views (php artisan view:clear) after updating Flux Pro.
• Data Binding: Use dd() to inspect closures in fluxOptionsResolver or fluxData.

Extension Points

1. Custom Chart Options Override getOptions() in chart widgets:

   protected function getOptions(): array {
       return [
           'colors' => ['emerald', 'fuchsia'],
           'showGrid' => false,
       ];
   }
   

2. Sanitization Rules Extend HtmlSanitizer for custom allowed tags:

   use Jeffersongoncalves\FilamentFluxPro\Support\HtmlSanitizer;
   
   $sanitizer = new HtmlSanitizer();
   $sanitizer->addAllowedTags(['custom-tag']);
   

3. Kanban Customization Use KanbanCardData to modify card rendering:

   protected function getKanbanCardData(KanbanCardData $data) {
       $data->title(fn ($record) => "Task #{$record->id}");
       return $data;
   }
   

Performance

• Lazy-Loading Data: For FluxAutocomplete, use fluxDebounce() to reduce API calls.
• Chart Optimization: Pre-fetch data in getData() to avoid runtime queries.

Configuration Quirks

• useEverywhere(): Disabling it doesn’t revert fields to their original state—you must manually replace them.
• Flux Pro Version: Ensure livewire/flux-pro is ^2.13 (check composer.json).