Filament Import Wizard Laravel Package

Getting Started

Minimal Setup

1. Install the package (unchanged):

   composer require waad/filament-import-wizard
   php artisan vendor:publish --provider="Waad\FilamentImportWizard\FilamentImportWizardServiceProvider" --tag="config"
   php artisan vendor:publish --provider="Waad\FilamentImportWizard\FilamentImportWizardServiceProvider" --tag="migrations"
   php artisan migrate
   

2. Register the import wizard in a Filament resource (updated for new features):

   use Waad\FilamentImportWizard\FilamentImportWizard;
   
   public static function getPages(): array
   {
       return [
           // ... other pages
           FilamentImportWizard::make('users')
               ->model(User::class)
               ->columns([
                   'name' => 'Name',
                   'email' => 'Email',
                   'role' => 'Role',
               ])
               ->relationships([
                   'team' => 'Team Name',
               ])
               ->translatableFields(['name', 'description']) // New: Support for translatable fields
       ];
   }
   

3. First use case (updated UI flow):

   • Access the import wizard via the Filament resource page.
   • Upload a CSV/Excel file (e.g., users_import.csv).
   • New: The UI now shows model fields first, with auto-matching to CSV headers (e.g., Title → title).
   • Map fields using the reverse mapping interface (model fields on left, CSV headers on right).
   • For translatable fields, toggle the merge translation checkbox for multi-column support (e.g., name_en, name_es).
   • Proceed through the wizard to import data.

Implementation Patterns

Core Workflow (Updated)

1. Column Mapping (Reverse UI):

   • New: Model fields are now the primary mapping source with auto-snake-casing (e.g., UserTitle → user_title).
   • Use translatableFields() to enable support for Spatie Translatable or native JSON fields:

     ->translatableFields(['name', 'description'])
     

   • Example with relationships and translatable fields:

     ->columns(['name', 'email'])
     ->relationships(['team' => 'Team Name'])
     ->translatableFields(['name', 'bio'])
     

2. Upsert Logic (Fixed):

   • Upsert keys and fields now work reliably with guarded models:

     ->upsertKeys(['email'])
     ->upsertFields(['name', 'updated_at'])
     

   • Note: Model observers and boot methods now fire correctly during upserts (fixed in v1.1.0).

3. Queue Configuration (Optimized):

   • Batch processing is more stable with the new normalizeRecordKeys() fix:

     ->batchSize(1000)
     ->queueConnection('database')
     

   • Monitor progress via the import_jobs table (new completed_with_errors status).

4. Validation Rules (Enhanced):

   • Add custom validation per column (unchanged):

     ->validationRules([
         'email' => 'required|email|unique:users,email,{{existing}}',
         'role' => 'required|exists:roles,name',
     ])
     

   • New: Translatable fields now support locale-specific validation (e.g., name_en|required).

5. Relationship Handling (Fixed):

   • Relationship foreign keys are now saved correctly, even with guarded models:

     ->relationships([
         'team' => 'Team Name',
     ])
     ->relationshipModel(Team::class)
     

   • New: Use resolveFillable() for custom fillable logic if needed.

6. Translatable Fields (New):

   • Native JSON Support: No Spatie dependency required. Detects translatable fields via schema inspection.
   • Example CSV format:

     name_en,name_es,email
     John,Juan,john@example.com
     

   • Toggle merge translation in the UI to combine columns like name_en and name_es into a single field.

7. Standalone Usage (Unchanged):

   use Waad\FilamentImportWizard\Components\ImportWizard;
   
   public function mount()
   {
       ImportWizard::make('standalone_import')
           ->model(Product::class)
           ->columns(['name', 'price'])
           ->translatableFields(['name'])
           ->mount();
   }
   

Integration Tips (Updated)

• Customize the UI:
  • Override blade templates in resources/views/vendor/filament-import-wizard.
  • New: The mapping.blade.php template now uses a reverse layout (model fields first).
• Extend Functionality:
  • Create custom import actions by extending ImportAction (unchanged).
  • New: Use getTranslatableFields() to detect translatable fields programmatically.
• Multi-Tenancy:

  ->tenant(fn () => Auth::user()->currentTeam)
  

• Event Listeners:
  • Listen to ImportStarted, ImportCompleted, or ImportFailed (unchanged).
  • New: Eloquent events (e.g., created, updated) now fire during imports.
• Excel/CSV Handling:
  • New: Empty trailing columns are automatically trimmed in Excel files.

Gotchas and Tips

Common Pitfalls (Updated)

1. Reverse Mapping Confusion:

   • Issue: The new UI shows model fields first, which may be counterintuitive.
   • Fix: Use the auto-matching feature (e.g., UserTitle → user_title) to speed up mapping.
   • Tip: Manually map fields using the drag-and-drop interface if auto-matching fails.

2. Translatable Field Setup:

   • Issue: Forgetting to toggle merge translation for multi-column translatable fields (e.g., name_en, name_es).
   • Fix: Enable the checkbox in the UI or use:

     ->translatableFields(['name'])
     

   • Tip: CSV headers should follow the pattern field_locale (e.g., name_en).

3. Guarded Model Relationships:

   • Issue: Relationships may not save if the model uses $guarded = [].
   • Fix: Use resolveFillable() or ensure relationships are in $fillable:

     ->relationships(['team' => 'Team Name'])
     ->resolveFillable(fn () => array_merge($this->model->fillable, ['team_id']))
     

4. Memory Limits (Mitigated):

   • Issue: Large files may still hit memory limits.
   • Fix: Use smaller batchSize or chunk files server-side.
   • New: Excel files now trim empty columns to reduce memory usage.

5. Validation Overrides:

   • Issue: Custom validation may conflict with auto-generated rules.
   • Fix: Use skipValidation() or adjust rules carefully:

     ->validationRules(['email' => 'required|email'])
     ->skipValidation(['email']) // Skip auto-validation
     

Debugging Tips (Updated)

• Log Imports:

  • Enable debug mode in config:

    'debug' => env('FILAMENT_IMPORT_WIZARD_DEBUG', false),
    

  • New: Logs now use Log::debug instead of Log::warning in production.

• Test with Small Files:

  • Start with 10-20 rows to validate mappings before scaling.

• Check Job Payloads:

  • Inspect the import_jobs table for serialized payloads.
  • New: Look for completed_with_errors status if imports fail silently.

• Translatable Field Debugging:

  • Verify CSV headers match the expected field_locale pattern (e.g., title_en).
  • Check the database schema for JSON columns if using native JSON storage.

Extension Points (Updated)

1. Custom Import Actions:

   • Extend ImportAction to add pre/post-import logic (unchanged).
   • New: Use insertRecordsAsModels() to trigger Eloquent events:

     class CustomImportAction extends ImportAction
     {
         protected function afterImport(ImportJob $job)
         {
             event(new ImportCompleted($job, $results));
         }
     }
     

2. Custom Column Types:

   • Add support for custom column types (e.g., JSON, encrypted fields) by implementing ColumnType interface (unchanged).

3. Presets (Enhanced):

   • Save column mappings as presets for reuse (unchanged).
   • New: Include translatable fields in presets:

     ->presets([
         'users' => [
             'columns' => ['name', 'email'],
             'relationships' => ['team'],
             'translatableFields' => ['name', 'bio'],
         ],
     ])
     

4. Webhooks:

   • Listen to ImportCompleted events to trigger external actions (unchanged).