Bdf Serializer Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require b2pweb/bdf-serializer-bundle
   

2. Enable Bundle: Add to config/bundles.php:

   Bdf\SerializerBundle\BdfSerializerBundle::class => ['all' => true],
   

3. Basic Configuration: Create config/packages/bdf_serializer.yaml:

   bdf_serializer:
     cache:
       pool: 'cache.app'  # For production
   

   For testing, override in config/packages/test/bdf_serializer.yaml:

   bdf_serializer:
     cache:
       pool: null
   

First Use Case: Serializing an Entity

Inject the SerializerInterface into a controller or service:

use Symfony\Component\Serializer\SerializerInterface;

class MyController extends AbstractController
{
    public function serializeEntity(SerializerInterface $serializer, MyEntity $entity): JsonResponse
    {
        $data = $serializer->serialize($entity, 'json', [
            'groups' => ['default'],
        ]);
        return new JsonResponse($data, 200, [], true);
    }
}

Implementation Patterns

Common Workflows

1. Group-Based Serialization: Use groups to control which properties are serialized:

   #[Groups(['default'])]
   private string $name;
   
   #[Groups(['admin'])]
   private string $secretKey;
   

   Then serialize with:

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

2. Custom Normalizers: Register a custom normalizer in config/packages/bdf_serializer.yaml:

   bdf_serializer:
       normalizers:
           - Bdf\SerializerBundle\Normalizer\CustomNormalizer
   

3. Contextual Serialization: Pass context to the serializer for dynamic behavior:

   $serializer->serialize($entity, 'json', [
       'groups' => ['default'],
       'context' => ['locale' => 'fr'],
   ]);
   

4. Deserialization:

   $deserialized = $serializer->deserialize($jsonData, MyEntity::class, 'json');
   

Integration Tips

• API Platform: Use this bundle alongside API Platform for consistent serialization.
• Symfony Forms: Combine with Symfony\Component\Form\FormFactory for form-to-entity hydration.
• Event Listeners: Attach listeners to kernel.request to pre-process serialization contexts.

Gotchas and Tips

Pitfalls

1. Caching Overhead:

   • Disabling caching (pool: null) in tests can slow down serialization significantly.
   • Clear cache after schema changes:

     php bin/console cache:clear
     

2. Circular References:

   • Use ignore_circular_references context option to avoid infinite loops:

     $serializer->serialize($entity, 'json', ['ignore_circular_references' => true]);
     

3. Group Conflicts:

   • Ensure groups are consistent across entities and serializers. Use #[Groups(['group1', 'group2'])] for shared properties.

4. Deprecated Methods:

   • Avoid Serializer::serialize() directly; prefer SerializerInterface for better dependency injection.

Debugging

• Enable Debug Mode: Add to config/packages/dev/bdf_serializer.yaml:

  bdf_serializer:
      debug: true
  

  This logs serialization/deserialization details.

• Check Normalizer Order: If serialization behaves unexpectedly, verify normalizer priority in config/packages/bdf_serializer.yaml:

  bdf_serializer:
      normalizers:
          - { class: App\Normalizer\FirstNormalizer, priority: 100 }
          - { class: App\Normalizer\SecondNormalizer, priority: 50 }
  

Extension Points

1. Custom Encoders: Register a custom encoder (e.g., for XML):

   bdf_serializer:
       encoders:
           - Bdf\SerializerBundle\Encoder\XmlEncoder
   

2. Event Subscribers: Subscribe to serializer.normalize or serializer.deserialize events for pre/post-processing:

   use Symfony\Component\Serializer\SerializerEvent;
   
   public function onSerialize(SerializerEvent $event) {
       $data = $event->getData();
       // Modify $data before serialization
       $event->setData($data);
   }
   

3. Dynamic Group Resolution: Override group resolution logic by implementing Bdf\SerializerBundle\Resolver\GroupResolverInterface.