Ux Export Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require akyos/ux-export
   

   For non-Flex projects, manually enable the bundle in config/bundles.php:

   Akyos\UXExportBundle\UXExportBundle::class => ['all' => true],
   

2. Mark an Entity Annotate your entity with #[Exportable] and define properties with #[ExportableProperty]:

   #[Exportable]
   class User {
       #[ExportableProperty(groups: ['export'])]
       public string $name;
   }
   

3. Integrate with Live Component Add ComponentWithExportTrait to your Live Component and implement getData():

   #[AsLiveComponent]
   class UserExportComponent {
       use ComponentWithExportTrait;
       public string $class = User::class;
       public ?string $exportGroup = 'export';
   
       public function getData(): iterable {
           return $this->userRepository->findAll();
       }
   }
   

4. Trigger Export Add a button in your Twig template:

   <button {{ live_action('export') }}>Export</button>
   

Implementation Patterns

Common Workflows

1. Dynamic Group Selection Use $exportGroup to switch between predefined export configurations:

   public ?string $exportGroup = 'admin'; // Overrides default
   

2. Nested Data Export Extract fields from related entities:

   #[ExportableProperty(groups: ['export'], fields: ['name', 'email'])]
   private ?Customer $customer;
   

3. Many-to-Many Handling Choose between row duplication (MODE_LINES) or separate sheets (MODE_SHEET):

   #[ExportableProperty(groups: ['export'], manyToMany: ExportableProperty::MODE_SHEET)]
   private Collection $roles;
   

4. Method-Based Export Export computed values:

   #[ExportableProperty(groups: ['export'], name: 'Full Name', position: 1)]
   public function getFullName(): string { ... }
   

5. CSV vs. XLSX Toggle formats via $exportType:

   public string $exportType = 'csv'; // Default is 'xlsx'
   

Integration Tips

• QueryBuilder Support: Pass a QueryBuilder or Query in getData() for efficient exports.
• Custom Filenames: Override $exportFileName for user-friendly filenames:

  public string $exportFileName = 'custom_users_export';
  

• Conditional Export Logic: Use #[Groups] as a fallback for ExportableProperty:

  #[ExportableProperty(groups: ['export'])]
  #[Groups(['export'])]
  public string $legacyField;
  

Gotchas and Tips

Pitfalls

1. Attribute Conflicts

   • Ensure #[ExportableProperty] groups match the $exportGroup in your component.
   • Fix: Validate groups in getData() or use a default group.

2. Circular References

   • Deeply nested fields may cause infinite loops.
   • Fix: Limit recursion or use #[Groups] to restrict exported properties.

3. Memory Limits

   • Large datasets may hit PHP memory limits.
   • Fix: Use chunked queries or increase memory_limit temporarily.

4. CSV Zip Behavior

   • Zipping triggers only if manyToMany: MODE_SHEET is used.
   • Fix: Set $exportType = 'csv' and ensure no MODE_SHEET properties exist for single-file output.

5. Live Component State

   • Export actions reset component state. Preserve critical filters in getData().

Debugging

• Check Generated Files: Verify exports in var/export/ (default path).
• Log Exporter Errors: Enable debug mode to catch serialization issues:

  # config/packages/dev/ux_export.yaml
  ux_export:
      debug: true
  

• Validate Metadata: Use Symfony’s Serializer to test entity configuration:

  $serializer->serialize($entity, 'json', ['groups' => ['export']]);
  

Extension Points

1. Custom Exporters Extend ExporterService or CsvExporterService for format-specific logic:

   class CustomExporter extends ExporterService {
       protected function customizeWorksheet(Worksheet $sheet): void { ... }
   }
   

2. Post-Export Actions Hook into the ux_export.post_export event to modify files:

   $eventDispatcher->addListener('ux_export.post_export', function (PostExportEvent $event) {
       $event->getFile()->setContent(gzdeflate($event->getFile()->getContent()));
   });
   

3. Dynamic Paths Override the export path per-component:

   public string $exportPath = '%kernel.project_dir%/custom/exports/';
   

4. Fallback Serialization Handle unsupported types with a custom normalizer:

   #[ExportableProperty(groups: ['export'])]
   public DateTimeInterface $createdAt;
   
   // In services.yaml:
   Symfony\Component\Serializer\Normalizer\NormalizerInterface:
       class: App\Normalizer\DateTimeNormalizer
   

```markdown
### Pro Tips
- **Performance**: Use DTOs for complex exports to avoid loading entire entities.
- **Localization**: Set headers dynamically:
  ```php
  #[ExportableProperty(groups: ['export'], name: $this->translator->trans('user.name'))]
  public string $name;

• Testing: Mock ExporterService in unit tests:

  $this->mockBuilder(ExporterService::class)
       ->method('export')
       ->willReturn('/path/to/mock/file.xlsx');