Content Import Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require contextualcode/content-import
   

   Add the bundle to config/bundles.php (Symfony) or config/app.php (Laravel):

   ContextualCode\ContentImportBundle\ContentImportBundle::class => ['all' => true],
   

2. Basic Configuration Publish the default config:

   php artisan vendor:publish --tag=content-import-config
   

   Key settings to review:

   • default_import_path (where to store import files)
   • supported_formats (e.g., ['csv', 'json', 'xml'])
   • mapping_strategies (how to map imported data to your models)

3. First Use Case: CSV Import Create a CSV file (users_import.csv) with headers matching your User model fields:

   email,name,role
   [email protected],John Doe,admin
   

   Run the import command:

   php artisan import:run --file=users_import.csv --model=App\Models\User
   

Implementation Patterns

Workflow: Structured Data Migration

1. Pre-Import Validation Extend ContentImportBundle\Validator\ImportValidator to add custom rules:

   use ContentImportBundle\Validator\Constraints as ImportAssert;
   
   /**
    * @ImportAssert\FileExists(path="/path/to/import")
    * @ImportAssert\ValidCSV(delimiter=",")
    */
   public function validateImport()
   {
       // Custom logic
   }
   

2. Mapping Strategies Define how imported data maps to your Eloquent models:

   // config/packages/contextualcode_content_import.yaml
   mapping_strategies:
       App\Models\User:
           - { source: 'email', target: 'email', type: 'string' }
           - { source: 'role', target: 'role', type: 'enum', options: ['admin', 'user'] }
   

3. Chunked Processing For large datasets, use chunking in your service:

   $importer = $this->container->get('content_import.importer');
   $importer->import($filePath, User::class, [
       'chunk_size' => 100,
       'on_chunk' => function ($chunk) {
           // Process chunk (e.g., log, validate)
       }
   ]);
   

4. Post-Import Actions Hook into events to trigger actions after import:

   // In a service provider
   $this->app->booted(function () {
       event(new ContentImportEvents\PostImport(User::class, $importedCount));
   });
   

Integration Tips

• Laravel Scout Integration Reindex search after import:

  $importer->import($filePath, Product::class)->then(function () {
      Product::reindex();
  });
  

• Queue Large Imports Dispatch a job for background processing:

  dispatch(new ImportContentJob($filePath, User::class));
  

• Custom Format Support Extend ContentImportBundle\Reader\FileReaderInterface for new formats (e.g., Excel):

  class ExcelReader implements FileReaderInterface
  {
      public function read(string $filePath): array
      {
          return Excel::toArray(new UserImport, $filePath);
      }
  }
  

Gotchas and Tips

Pitfalls

1. Field Mismatches

   • Issue: Import fails silently if CSV headers don’t match config.
   • Fix: Enable debug mode in config:

     debug: true
     

     Check logs for MappingError exceptions.

2. Memory Limits

   • Issue: Large CSV files may hit PHP memory limits.
   • Fix: Use chunk_size in config or stream processing:

     chunk_size: 50
     stream: true
     

3. Transaction Rollbacks

   • Issue: Partial imports leave data inconsistent.
   • Fix: Wrap imports in a transaction:

     DB::transaction(function () use ($importer) {
         $importer->import($filePath, User::class);
     });
     

4. Timezone Handling

   • Issue: Date fields may be misinterpreted.
   • Fix: Explicitly set timezone in config:

     timezone: 'UTC'
     

Debugging Tips

• Dry Run Mode Test mappings without writing to DB:

  php artisan import:run --dry-run --file=users.csv
  

• Log Imports Enable logging in config/packages/contextualcode_content_import.yaml:

  logging:
      enabled: true
      channel: single
  

• Custom Error Handling Override the default error handler:

  $importer->setErrorHandler(function ($error) {
      \Log::error("Import Error: {$error->getMessage()}");
      // Custom logic (e.g., notify admin)
  });
  

Extension Points

1. Custom Validators Create a validator for domain-specific rules:

   class UniqueEmailValidator extends ImportValidator
   {
       public function validateEmail($email, $row)
       {
           return !User::where('email', $email)->exists();
       }
   }
   

2. Pre/Post-Import Hooks Use events to extend functionality:

   // Listen for pre-import
   ContentImportEvents::PRE_IMPORT->listen(function ($event) {
       $event->setOption('validate_emails', true);
   });
   

3. Dynamic Model Mapping Resolve models dynamically (e.g., from a config file):

   $mapping = config("import.mappings.{$event->getModel()}");