Laravel Excel Importer Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require sazzadbinashique/laravel-excel-importer
   php artisan vendor:publish --provider="SazzadBinAshique\LaravelExcelImporter\ExcelImporterServiceProvider"
   php artisan migrate
   

2. Define an Import Type: In config/excel-importer.php, add a new import type under types:

   'user_import' => [
       'model' => \App\Models\User::class,
       'columns' => [
           'name' => 'Name',
           'email' => 'Email',
           'role' => 'Role',
       ],
       'rules' => [
           'name' => 'required|string',
           'email' => 'required|email',
           'role' => 'required|in:admin,user',
       ],
   ],
   

3. First Use Case:

   • Upload an Excel file via the built-in dashboard at /excel-importer.
   • Preview data before importing.
   • Validate and import with progress tracking.

Implementation Patterns

Core Workflow

1. Dashboard Integration:

   • Use the pre-built dashboard (/excel-importer) for file uploads, previews, and imports.
   • Customize the dashboard by extending the ExcelImporterController or overriding views in resources/views/vendor/excel-importer.

2. Livewire Component:

   • The package uses Livewire for reactive UI. Extend the ExcelImporter component for custom logic:

     use SazzadBinAshique\LaravelExcelImporter\Livewire\ExcelImporter;
     
     class CustomExcelImporter extends ExcelImporter {
         protected $customField = '';
     
         public function mount() {
             $this->importType = 'user_import';
         }
     
         public function import() {
             // Custom logic before import
             $this->dispatch('custom-event');
             parent::import();
         }
     }
     

3. Validation and Mapping:

   • Define columns and rules in the config to map Excel headers to model fields.
   • Use Laravel’s validation rules (e.g., required, unique, custom callbacks).

4. Chunked Imports:

   • For large files, leverage Laravel’s chunking:

     'chunk_size' => 100, // Default: 100
     

5. Post-Import Actions:

   • Hook into imported event:

     Event::listen('excel-importer.imported', function ($importType, $records) {
         // Send notification, log, etc.
     });
     

Integration Tips

• Custom Styling: Override Livewire styles in your app’s CSS.
• API Endpoint: For headless imports, create a custom controller:

  public function import(Request $request) {
      $request->validate(['file' => 'required|file']);
      ExcelImporter::import($request->file('file'), 'user_import');
  }
  

• Queue Jobs: Offload imports to queues for long-running tasks:

  ExcelImporter::dispatch($request->file('file'), 'user_import')->onQueue('imports');
  

Gotchas and Tips

Pitfalls

1. Livewire Dependency:

   • The package requires Livewire 3+. Ensure your app is compatible:

     composer require livewire/livewire
     

   • Debug Livewire issues with php artisan livewire:discover.

2. Column Mismatches:

   • Excel headers must match the columns config keys exactly (case-sensitive).
   • Use trim or strtolower in rules for flexibility:

     'rules' => [
         'email' => 'required|email|unique:users,email',
         'name' => 'required|string|min:3',
     ],
     

3. Memory Limits:

   • Large files may hit PHP memory limits. Adjust php.ini or use chunking:

     'chunk_size' => 50; // Lower for memory constraints
     

4. Dashboard Permissions:

   • The dashboard is protected by auth. Customize middleware in ExcelImporterServiceProvider:

     protected $middleware = [\App\Http\Middleware\AdminMiddleware::class];
     

5. File Size Limits:

   • Default PHP upload_max_filesize and post_max_size may block large uploads. Configure in .env:

     UPLOAD_MAX_SIZE=100M
     POST_MAX_SIZE=100M
     

Debugging

• Preview Issues:

  • Check storage/logs/laravel-excel-importer.log for parsing errors.
  • Verify Excel files are not corrupted (try opening in LibreOffice).

• Validation Errors:

  • Use dd($this->errors) in a Livewire component to inspect validation failures.

• Progress Tracking:

  • Ensure JavaScript is enabled. Test with:

    Livewire.emit('track-progress', { step: 'importing', percent: 50 });
    

Extension Points

1. Custom Importers:

   • Extend the ExcelImporter class to add pre/post-processing:

     class CustomImporter extends \SazzadBinAshique\LaravelExcelImporter\ExcelImporter {
         public function transformRecord($record) {
             $record['email'] = strtolower($record['email']);
             return $record;
         }
     }
     

2. Dashboard Customization:

   • Override views in resources/views/vendor/excel-importer.
   • Example: resources/views/vendor/excel-importer/dashboard.blade.php.

3. Event Hooks:

   • Listen for excel-importer.preparing, excel-importer.importing, and excel-importer.imported events.

4. Storage Backends:

   • Use maatwebsite/excel’s storage adapters (S3, etc.) by configuring Excel::store():

     Excel::store(new S3Store('bucket-name'), 'public');