Dataexporter Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require antqa/dataexporter-bundle
   

   Register the bundle in config/bundles.php (Symfony 5+ auto-discovers it).

2. First Export (CSV):

   use AntQa\DataExporterBundle\Exporter\CsvExporter;
   use AntQa\DataExporterBundle\Exporter\ExporterInterface;
   
   $exporter = new CsvExporter();
   $data = [['id' => 1, 'name' => 'Item 1'], ['id' => 2, 'name' => 'Item 2']];
   $csv = $exporter->export($data);
   file_put_contents('export.csv', $csv);
   

3. First Use Case: Export a Doctrine Collection to CSV via a controller:

   use AntQa\DataExporterBundle\Exporter\CsvExporter;
   use Symfony\Component\HttpFoundation\Response;
   
   public function exportAction(ExporterInterface $exporter, EntityManagerInterface $em): Response
   {
       $data = $em->getRepository(Product::class)->findAll();
       $csv = $exporter->export($data, ['id', 'name', 'price']);
       return new Response($csv, 200, ['Content-Type' => 'text/csv']);
   }
   

Key Entry Points

• Exporters: CsvExporter, XmlExporter, JsonExporter, XlsExporter, HtmlExporter (all implement ExporterInterface).
• Configuration: Minimal; defaults work out-of-the-box. Override via DI or config/packages/antqa_data_exporter.yaml.
• Twig Integration: Use {{ dump(data) | export_to_csv }} in templates (if Twig extension is enabled).

Implementation Patterns

Core Workflow

1. Data Preparation:

   • Normalize data to arrays (Doctrine Collection → array via map() or toArray()).
   • Define export fields explicitly (e.g., ['id', 'name']) or rely on auto-detection (risky for nested objects).

2. Exporter Selection:

   // Dependency Injection (recommended)
   public function __construct(
       private CsvExporter $csvExporter,
       private XlsExporter $xlsExporter
   ) {}
   
   // Runtime selection
   $exporter = match ($format) {
       'csv' => $csvExporter,
       'xls' => $xlsExporter,
       default => throw new \InvalidArgumentException('Unsupported format'),
   };
   

3. Export Execution:

   • To File:

     $exporter->exportToFile($data, 'path/to/export.csv');
     

   • To Response (Symfony):

     return new Response(
         $exporter->export($data),
         200,
         ['Content-Type' => 'text/csv', 'Content-Disposition' => 'attachment; filename="export.csv"']
     );
     

   • To Memory (for APIs):

     $csv = $exporter->export($data);
     return json_encode(['data' => base64_encode($csv)]);
     

4. Custom Headers/Footers:

   $exporter->setHeader(['Custom Header']);
   $exporter->setFooter(['Custom Footer']);
   $exporter->export($data);
   

Advanced Patterns

• Dynamic Field Mapping:

  $exporter->setFieldMapping([
      'product_id' => 'id',
      'product_name' => 'name',
      'formatted_price' => function ($item) {
          return '$' . number_format($item['price'], 2);
      },
  ]);
  

• Batch Processing:

  $chunkSize = 1000;
  $offset = 0;
  while ($products = $em->getRepository(Product::class)->findBy([], [], $chunkSize, $offset)) {
      $exporter->exportToFile($products, "export_$offset.csv");
      $offset += $chunkSize;
  }
  

• Event Listeners: Extend functionality via Symfony events (e.g., pre-export data transformation):

  // config/services.yaml
  services:
      App\EventListener\ExportListener:
          tags:
              - { name: kernel.event_listener, event: antqa.data_exporter.pre_export, method: onPreExport }
  

• Twig Integration:

  {# Export a collection to CSV via Twig filter #}
  <a href="{{ path('export') | export_to_csv(data) }}">Download CSV</a>
  

Gotchas and Tips

Pitfalls

1. Memory Limits:

   • Large datasets (e.g., 100K+ rows) may hit memory limits when exporting to memory.
   • Fix: Use exportToFile() or stream data in chunks.

2. Nested Objects:

   • Auto-detection fails for nested objects (e.g., User::getAddress()).
   • Fix: Flatten data manually or use setFieldMapping():

     $exporter->setFieldMapping([
         'address_city' => function ($user) {
             return $user->getAddress()->getCity();
         },
     ]);
     

3. Excel (XLS) Quirks:

   • XlsExporter uses phpoffice/phpspreadsheet under the hood.
   • Gotchas:
     • Complex formulas may break without proper escaping.
     • Large files (>1MB) may time out. Use setOutputEncoding('UTF-8') for non-ASCII data.
   • Tip: Prefer XlsxExporter (if available) for modern Excel files.

4. XML/HTML Escaping:

   • Special characters (<, >, &) in data may break XML/HTML output.
   • Fix: Use setEscapeHtml(true) for HTML or ensure data is sanitized.

5. Symfony 5.4+ Compatibility:

   • The bundle supports Symfony 4.4–5.4 but lacks explicit Symfony 6+ tests.
   • Tip: Test thoroughly if upgrading to Symfony 6+.

Debugging Tips

• Enable Verbose Output:

  $exporter->setDebug(true); // Logs raw data before export
  

• Check Headers/Footers: Misplaced headers/footers can corrupt CSV/Excel. Verify with:

  $exporter->setHeader([]); // Reset if needed
  

• Validate Data Structure: Use var_dump($exporter->getExportedData()) to inspect the final array before export.

Extension Points

1. Custom Exporters: Extend AbstractExporter to add new formats (e.g., PDF via Dompdf):

   class PdfExporter extends AbstractExporter
   {
       protected function exportData(array $data): string
       {
           $dompdf = new \Dompdf\Dompdf();
           $dompdf->loadHtml($this->renderHtml($data));
           return $dompdf->output();
       }
   }
   

2. Override Default Exporters: Bind custom exporters in config/services.yaml:

   services:
       AntQa\DataExporterBundle\Exporter\CsvExporter:
           class: App\Exporter\CustomCsvExporter
   

3. Pre/Post-Export Events: Listen for antqa.data_exporter.pre_export and antqa.data_exporter.post_export:

   public function onPreExport(PreExportEvent $event)
   {
       $event->setData($this->transformData($event->getData()));
   }
   

4. Configuration Overrides: Override defaults in config/packages/antqa_data_exporter.yaml:

   antqa_data_exporter:
       default_format: 'xls' # Override default exporter
       csv:
           delimiter: ';' # Custom CSV delimiter
           enclosure: '"'
   

Performance Tips

• Avoid Auto-Detection: Explicitly define fields (setFieldMapping()) for better performance and predictability.
• Stream Large Files: For CSV/Excel, implement chunked writing:

  $handle = fopen('large_export.csv', 'w');
  foreach ($data as $row) {
      fputcsv($handle, $row);
  }
  fclose($handle);
  

• Cache Exporters: Reuse exporter instances (they are stateless but may have overhead):

  // services.yaml
  services:
      App\Service\ExportService:
          arguments:
              $csvExporter: '@AntQa\DataExporterBundle\Exporter\CsvExporter'