Import Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation Run composer require clickandmortar/import-bundle and enable the bundle in AppKernel.php (Laravel 5.5+ users should register it in config/app.php under providers).

2. Basic Configuration Define a minimal config/import.php (or config.yml in Symfony) with:

   click_and_mortar_import:
     entities:
       user_import:
         model: App\User
         unique_key: email
         mappings:
           name: "FullName"
           email: "EmailAddress"
   

3. First Use Case Upload a CSV file (e.g., users.csv) with headers matching your mappings. Trigger the import via:

   use ClickAndMortar\ImportBundle\ImportManager;
   
   $importManager = $this->get('click_and_mortar_import.manager');
   $result = $importManager->import('user_import', 'path/to/users.csv');
   

Implementation Patterns

Workflows

1. Batch Processing For large files, chunk the import using Laravel’s Chunk helper or Symfony’s BatchProcessor:

   $importManager->import('user_import', $filePath, ['chunk_size' => 100]);
   

2. Pre/Post-Import Hooks Extend the bundle by overriding the ImportManager service:

   services:
     click_and_mortar_import.manager:
       class: App\Services\CustomImportManager
       arguments: ['@click_and_mortar_import.manager']
   

   Implement preImport() and postImport() in CustomImportManager.

3. Dynamic Mappings Use a service to generate mappings at runtime (e.g., for API imports):

   $mappings = $this->generateDynamicMappings($apiResponse);
   $importManager->import('dynamic_entity', $filePath, ['mappings' => $mappings]);
   

Integration Tips

• Validation: Add Laravel’s FormRequest or Symfony’s Validator to validate imported data before saving.
• Logging: Use Laravel’s Log facade or Symfony’s Monolog to track import progress:

  $importManager->import('user_import', $filePath, ['log' => true]);
  

• Queue Jobs: Offload imports to a queue (Laravel) or message broker (Symfony) for async processing:

  dispatch(new ImportJob('user_import', $filePath));
  

Gotchas and Tips

Pitfalls

1. Deprecated Symfony Bundle The package is designed for Symfony 2/3. For Laravel, wrap it in a service layer or use a Laravel-compatible alternative like maatwebsite/excel.

2. Unique Key Conflicts Ensure unique_key in config matches a database column. Skipped rows will log warnings but not fail.

3. File Encoding Issues Specify encoding in the import options:

   $importManager->import('user_import', $filePath, ['encoding' => 'UTF-8']);
   

4. Case-Sensitive Headers CSV headers must match mappings exactly (case-sensitive). Use strtolower() in mappings if needed:

   mappings:
     name: "fullname"  # Matches "FullName" in CSV
   

Debugging

• Dry Runs: Test mappings without saving:

  $importManager->import('user_import', $filePath, ['dry_run' => true]);
  

• Verbose Logging: Enable debug mode in config:

  click_and_mortar_import:
    debug: true
  

• Check Raw Data: Access raw rows via the ImportManager event system (Symfony) or Laravel’s after hooks.

Extension Points

1. Custom Writers Override the Writer class to support new formats (e.g., JSON):

   class JsonWriter extends AbstractWriter
   {
       public function write(array $data) { /* ... */ }
   }
   

   Register it in config:

   click_and_mortar_import:
     writers:
       json: App\Services\JsonWriter
   

2. Event Listeners Listen for import.start/import.end events (Symfony) or Laravel’s importing/imported events to trigger actions.

3. Database Transactions Wrap imports in transactions for atomicity:

   DB::transaction(function () use ($importManager) {
       $importManager->import('user_import', $filePath);
   });