Import Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require darkilliant/import
   

   Ensure your project uses Symfony 3.4.x (not Laravel, but Symfony-based) and PHP 7.0+.

2. Enable the Bundle Add to app/AppKernel.php (Symfony) or config/bundles.php (Symfony Flex):

   new Darkilliant\ImportBundle\DarkilliantImportBundle(),
   

3. First Use Case Define a CSV import route in routing.yml:

   darkilliant_import:
       resource: "@DarkilliantImportBundle/Resources/config/routing.yml"
       prefix: /import
   

   Test with a sample CSV file (e.g., users.csv) and a form type to map fields.

Key Files to Review

• src/Darkilliant/ImportBundle/Resources/config/routing.yml: Default routes.
• src/Darkilliant/ImportBundle/Import/ImportInterface.php: Core import logic contract.
• src/Darkilliant/ImportBundle/Import/Import.php: Base import class (extend this).
• src/Darkilliant/ImportBundle/Form/Type/ImportType.php: Form type for file uploads.

Implementation Patterns

1. Custom Importer Class

Extend Darkilliant\ImportBundle\Import\Import to handle your data model:

// src/AppBundle/Import/UserImporter.php
namespace AppBundle\Import;

use Darkilliant\ImportBundle\Import\Import;
use AppBundle\Entity\User;

class UserImporter extends Import
{
    protected function transformRow(array $row): User
    {
        $user = new User();
        $user->setEmail($row['email']);
        $user->setName($row['name']);
        return $user;
    }

    protected function getEntityManager(): \Doctrine\ORM\EntityManagerInterface
    {
        return $this->container->get('doctrine')->getManager();
    }
}

2. Form Integration

Use the ImportType in a controller:

// src/AppBundle/Controller/ImportController.php
use Darkilliant\ImportBundle\Form\Type\ImportType;
use AppBundle\Import\UserImporter;

class ImportController extends Controller
{
    public function importAction(Request $request)
    {
        $importer = new UserImporter($this->get('doctrine'));
        $form = $this->createForm(ImportType::class, $importer, [
            'csv_file' => 'users.csv',
        ]);

        $form->handleRequest($request);
        if ($form->isSubmitted() && $form->isValid()) {
            $importer->run();
            $this->addFlash('success', 'Import completed!');
        }

        return $this->render('import/index.html.twig', ['form' => $form->createView()]);
    }
}

3. Validation & Mapping

Define validation rules in transformRow() and handle errors:

protected function transformRow(array $row): User
{
    if (empty($row['email'])) {
        throw new \RuntimeException('Email is required.');
    }

    $user = new User();
    $user->setEmail($row['email']);
    return $user;
}

4. Batch Processing

For large datasets, implement chunking:

protected function persistEntity($entity): void
{
    $this->entityManager->persist($entity);
    if ($this->getCount() % 20 === 0) {
        $this->entityManager->flush();
        $this->entityManager->clear();
    }
}

5. Event Listeners

Extend functionality via events (e.g., pre/post-import):

// src/AppBundle/EventListener/ImportListener.php
use Darkilliant\ImportBundle\Event\ImportEvent;

class ImportListener
{
    public function onImport(ImportEvent $event)
    {
        if ($event->getImport()->getClass() === User::class) {
            // Log or notify
        }
    }
}

Register in services.yml:

services:
    AppBundle\EventListener\ImportListener:
        tags:
            - { name: kernel.event_listener, event: darkilliant.import, method: onImport }

Gotchas and Tips

Pitfalls

1. Symfony Dependency

   • This package is Symfony-only (not Laravel). Use Symfony’s EventDispatcher or Doctrine patterns if migrating to Laravel.
   • Workaround: Wrap logic in a Laravel service and manually handle file uploads/validation.

2. Outdated Codebase

   • Last release: 2018. Test thoroughly for edge cases (e.g., UTF-8 encoding, large files).
   • Tip: Fork and update dependencies (e.g., symfony/validator, doctrine/orm).

3. No Laravel Adapter

   • No built-in Laravel support. Expect manual integration (e.g., use Laravel’s Request for file handling).

4. Memory Limits

   • Large CSV files may hit PHP’s memory_limit. Use chunking or fgetcsv() for streaming.

Debugging Tips

1. Enable Verbose Logging Add to config/packages/monolog.yaml:

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

2. Validate CSV Structure Use League\Csv\Reader to pre-validate files before import:

   $csv = Reader::createFromPath($file->getPathname(), 'r');
   $csv->setHeaderOffset(0);
   foreach ($csv as $record) {
       if (!isset($record['email'])) {
           throw new \RuntimeException('Invalid CSV format.');
       }
   }
   

3. Doctrine Flush Issues If entities aren’t saving, check:

   • entityManager->flush() is called.
   • No transactions are open ($em->getConnection()->beginTransaction()).

Extension Points

1. Custom File Parsers Override Darkilliant\ImportBundle\Import\Import::parseFile() to support Excel/JSON:

   protected function parseFile(SplFileInfo $file): array
   {
       $csv = Reader::createFromPath($file->getPathname(), 'r');
       return iterator_to_array($csv);
   }
   

2. Progress Tracking Add a progress bar using Symfony’s ProgressComponent:

   use Symfony\Component\Console\Helper\ProgressBar;
   
   $progress = new ProgressBar($this->output);
   $progress->start($this->getTotalRows());
   
   foreach ($this->getRows() as $row) {
       $this->transformRow($row);
       $progress->advance();
   }
   $progress->finish();
   

3. Rollback on Failure Wrap imports in a Doctrine transaction:

   $this->entityManager->beginTransaction();
   try {
       foreach ($this->getRows() as $row) {
           $this->persistEntity($this->transformRow($row));
       }
       $this->entityManager->flush();
       $this->entityManager->commit();
   } catch (\Exception $e) {
       $this->entityManager->rollback();
       throw $e;
   }
   

Laravel Workarounds

If using in Laravel:

1. File Uploads Replace ImportType with Laravel’s FormRequest:

   use Illuminate\Http\Request;
   
   public function import(Request $request)
   {
       $file = $request->file('csv_file');
       $importer = new UserImporter($this->app->make('db'));
       $importer->setFile($file->getPathname());
       $importer->run();
   }
   

2. Doctrine Alternative Use Laravel’s Eloquent or a Symfony bridge (e.g., spatie/laravel-symfony-support).

3. Event System Use Laravel’s Events instead of Symfony’s EventDispatcher.