Import Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require 2lenet/import-bundle
   

   (Note: The README mentions composer update, but require is the modern standard.)

2. Register the Bundle Add to config/bundles.php (Laravel 5.5+):

   ClickAndMortar\ImportBundle\ClickAndMortarImportBundle::class,
   

3. Configure a Basic Import Define in config/import.php (create if missing):

   'entities' => [
       'customer_from_csv' => [
           'model' => App\Models\Customer::class,
           'unique_key' => 'id',
           'mappings' => [
               'id' => 'ID',
               'name' => 'FullName',
               'email' => 'EmailAddress',
           ],
       ],
   ],
   

4. First Use Case Create a controller method to handle file uploads:

   use ClickAndMortar\ImportBundle\Service\ImportService;
   
   public function import(Request $request, ImportService $importService)
   {
       $file = $request->file('csv_file');
       $result = $importService->import('customer_from_csv', $file->getPathname());
       return response()->json($result);
   }
   

Implementation Patterns

Workflow: CSV Import

1. File Handling

   • Use Laravel’s Request to capture uploaded files:

     $file = $request->validate([
         'csv_file' => 'required|file|csv',
     ])->file('csv_file');
     

   • Stream large files to avoid memory issues:

     $file->openFile()->fpassthru();
     

2. Mapping Strategy

   • Dynamic Mappings: Override mappings per request:

     $importService->import('customer_from_csv', $filePath, [
         'mappings' => [
             'name' => 'CustomNameColumn',
         ],
     ]);
     

   • Nested Entities: Use model relationships:

     mappings:
       address: "Address_Line1,Address_Line2"
     

     (Assumes Customer has an address relationship.)

3. Batch Processing

   • Split large imports into chunks:

     $importService->setChunkSize(100); // Process 100 records at a time
     

4. Event Listeners

   • Trigger events before/after import:

     event(new ImportStarting('customer_from_csv', $filePath));
     $result = $importService->import(...);
     event(new ImportCompleted($result));
     

Integration Tips

• Validation: Extend ClickAndMortar\ImportBundle\Validator\ValidatorInterface for custom rules.
• Logging: Use Laravel’s logging to track imports:

  \Log::info('Import started', ['entity' => 'customer_from_csv']);
  

• Queue Jobs: Offload imports to queues:

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

  (Create a job extending ShouldQueue.)

Gotchas and Tips

Pitfalls

1. Case Sensitivity

   • Column names in mappings must match the CSV header exactly (including case).
   • Fix: Normalize headers in preprocessing:

     $headers = array_map('strtolower', $csvHeaders);
     

2. Unique Key Conflicts

   • If unique_key exists in the DB, the bundle skips duplicates by default.
   • Override: Set overwrite_on_duplicate: true in config.

3. Memory Limits

   • Large XML files may hit PHP’s memory_limit.
   • Fix: Use SimpleXML with libxml_disable_entity_loader(true).

4. Entity Not Found

   • If model class is invalid, the bundle throws a RuntimeException.
   • Debug: Verify the FQCN in config/import.php.

Debugging

• Enable Verbose Logging Add to config/import.php:

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

  Logs detailed mapping and validation steps.

• Test with Small Files Use a 5-row CSV first to validate mappings before processing large datasets.

Extension Points

1. Custom Writers Override ClickAndMortar\ImportBundle\Writer\WriterInterface to support new formats (e.g., JSON):

   class JsonWriter implements WriterInterface {
       public function write(array $data, string $filePath) { ... }
   }
   

2. Pre/Post-Processors Hook into ImportEvent listeners for data transformation:

   public function onImportStarting(ImportStarting $event) {
       $event->setData(array_map(function($row) {
           return strtoupper($row['name']); // Example: Uppercase names
       }, $event->getData()));
   }
   

3. Database Transactions Wrap imports in a transaction for atomicity:

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

Config Quirks

• Default Values The bundle assumes:

  • unique_key is a column in the DB.
  • mappings use dot notation for nested attributes (e.g., address.city).
  • Fix: Explicitly define defaults in config to avoid silent failures.

• XML Namespaces For XML imports, specify namespaces in the config:

  click_and_mortar_import:
      entities:
          product_from_xml:
              model: App\Models\Product::class
              xml_namespace: "urn:example"
              mappings:
                  sku: "/ns:product/ns:sku"