Import Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require bluetea/import-bundle
   

   Add to AppKernel.php:

   new Bluetea\ImportBundle\ImportBundle(),
   

2. Configure: Update config.yml with your import settings:

   bluetea_import:
       factories: ['%kernel.root_dir%/../src/AppBundle/Factory']
       entity_manager: 'import_em'  # Optional: Use a separate EM
   

3. First Use Case: Create a CSV import factory (e.g., src/AppBundle/Factory/UserImportFactory.php):

   namespace AppBundle\Factory;
   
   use Bluetea\ImportBundle\Factory\AbstractFactory;
   
   class UserImportFactory extends AbstractFactory
   {
       protected $entityClass = 'AppBundle\Entity\User';
       protected $fields = ['username', 'email', 'role'];
   }
   

4. Trigger Import: Use a controller or command to process a CSV:

   use Bluetea\ImportBundle\Import\ImportManager;
   
   $importManager = $this->get('bluetea_import.import_manager');
   $importManager->import('user', $filePath);
   

Implementation Patterns

Workflows

1. Factory-Based Imports:

   • Extend AbstractFactory for each entity type.
   • Override processRow() to handle custom logic per row.
   • Example:

     public function processRow($row, $entity)
     {
         $entity->setPassword($this->encodePassword($row['password']));
     }
     

2. Validation:

   • Use Symfony’s Validator in processRow() or validateRow().
   • Example:

     $errors = $this->validator->validate($entity);
     if (count($errors)) {
         $this->addError($row, $errors);
     }
     

3. Bulk Operations:

   • Disable transactions for large imports:

     bluetea_import:
         flush_after_rows: 50  # Flush every 50 rows
     

4. Event-Driven:

   • Listen to import.pre_process, import.post_process, or import.error events:

     $dispatcher->addListener('import.error', function ($event) {
         $this->logger->error($event->getMessage());
     });
     

Integration Tips

• Doctrine Events: Hook into prePersist/preUpdate for additional logic.
• Queue Imports: Use Symfony Messenger or a queue system for async processing.
• Logging: Configure Monolog to track import progress:

  monolog:
      handlers:
          import:
              type: stream
              path: "%kernel.logs_dir%/import.log"
              level: debug
  

Gotchas and Tips

Pitfalls

1. Deprecated Symfony2:

   • The bundle is unmaintained (last release: 2014). Test thoroughly in a staging environment.
   • May conflict with modern Symfony (e.g., Flex, auto-wiring).

2. Memory Limits:

   • Large CSV files can exhaust memory. Use flush_after_rows or chunking:

     $importManager->setFlushAfterRows(20);
     

3. Entity Manager Isolation:

   • If using a separate import_em, ensure it’s cleared after imports:

     $importManager->getEntityManager()->clear();
     

4. CSV Parsing Quirks:

   • Default delimiter is ,. Override in factory:

     protected $delimiter = ';';
     

Debugging

• Enable Debug Mode:

  bluetea_import:
      debug: true  # Logs raw CSV data and errors
  

• Check Events:

  bin/console debug:event-dispatcher
  

  Filter for import.* events.

Extension Points

1. Custom Factories:

   • Add new file types (e.g., Excel) by extending AbstractFactory and implementing supports():

     public function supports($filePath)
     {
         return pathinfo($filePath, PATHINFO_EXTENSION) === 'xlsx';
     }
     

2. Pre/Post Hooks:

   • Override preProcess() or postProcess() in factories for global logic.

3. Custom Error Handling:

   • Extend ImportErrorHandler to redirect errors to a queue or API:

     class CustomErrorHandler extends ImportErrorHandler
     {
         public function handleError($error)
         {
             $this->apiClient->sendError($error);
         }
     }
     

4. Configuration Overrides:

   • Dynamically set options via services:

     services:
         app.import_factory:
             class: AppBundle\Factory\UserImportFactory
             calls:
                 - [setValidator, ['@validator']]