Filament Excel Laravel Package

Getting Started

First Steps

1. Installation Add the package via Composer:

   composer require pxlrbt/filament-excel
   

   Publish the config (if needed):

   php artisan vendor:publish --provider="Pxlrbt\FilamentExcel\FilamentExcelServiceProvider" --tag="filament-excel-config"
   

2. Basic Setup Register the package in app/Providers/Filament/AdminPanelProvider.php:

   public function panel(Panel $panel): Panel
   {
       return $panel
           ->plugins([
               \Pxlrbt\FilamentExcel\FilamentExcelPlugin::make(),
           ]);
   }
   

3. First Export Use the exportTable method in a Filament Resource:

   use Pxlrbt\FilamentExcel\Actions\ExportTable;
   
   public static function table(Table $table): Table
   {
       return $table
           ->columns([...])
           ->actions([
               ExportTable::make(),
           ]);
   }
   

Where to Look First

• Documentation: GitHub README (check for Filament v3 compatibility notes).
• Config: config/filament-excel.php (default settings, file naming, storage paths).
• Actions: Pxlrbt\FilamentExcel\Actions namespace for reusable export actions.

First Use Case

Export a filtered table as an Excel file with a single click:

use Pxlrbt\FilamentExcel\Actions\ExportTable;

public static function table(Table $table): Table
{
    return $table
        ->columns([...])
        ->actions([
            ExportTable::make()
                ->filename('users-export-' . now()->format('Y-m-d'))
                ->withHeadings()
                ->withEvents(), // Optional: trigger events before/after export
        ]);
}

Implementation Patterns

Common Workflows

1. Dynamic Filename Generation Use closures for dynamic filenames:

   ExportTable::make()
       ->filename(fn () => "reports/{$this->getKey()}-export.xlsx")
   

2. Customizing Exported Data Override the getExportedTableData method in your Resource:

   public function getExportedTableData(): array
   {
       return $this->table->getRecords()->map(fn ($record) => [
           'name' => $record->name,
           'custom_field' => $record->custom_field ?? 'N/A',
       ]);
   }
   

3. Batch Exports Combine with Filament’s BulkAction:

   use Filament\Actions\Action;
   use Pxlrbt\FilamentExcel\Actions\ExportTable;
   
   public static function table(Table $table): Table
   {
       return $table
           ->actions([
               Action::make('export-selected')
                   ->action(ExportTable::make()
                       ->onlySelected()
                   ),
           ]);
   }
   

4. Event-Based Extensions Listen to filament-excel.exporting or filament-excel.exported events:

   // In a service provider
   Excel::exporting(function (Exporting $event) {
       $event->setFilename('custom-prefix-' . $event->filename);
   });
   

Integration Tips

• Filament Forms: Use ExportTable in form actions for custom exports:

  public static function form(Form $form): Form
  {
      return $form
          ->actions([
              Action::make('export-form-data')
                  ->action(ExportTable::make()
                      ->withFormData($form->getState())
                  ),
          ]);
  }
  

• Laravel Excel Integration Leverage Maatwebsite\Excel features (e.g., WithHeadings, WithEvents) via the package’s config:

  // config/filament-excel.php
  'excel' => [
      'with_headings' => true,
      'events' => [
          'before' => \App\Listeners\LogExport::class,
      ],
  ],
  

• API Routes Expose exports via API:

  Route::get('/export', function () {
      return Excel::download(
          new UsersExport,
          'users.xlsx'
      );
  });
  

Gotchas and Tips

Pitfalls

1. Filament Version Mismatch

   • Issue: Package may not support your Filament version.
   • Fix: Check the GitHub issues or composer.json for compatibility.
   • Workaround: Use pxlrbt/filament-excel:dev-main for bleeding-edge Filament 3 support.

2. Large Dataset Performance

   • Issue: Exporting 100K+ rows may time out or crash.
   • Fix:
     • Use chunking in getExportedTableData():

       public function getExportedTableData(): array
       {
           return $this->table->getRecords()->chunk(1000)->toArray();
       }
       

     • Stream exports with Maatwebsite\Excel\Concerns\WithCustomStartCell and WithChunkReading.

3. Stale Data in Exports

   • Issue: Exports may not reflect real-time data due to caching or query scopes.
   • Fix: Force fresh data in getExportedTableData():

     public function getExportedTableData(): array
     {
         return $this->table->getRecords()->fresh()->toArray();
     }
     

4. File Storage Paths

   • Issue: Exports may fail if storage paths are misconfigured.
   • Fix: Verify filament-excel.storage in config and ensure the disk exists:

     // config/filament-excel.php
     'storage' => 'public',
     

     Run php artisan storage:link if using public disk.

Debugging Tips

1. Log Export Events Add a listener to debug:

   Excel::exporting(function (Exporting $event) {
       \Log::info('Exporting:', [
           'filename' => $event->filename,
           'data' => count($event->data),
       ]);
   });
   

2. Check Excel Writer If exports are corrupted, test with a minimal Maatwebsite\Excel class:

   use Maatwebsite\Excel\Concerns\FromCollection;
   
   class TestExport implements FromCollection
   {
       public function collection()
       {
           return collect([['test' => 'data']]);
       }
   }
   Excel::download(new TestExport, 'test.xlsx');
   

3. Clear Caches After config changes, run:

   php artisan optimize:clear
   php artisan view:clear
   

Extension Points

1. Custom Export Classes Extend Pxlrbt\FilamentExcel\Actions\ExportTable:

   namespace App\Actions;
   
   use Pxlrbt\FilamentExcel\Actions\ExportTable;
   
   class CustomExport extends ExportTable
   {
       protected function getFilename(): string
       {
           return 'custom-' . parent::getFilename();
       }
   }
   

2. Modify Excel Writer Bind a custom writer in the service provider:

   Excel::extend('custom', function () {
       return new \App\Exports\CustomExcelWriter;
   });
   

3. Add Presets Create reusable export configurations:

   // app/Exports/ReportPreset.php
   namespace App\Exports;
   
   use Pxlrbt\FilamentExcel\Actions\ExportTable;
   
   class ReportPreset extends ExportTable
   {
       public static function make(): static
       {
           return parent::make()
               ->withHeadings()
               ->withEvents()
               ->filename('report-' . now()->format('Y-m-d'));
       }
   }
   

4. Localization Override labels in resources/lang/en/filament-excel.php:

   return [
       'export' => [
           'title' => 'Download Excel',
           'description' => 'Export selected records to Excel',
       ],
   ];
   

Config Quirks

• Default Storage: Exports default to storage/app/filament-excel. Change via:

  'storage' => 's3', // or any configured disk
  

• File Naming: Avoid special characters (e.g., :, ?, /) in filenames.
• Memory Limits: Increase memory_limit in php.ini for large exports:

  memory_limit = 512M