Jms Serializer Bundle Bridge Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle Add the package via Composer:

   composer require dlakomski/jms-serializer-bundle-bridge
   

   Register the bundle in config/bundles.php:

   return [
       // ...
       SimpleBus\JMSSerializerBundleBridge\SimpleBusJMSSerializerBundleBridgeBundle::class => ['all' => true],
   ];
   

2. Configure JMSSerializer Ensure jms/serializer-bundle is installed and configured in config/packages/jms_serializer.yaml:

   jms_serializer:
       handlers:
           datetime:
               default_format: "Y-m-d\TH:i:sP"
       metadata:
           directories:
               - "%kernel.project_dir%/config/serializer"
   

3. First Use Case: Serializing a Message Define a message class (e.g., app/src/Message/ExampleMessage.php):

   namespace App\Message;
   
   class ExampleMessage {
       public function __construct(
           private string $content,
           private ?\DateTimeInterface $timestamp = null
       ) {}
       // Getters omitted for brevity
   }
   

   Dispatch it via SimpleBus:

   $bus->dispatch(new ExampleMessage('Hello, world!', new \DateTime()));
   

Implementation Patterns

Workflows

1. Message Serialization The bridge automatically uses JMSSerializer for all messages dispatched via SimpleBus\AsynchronousBundle. No manual serialization is required—just define your message classes with proper annotations or metadata.

2. Custom Metadata Extend JMS metadata for complex types (e.g., nested objects, custom formats):

   # config/serializer/App.Message.ExampleMessage.yml
   App\Message\ExampleMessage:
       exclusion_policy: ALL
       properties:
           content:
               expose: true
           timestamp:
               expose: true
               type: DateTime<'Y-m-d\TH:i:s.uP'>
   

3. Integration with Symfony Forms Reuse JMS metadata for form type mapping:

   use JMS\Serializer\Annotation as Serializer;
   
   class ExampleMessage {
       #[Serializer\Type("string")]
       private string $content;
   }
   

4. Event Listeners for Post-Processing Hook into kernel.request to modify serialization behavior:

   $event->getRequest()->attributes->set('serializer.context', [
       'groups' => ['api']
   ]);
   

Tips for Daily Use

• Leverage Groups: Use @Groups({"api"}) in annotations to control serialization context.
• Debugging: Enable JMS debug mode in config/packages/dev/jms_serializer.yaml:

  jms_serializer:
      debug: true
  

• Performance: Cache metadata for production:

  jms_serializer:
      metadata:
          cache: file
          file_cache:
              dir: "%kernel.cache_dir%/serializer"
  

Gotchas and Tips

Pitfalls

1. Circular References JMS may fail on circular references (e.g., MessageA contains MessageB, which contains MessageA). Fix: Use @MaxDepth(1) or @ExclusionPolicy(ALL) on problematic properties.

2. Missing Metadata If a message isn’t serialized, verify:

   • The class has no exclusion_policy: ALL without exposed properties.
   • Metadata files are in the correct directory (%kernel.project_dir%/config/serializer).

3. DateTime Handling Default format may not match your needs. Override in jms_serializer.yaml or use metadata:

   properties:
       timestamp:
           type: DateTime<'Y-m-d H:i:s'>
   

4. Bundle Conflict Ensure SimpleBus/AsynchronousBundle is installed and configured before this bridge.

Debugging

• Check Serialized Output:

  $serializer = $container->get('jms_serializer');
  $serialized = $serializer->serialize($message, 'json');
  

• Validate Metadata:

  php bin/console debug:serializer
  

Extension Points

1. Custom Serializers Register a custom handler in config/packages/jms_serializer.yaml:

   handlers:
       My\Custom\Type:
           type: My\Custom\Serialization\Handler
   

2. Override Default Serializer If needed, configure SimpleBus\AsynchronousBundle to use a custom ObjectSerializer:

   simple_bus_asynchronous:
       object_serializer: my_custom.serializer
   

3. Event Subscribers Extend serialization logic via JMS\Serializer\EventDispatcher\PreSerializeEvent:

   $event->getObject()->setProperty($event->getVisitor()->getContext()['custom_key']);