Sonata Import Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require doctrs/sonata-import-bundle white-october/pagerfanta-bundle
   

   Register bundles in AppKernel.php:

   new Doctrs\SonataImportBundle\DoctrsSonataImportBundle(),
   new WhiteOctober\PagerfantaBundle\WhiteOctoberPagerfantaBundle(),
   

2. Doctrine ORM Mapping: Add to config.yml:

   doctrine:
       orm:
           entity_managers:
               default:
                   mappings:
                       DoctrsSonataImportBundle: ~
   

3. Basic Configuration: Define import mappings in config.yml:

   doctrs_sonata_import:
       mappings:
           - { name: date, class: doctrs.type.datetime }
           - { name: datetime, class: doctrs.type.datetime }
   

4. First Use Case: Extend a Sonata Admin class to enable imports:

   use Doctrs\SonataImportBundle\Admin\AdminImportExtension;
   
   class YourAdmin extends AbstractAdmin
   {
       protected function configureSideMenu()
       {
           $this->menu->addChild('Import', 'fa-upload');
       }
   
       protected function configure()
       {
           $this->addImportExtension();
       }
   }
   

Implementation Patterns

Workflow Integration

1. Admin Extension: Use AdminImportExtension to add import functionality to any Sonata Admin:

   $this->addImportExtension([
       'template' => '@DoctrsSonataImport/import.html.twig',
       'mappings' => [
           'date' => 'doctrs.type.datetime',
           'status' => 'doctrs.type.choice',
       ],
   ]);
   

2. Custom Mapping Classes: Extend or create custom mapping classes (e.g., for autocomplete fields):

   # config.yml
   doctrs_sonata_import:
       mappings:
           - { name: city, class: AppBundle\Form\Mapping\CityAutocomplete }
   

3. Validation & Error Handling: Validate imports via Symfony’s validator or custom logic:

   $this->addImportExtension([
       'validator' => $this->getValidator(),
   ]);
   

4. Batch Processing: Use Pagerfanta for large imports:

   $this->addImportExtension([
       'pagerfanta' => true,
   ]);
   

Common Use Cases

• CSV/Excel Imports: Leverage Sonata’s built-in file upload and process via DoctrsSonataImportBundle.
• Data Migration: Useful for bulk updates or initial data seeding.
• User-Generated Imports: Allow non-technical users to upload data via the admin panel.

Gotchas and Tips

Pitfalls

1. Outdated Dependencies:

   • The bundle hasn’t been updated since 2017. Test thoroughly with your Symfony/Laravel (via Symfony Bridge) version.
   • Workaround: Fork and update dependencies (e.g., sonata-admin-bundle, doctrine/orm).

2. Missing Pagerfanta:

   • Forgetting to install white-october/pagerfanta-bundle will break pagination in imports.
   • Fix: Ensure both bundles are registered in AppKernel.php.

3. Mapping Class Errors:

   • Custom mapping classes must extend Doctrs\SonataImportBundle\Form\Mapping\AbstractMapping.
   • Debug: Check var/log/dev.log for ClassNotFoundException if mappings fail.

4. CSRF & Security:

   • The bundle assumes standard Sonata Admin security. Add custom validation for sensitive imports:

     $this->addImportExtension([
         'access_control' => 'ROLE_ADMIN',
     ]);
     

Debugging Tips

• Enable Debug Mode:

  # config.yml
  monolog:
      handlers:
          main:
              level: debug
  

• Check Twig Templates: Override the default template (@DoctrsSonataImport/import.html.twig) for custom UI:

  {% extends '@SonataAdmin/CRUD/base_edit.html.twig' %}
  {% block import_form %}
      {{ form_start(form) }}
      <input type="file" name="import_file" />
      {{ form_end(form) }}
  {% endblock %}
  

Extension Points

1. Custom Importers: Create a service to handle post-import logic:

   // services.yml
   app.import_handler:
       class: AppBundle\Service\ImportHandler
       tags:
           - { name: sonata.admin.import.handler }
   

2. Event Listeners: Listen to sonata.admin.import.pre and sonata.admin.import.post events:

   $eventDispatcher->addListener('sonata.admin.import.pre', function ($event) {
       // Pre-import logic
   });
   

3. Override Mapping Classes: Extend existing classes (e.g., doctrs.type.datetime) for custom logic:

   class CustomDateMapping extends \Doctrs\SonataImportBundle\Form\Mapping\DateMapping
   {
       public function transform($value)
       {
           return parent::transform($value)->format('Y-m-d H:i:s');
       }
   }