Import Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require ccetc/import-bundle
   

   Add to config/bundles.php (Symfony) or config/app.php (Laravel via bridge):

   return [
       // ...
       CCETC\ImportBundle\CCETCImportBundle::class => ['all' => true],
   ];
   

2. Basic Configuration Create a YAML config file (e.g., config/imports.yaml):

   imports:
       users:
           file: 'path/to/users.xlsx'
           model: App\Models\User
           sheet: 'Sheet1'
           headers: ['name', 'email', 'role']
           batch_size: 100
   

3. First Use Case Trigger an import via CLI:

   php artisan import:run users
   

   Or programmatically:

   use CCETC\ImportBundle\ImportManager;
   
   $manager = app(ImportManager::class);
   $manager->run('users');
   

Implementation Patterns

Workflow Integration

1. Scheduled Imports Use Laravel’s task scheduler (app/Console/Kernel.php) to run imports nightly:

   protected function schedule(Schedule $schedule)
   {
       $schedule->command('import:run users')->daily();
   }
   

2. Event-Driven Imports Listen for file uploads (e.g., via HasFile trait) and trigger imports:

   use CCETC\ImportBundle\Events\ImportStarted;
   
   event(new ImportStarted('users', $filePath));
   

3. Chunked Processing For large datasets, leverage batch_size in config and handle chunk events:

   imports:
       products:
           batch_size: 500
           on_batch_complete: App\Listeners\LogBatchProgress
   

Common Patterns

• Validation Extend CCETC\ImportBundle\Validator\BaseValidator to add custom rules:

  class UserValidator extends BaseValidator
  {
      public function rules()
      {
          return [
              'email' => 'required|email|unique:users',
              'role'  => 'in:admin,user,guest',
          ];
      }
  }
  

  Register in config:

  imports:
      users:
          validator: App\Validator\UserValidator
  

• Mapping Headers Use header_mapping to rename columns:

  imports:
      orders:
          headers: ['order_id', 'customer_name', 'total']
          header_mapping:
              order_id: id
              customer_name: user.name
  

• Post-Import Actions Hook into ImportCompleted event:

  public function handle(ImportCompleted $event)
  {
      // Send notification, update cache, etc.
  }
  

Gotchas and Tips

Pitfalls

1. Memory Limits

   • Large XLS files may hit PHP’s memory_limit. Increase it temporarily:

     php -d memory_limit=1G artisan import:run users
     

   • Use batch_size to process in chunks.

2. Sheet Selection

   • The bundle defaults to the first sheet. Explicitly define sheet in config to avoid ambiguity:

     sheet: 'Invoices 2023'
     

3. Case Sensitivity

   • Header names in YAML are case-sensitive. Match them exactly with your XLS column names.

4. Model Mass Assignment

   • Ensure your model’s $fillable includes all imported fields. Use $guarded = [] if needed.

5. Timezones

   • Dates in XLS may be parsed incorrectly. Normalize in a validator:

     public function rules()
     {
         return [
             'created_at' => 'date_format:Y-m-d\TH:i:s',
         ];
     }
     

Debugging Tips

• Dry Run Mode Test without saving to DB:

  php artisan import:run users --dry-run
  

  Outputs validation errors and skipped rows.

• Logging Enable verbose output:

  php artisan import:run users --verbose
  

  Or configure Monolog in config/imports.yaml:

  logging:
      enabled: true
      channel: single
  

• Common Errors

  Error	Solution
  Sheet not found	Verify sheet name in config matches XLS.
  Column not found	Check headers in config vs. XLS columns.
  MassAssignmentException	Add fields to model’s $fillable.
  Memory exhausted	Reduce batch_size or increase memory.

Extension Points

1. Custom Importers Extend CCETC\ImportBundle\Importer\BaseImporter for non-XLS files (CSV, JSON):

   class JsonImporter extends BaseImporter
   {
       protected function parseFile($filePath)
       {
           return json_decode(file_get_contents($filePath), true);
       }
   }
   

   Register in config:

   imports:
       api_data:
           importer: App\Importer\JsonImporter
   

2. Pre/Post-Processors Add logic before/after row processing:

   imports:
       users:
           pre_processor: App\Processor\SanitizeInputProcessor
           post_processor: App\Processor\UpdateLastImportedAt
   

3. Custom Validators Override default validation (e.g., for API keys):

   class ApiKeyValidator extends BaseValidator
   {
       public function validateApiKey($value)
       {
           return strlen($value) === 32;
       }
   }
   

   Attach to a field:

   imports:
       api_keys:
           validator: App\Validator\ApiKeyValidator
           rules:
               key: 'required|validateApiKey'