Mathielen Import Engine Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation Add the bundle to your composer.json:

   composer require avtonom/mathielen-import-engine-bundle
   

   Enable the bundle in config/bundles.php:

   return [
       // ...
       Avtonom\MathielenImportEngineBundle\AvtonomMathielenImportEngineBundle::class => ['all' => true],
   ];
   

2. First Use Case: Basic CSV Import Define a simple import class (e.g., src/Import/UserImport.php):

   namespace App\Import;
   
   use Avtonom\MathielenImportEngineBundle\Import\ImportInterface;
   use Avtonom\MathielenImportEngineBundle\Import\ImportResult;
   use App\Entity\User;
   
   class UserImport implements ImportInterface
   {
       public function import(array $data): ImportResult
       {
           $user = new User();
           $user->setEmail($data['email']);
           $user->setName($data['name']);
           // Save logic (e.g., EntityManager) here
   
           return new ImportResult(true, 'User imported successfully');
       }
   }
   

3. Run the Import Use the Symfony console command:

   php bin/console avtonom:import:run UserImport /path/to/file.csv
   

4. Key Files to Explore

   • src/Resources/config/services.xml: Bundle configuration.
   • src/Import/ImportInterface.php: Core interface for imports.
   • src/Command/ImportCommand.php: CLI entry point.

Implementation Patterns

Workflows

1. Structured Import Pipeline

   • Mapping: Use ImportInterface to map CSV rows to entities/arrays.
   • Validation: Implement validate() in your import class to reject malformed data early.
   • Batch Processing: Leverage the engine’s built-in batching for large files:

     $this->setBatchSize(100); // In your import class constructor
     

2. Export Workflow

   • Extend Avtonom\MathielenImportEngineBundle\Export\ExportInterface for exports.
   • Example: Export users to CSV:

     namespace App\Export;
     
     use Avtonom\MathielenImportEngineBundle\Export\ExportInterface;
     use App\Entity\UserRepository;
     
     class UserExport implements ExportInterface
     {
         private $userRepository;
     
         public function __construct(UserRepository $userRepository)
         {
             $this->userRepository = $userRepository;
         }
     
         public function export(): array
         {
             return $this->userRepository->findAll();
         }
     
         public function getHeaders(): array
         {
             return ['id', 'email', 'name'];
         }
     }
     

   • Run via CLI:

     php bin/console avtonom:export:run UserExport /path/to/output.csv
     

3. Dependency Injection

   • Inject services (e.g., EntityManager, Validator) into your import/export classes.
   • Register custom services in config/services.yaml:

     services:
         App\Import\UserImport:
             arguments:
                 $entityManager: '@doctrine.orm.entity_manager'
     

4. Event-Driven Extensions

   • Listen to import.start, import.end, or row.processed events via Symfony’s event dispatcher:

     $dispatcher->addListener('import.start', function () {
         // Pre-import logic (e.g., log start time)
     });
     

Integration Tips

• Doctrine ORM: Use EntityManager to persist entities during import.
• Validation: Integrate Symfony’s Validator to validate rows before processing:

  use Symfony\Component\Validator\Validator\ValidatorInterface;
  
  public function __construct(ValidatorInterface $validator)
  {
      $this->validator = $validator;
  }
  
  public function import(array $data): ImportResult
  {
      $errors = $this->validator->validate($data);
      if (count($errors) > 0) {
          return new ImportResult(false, (string) $errors);
      }
      // Proceed with import
  }
  

• Logging: Use Monolog to log import progress or errors:

  use Psr\Log\LoggerInterface;
  
  public function __construct(LoggerInterface $logger)
  {
      $this->logger = $logger;
  }
  

Gotchas and Tips

Pitfalls

1. PHP Version Compatibility

   • The package requires PHP 5.5+, but modern Laravel (8+) uses PHP 7.4+. Test thoroughly if using older PHP versions.
   • Fix: Use a PHP 7.4+ compatible fork or container (e.g., Docker).

2. Symfony Version Mismatch

   • The bundle targets Symfony 2.4–3.0, which may conflict with Laravel’s Symfony components.
   • Fix: Override or extend the bundle’s services in config/packages/avtonom_mathielen_import.yaml:

     imports:
         resources:
             - "%kernel.project_dir%/vendor/avtonom/mathielen-import-engine-bundle/src/Resources/config/services.xml"
     parameters:
         avtonom_mathielen_import.engine.class: App\Service\CustomImportEngine
     

3. Memory Limits

   • Large CSV files may exhaust memory during import.
   • Fix: Process files in chunks or use streaming:

     $this->setChunkSize(500); // Process 500 rows at a time
     

4. Namespace Collisions

   • The bundle’s ImportInterface may conflict with Laravel’s Illuminate\Support\Collection or other Import classes.
   • Fix: Use fully qualified namespaces or alias the bundle’s classes:

     use Avtonom\MathielenImportEngineBundle\Import\ImportInterface as AvtonomImportInterface;
     

5. Missing Error Handling

   • The bundle lacks detailed error logging for failed imports.
   • Fix: Extend ImportResult or wrap imports in try-catch blocks:

     try {
         $result = $this->import($data);
     } catch (\Exception $e) {
         return new ImportResult(false, $e->getMessage());
     }
     

Debugging

1. Enable Verbose Output Run commands with -v or -vv for debugging:

   php bin/console avtonom:import:run UserImport file.csv -vv
   

2. Check Event Listeners Ensure your event listeners are registered in config/services.yaml:

   services:
       App\EventListener\ImportListener:
           tags:
               - { name: kernel.event_listener, event: import.start, method: onImportStart }
   

3. Validate CSV Format Use tools like CSVLint to pre-validate files before import.

Extension Points

1. Custom File Parsers Extend Avtonom\MathielenImportEngineBundle\Parser\ParserInterface to support formats like JSON or XML:

   class JsonParser implements ParserInterface
   {
       public function parse(string $filePath): array
       {
           return json_decode(file_get_contents($filePath), true);
       }
   }
   

   Register the parser in services.yaml:

   services:
       App\Parser\JsonParser:
           tags:
               - { name: avtonom_mathielen_import.parser }
   

2. Database Transactions Wrap imports in transactions to ensure data consistency:

   use Doctrine\DBAL\Connection;
   
   public function __construct(Connection $connection)
   {
       $this->connection = $connection;
   }
   
   public function import(array $data): ImportResult
   {
       $this->connection->beginTransaction();
       try {
           // Import logic
           $this->connection->commit();
           return new ImportResult(true, 'Import successful');
       } catch (\Exception $e) {
           $this->connection->rollBack();
           return new ImportResult(false, $e->getMessage());
       }
   }
   

3. Progress Tracking Add progress callbacks to monitor long-running imports:

   public function import(array $data): ImportResult
   {
       $this->dispatcher->dispatch('row.processed', new RowProcessedEvent($data));
       // ...
   }
   

   Listen for events in a controller or command:

   $dispatcher->addListener('row.processed', function (RowProcessedEvent $event) {
       echo "Processed row: " . $event->getRow() . "\n";
   });
   

4. Custom Result Formats Extend ImportResult to include additional metadata (e.g., row counts, stats):

   class ExtendedImportResult extends ImportResult
   {
       private $rowCount;
       private $errorsByRow;
   
       public function __construct(bool $success, string $message, int $rowCount, array $errorsByRow)
       {
           parent::__construct($success, $message);
           $this->rowCount = $