Jms Serializer Bundle Bridge Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require simple-bus/jms-serializer-bundle-bridge
   

   Ensure simple-bus/asynchronous-bundle and jms/serializer-bundle are also installed.

2. Enable the Bundle: Add to config/bundles.php (Symfony 4.4+):

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

   For Symfony <4.4, add to AppKernel.php:

   $bundles[] = new \SimpleBus\JMSSerializerBundleBridge\SimpleBusJMSSerializerBundleBridgeBundle();
   

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

   namespace App\Message;
   
   class ProcessOrder
   {
       public function __construct(
           public string $orderId,
           public array $items
       ) {}
   }
   

   Dispatch it via SimpleBus:

   $bus->dispatch(new ProcessOrder('123', [['id' => 1, 'name' => 'Item']]));
   

   The bundle automatically serializes/deserializes messages using JMSSerializer.

Implementation Patterns

Core Workflow

1. Message Definition: Use DTOs (Data Transfer Objects) for messages. Annotate properties for JMSSerializer (e.g., @SerializedName, @Type):

   use JMS\Serializer\Annotation as JMS;
   
   class ProcessOrder
   {
       /** @JMS\Type("string") */
       public string $orderId;
   
       /** @JMS\Type("array<string, mixed>") */
       public array $items;
   }
   

2. Handling Messages: Register handlers in config/packages/simple_bus.yaml:

   simple_bus:
       handlers:
           App\Message\ProcessOrder: App\Handler\ProcessOrderHandler
   

3. Custom Serialization: Extend JMSSerializer configuration (e.g., config/packages/jms_serializer.yaml):

   jms_serializer:
       metadata:
           directories:
               App:
                   namespace_prefix: "App\\Message"
                   path: "%kernel.project_dir%/config/serializer"
   

Integration Tips

• Symfony Messenger Bridge: If using Symfony Messenger, configure SimpleBusAsynchronousBundle to delegate to Messenger:

  simple_bus_asynchronous:
      messenger: true
  

• Validation: Combine with symfony/validator for message validation:

  use Symfony\Component\Validator\Constraints as Assert;
  
  class ProcessOrder
  {
      /** @Assert\NotBlank */
      public string $orderId;
  }
  

• Testing: Mock the ObjectSerializer in tests:

  $serializer = $this->createMock(\SimpleBus\JMSSerializerBridge\ObjectSerializer::class);
  $bus = new \SimpleBus\Asynchronous\AsynchronousBus($serializer, $messageDispatcher);
  

Gotchas and Tips

Pitfalls

1. Circular References: JMSSerializer may fail on circular references. Use @MaxDepth or @ExclusionPolicy:

   /** @JMS\MaxDepth(1) */
   class CircularReference {}
   

2. Type Mismatches: Ensure message properties match serialized types (e.g., DateTime vs. string). Use @Type("DateTime<'Y-m-d'>") for custom formats.

3. Bundle Order: Enable SimpleBusJMSSerializerBundleBridgeBundle after SimpleBusAsynchronousBundle and JMSSerializerBundle in bundles.php.

4. Caching Metadata: Clear cache after adding new message classes:

   php bin/console cache:clear
   

Debugging

• Serialization Errors: Enable JMSSerializer debug mode in config/packages/jms_serializer.yaml:

  jms_serializer:
      debug: true
  

  Check logs for JMS\Serializer\Exception\RuntimeException.

• Handler Not Found: Verify the handler is registered in simple_bus.yaml and the message class is autoloaded.

Extension Points

1. Custom Metadata: Create custom metadata files in config/serializer/App.Message.directory.yml:

   App\Message\ProcessOrder:
       exclusion_policy: ALL
       properties:
           orderId:
               exclude: false
   

2. Event Listeners: Subscribe to simple_bus.message.serialized and simple_bus.message.deserialized events for logging/auditing:

   $eventDispatcher->addListener(
       'simple_bus.message.serialized',
       fn ($event) => Logger::info('Serialized: ' . $event->getMessage())
   );
   

3. Alternative Serializers: Override the default ObjectSerializer in config/packages/simple_bus.yaml:

   simple_bus:
       object_serializer: App\Custom\ObjectSerializer