Doctrine Entity Dto Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require danilovl/doctrine-entity-dto-bundle
   

   Ensure Danilovl\DoctrineEntityDtoBundle\DoctrineEntityDtoBundle::class is registered in config/bundles.php.

2. Basic Configuration: Configure danilovl_doctrine_entity_dto.yaml in config/packages/:

   danilovl_doctrine_entity_dto:
       is_enabled: true
       default_dto_namespace: 'App\Dto'
   

3. First Use Case:

   • Create a DTO class (e.g., UserDto):

     namespace App\Dto;
     
     class UserDto {
         public function __construct(
             public string $id,
             public string $name,
             public string $email
         ) {}
     }
     

   • Annotate your Doctrine entity (e.g., User):

     use Danilovl\DoctrineEntityDtoBundle\Annotation\AsDto;
     
     #[AsDto(UserDto::class)]
     class User {}
     

   • Convert an entity to DTO in a service/controller:

     use Danilovl\DoctrineEntityDtoBundle\Dto\DtoConverter;
     
     $dto = $this->container->get(DtoConverter::class)->convert($userEntity);
     

Implementation Patterns

Common Workflows

1. DTO Conversion in Controllers:

   #[Route('/users/{id}', name: 'user_show')]
   public function show(User $user, DtoConverter $converter): JsonResponse
   {
       $dto = $converter->convert($user);
       return $this->json($dto);
   }
   

2. Bulk Conversion:

   $users = $userRepository->findAll();
   $dtos = $converter->convertCollection($users);
   

3. Custom Mapping Logic: Override default behavior with a custom converter:

   use Danilovl\DoctrineEntityDtoBundle\Dto\DtoConverterInterface;
   
   class CustomDtoConverter implements DtoConverterInterface {
       public function convert(object $entity): object {
           // Custom logic
       }
   }
   

   Register it as a service:

   services:
       Danilovl\DoctrineEntityDtoBundle\Dto\DtoConverter:
           alias: 'App\Service\CustomDtoConverter'
   

4. Nested DTOs:

   #[AsDto(UserDto::class)]
   class User {
       #[AsDto(AddressDto::class)]
       private Address $address;
   }
   

Integration Tips

• Symfony Forms: Use DTOs as form data classes for cleaner separation.
• API Platform: Leverage DTOs to control serialization without modifying entities.
• Event Listeners: Convert entities to DTOs in pre/post event handlers for logging or caching.

Gotchas and Tips

Pitfalls

1. Circular References: Avoid circular references in entity relationships (e.g., User ↔ Profile). Use @AsDto selectively or implement lazy loading.

2. Performance: Bulk conversion (convertCollection) can be memory-intensive. Use pagination or chunking for large datasets.

3. Configuration Overrides: Ensure is_enabled is true in config; otherwise, conversions will silently fail.

4. Annotation Processing: Clear Symfony cache (php bin/console cache:clear) after adding/removing @AsDto annotations.

Debugging

• Missing DTOs: Verify the DTO class is autoloaded and the namespace matches the config (default_dto_namespace).

  composer dump-autoload
  

• Conversion Errors: Check for type mismatches between entity properties and DTO constructor parameters. Use #[Assert\Type] for validation.

• Logging: Enable debug mode to log conversion issues:

  danilovl_doctrine_entity_dto:
      debug: true
  

Extension Points

1. Custom Property Mappers: Implement Danilovl\DoctrineEntityDtoBundle\Dto\PropertyMapperInterface to handle complex mappings (e.g., JSON fields).

2. Dynamic DTOs: Use reflection to generate DTOs dynamically if annotations are impractical:

   $converter->convert($entity, UserDto::class, true); // Force conversion
   

3. Symfony Messenger: Dispatch DTOs as messages for async processing:

   $this->messageBus->dispatch(new UserCreatedDto($dto));
   

4. Testing: Mock DtoConverter in unit tests:

   $this->mockBuilder(DtoConverter::class)
       ->shouldReceive('convert')
       ->andReturn(new UserDto('1', 'Test', 'test@example.com'));