Xporter Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require aquis/xporter-bundle:*@dev
   

   Ensure your config/bundles.php includes:

   return [
       // ...
       Aquis\XporterBundle\XporterBundle::class => ['all' => true],
   ];
   

2. First Export Use the CLI command to export a single entity (e.g., User) to YAML:

   php bin/console xporter:export User
   

   Output: var/exports/User_[timestamp].yml

3. First Import Import the generated YAML back into the database:

   php bin/console xporter:import var/exports/User_[timestamp].yml
   

Key Files to Review

• Command Reference: vendor/aquis/xporter-bundle/src/Command/ for ExportCommand and ImportCommand.
• Configuration: Check config/packages/xporter.yaml (if auto-generated) for customization options.
• Fixtures Format: Inspect the generated YAML to understand the structure (e.g., nested relations, metadata).

Implementation Patterns

Workflow: Fixture Management

1. Export Workflow

   • Selective Export: Filter records by adding options:

     php bin/console xporter:export User --limit=10 --where="active=1"
     

   • Relation Handling: Use --with-relations to include associated entities (e.g., User with Address):

     php bin/console xporter:export User --with-relations=address
     

   • Output Path: Override default path with --output-dir=/custom/path.

2. Import Workflow

   • Partial Imports: Use --append to avoid conflicts:

     php bin/console xporter:import fixtures/user.yml --append
     

   • Validation: Add --validate to check YAML syntax before import.

3. Integration with Tests

   • Export test data once, then reuse across test suites:

     php bin/console xporter:export User --env=test > tests/fixtures/users.yml
     

   • Load fixtures in phpunit.xml:

     <env name="KERNEL_CLASS" value="App\Kernel"/>
     <env name="SYMFONY_DEPRECATIONS_HELPER" value="weak"/>
     <env name="APP_ENV" value="test"/>
     <env name="APP_DEBUG" value="true"/>
     <env name="XPORTER_IMPORT_FILE" value="%kernel.project_dir%/tests/fixtures/users.yml"/>
     

Advanced Patterns

• Custom Exporters: Extend the bundle by creating a custom exporter service:

  // src/Service/CustomExporter.php
  class CustomExporter implements ExporterInterface {
      public function export(EntityManager $em, string $entityClass, array $options): string {
          // Custom logic (e.g., transform data before export)
          return $yamlContent;
      }
  }
  

  Register it in services.yaml:

  services:
      App\Service\CustomExporter:
          tags: ['xporter.exporter']
  

• Pre/Post-Import Hooks: Use Symfony events to modify data before/after import:

  // config/services.yaml
  App\EventListener\ImportListener:
      tags:
          - { name: kernel.event_listener, event: xporter.import.pre, method: onPreImport }
  

Gotchas and Tips

Pitfalls

1. Circular References

   • Exporting entities with bidirectional relations (e.g., User ↔ Role) may cause infinite loops.
   • Fix: Use --with-relations sparingly or manually break cycles in YAML.

2. Large Datasets

   • Exporting 100K+ records may hit memory limits.
   • Fix: Use chunking with --limit or optimize YAML serialization.

3. Doctrine Events

   • Pre/post-persist/remove events may interfere with imports.
   • Fix: Disable events during import:

     $em->getEventManager()->clear();
     

4. Unique Constraints

   • Importing duplicate data (e.g., email in User) will fail silently or throw exceptions.
   • Fix: Use --append or validate YAML first.

Debugging Tips

• Dry Run: Add --dry-run to preview changes without executing:

  php bin/console xporter:import user.yml --dry-run
  

• Logging: Enable debug mode to log skipped/failed records:

  # config/packages/xporter.yaml
  xporter:
      debug: true
  

• YAML Validation: Use symfony/validator to validate fixtures before import:

  use Symfony\Component\Validator\Validator\ValidatorInterface;
  
  $validator = $container->get(ValidatorInterface::class);
  $errors = $validator->validate($yamlData);
  

Extension Points

1. Custom Fixture Format Override the default YAML writer by implementing FixtureWriterInterface:

   class JsonFixtureWriter implements FixtureWriterInterface {
       public function write(array $data, string $path): void {
           file_put_contents($path, json_encode($data));
       }
   }
   

   Register it in services.yaml:

   App\Service\JsonFixtureWriter:
       tags: ['xporter.fixture_writer']
   

2. Dynamic Export Filters Use a custom query builder by extending ExportCommand:

   protected function getQueryBuilder(string $entityClass): QueryBuilder {
       $qb = parent::getQueryBuilder($entityClass);
       $qb->andWhere('u.createdAt > :date')
          ->setParameter('date', new \DateTime('-7 days'));
       return $qb;
   }
   

3. Environment-Specific Fixtures Use Symfony’s parameter system to switch fixtures per environment:

   # config/packages/dev/xporter.yaml
   xporter:
       import_files:
           - "%kernel.project_dir%/config/fixtures/dev/users.yml"