Laravel Symfony Serializer Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require wayofdev/laravel-symfony-serializer
   

   Publish the config (optional):

   php artisan vendor:publish --provider="WayOfDev\LaravelSymfonySerializer\LaravelSymfonySerializerServiceProvider"
   

2. First Use Case: Serializing a Model

   use WayOfDev\LaravelSymfonySerializer\Facades\Serializer;
   
   $user = User::find(1);
   $serialized = Serializer::serialize($user, 'json');
   $deserialized = Serializer::deserialize($serialized, User::class, 'json');
   

3. Where to Look First

   • Facade: WayOfDev\LaravelSymfonySerializer\Facades\Serializer (primary entry point).
   • Config: config/symfony-serializer.php (for customizing encoders/normalizers).
   • Documentation: Focus on the Symfony Serializer docs for advanced use cases.

Implementation Patterns

Core Workflows

1. Model Serialization/Deserialization

   // Serialize to JSON
   $json = Serializer::serialize($model, 'json');
   
   // Deserialize from JSON
   $model = Serializer::deserialize($json, Model::class, 'json');
   

2. Custom Normalizers Extend Symfony\Component\Serializer\Normalizer\NormalizerInterface and register via config:

   'normalizers' => [
       App\Normalizers\CustomNormalizer::class,
   ],
   

3. API Response Handling

   return response()->json(
       Serializer::serialize($collection, 'json', [
           'groups' => ['api']
       ])
   );
   

4. Event-Driven Serialization Use Serializer::serializeToStream() for large objects (e.g., exporting CSV/Excel):

   $stream = Serializer::serializeToStream($data, 'csv');
   return response()->stream(fn() => $stream, 200, [
       'Content-Type' => 'text/csv',
       'Content-Disposition' => 'attachment; filename="export.csv"',
   ]);
   

5. Integration with Laravel Events

   use WayOfDev\LaravelSymfonySerializer\Events\Serializing;
   
   Serializing::dispatch($model, 'json')->then(function ($serialized) {
       // Post-serialization logic
   });
   

Best Practices

• Grouping: Use @Groups annotations (via serializer:groups config) for granular control over serialized fields.
• Caching: Leverage Symfony’s CacheNormalizer for performance-critical paths:

  'normalizers' => [
      Symfony\Component\Serializer\Normalizer\CacheNormalizer::class,
  ],
  

• Validation: Combine with Laravel Validation for deserialized data:

  $data = Serializer::deserialize($json, stdClass::class, 'json');
  Validator::make($data, ['field' => 'required'])->validate();
  

Gotchas and Tips

Pitfalls

1. Circular References

   • Default behavior throws CircularReferenceException. Use ignore_circular_references config option or implement DenormalizerInterface:

     'context' => [
         'ignore_circular_references' => true,
     ],
     

2. Type Safety

   • Deserializing to abstract classes or interfaces may fail. Ensure concrete classes are registered in the config:

     'denormalizers' => [
         App\Denormalizers\AbstractClassDenormalizer::class,
     ],
     

3. Performance Overhead

   • Avoid serializing large collections in loops. Use Serializer::serialize() with stream context for memory efficiency:

     Serializer::serialize($collection, 'json', ['stream' => true]);
     

4. Config Overrides

   • Published config (config/symfony-serializer.php) is merged with defaults. Overrides may silently fail if syntax is incorrect. Validate with:

     php artisan config:clear
     

Debugging Tips

• Enable Debug Mode

  Serializer::setDebug(true); // Logs normalization/denormalization steps
  

• Inspect Context Use Serializer::getContext() to debug serialization/deserialization context:

  $context = Serializer::getContext();
  dd($context['groups'], $context['attributes']);
  

• Normalizer Debugging Implement Symfony\Component\Serializer\Normalizer\NormalizerAwareInterface to log normalization steps:

  public function normalize($object, string $format = null, array $context = [])
  {
      \Log::debug('Normalizing: ' . get_class($object));
      return parent::normalize($object, $format, $context);
  }
  

Extension Points

1. Custom Encoders Register new encoders (e.g., XML, YAML) in the config:

   'encoders' => [
       Symfony\Component\Serializer\Encoder\XmlEncoder::class,
   ],
   

2. Event Listeners Subscribe to Serializing/Deserializing events for pre/post-processing:

   Serializing::listen(function ($event) {
       $event->getData()->append('custom_field', 'value');
   });
   

3. Service Provider Binding Bind custom serializers to the container:

   $this->app->bind(
       Symfony\Component\Serializer\SerializerInterface::class,
       App\CustomSerializer::class
   );
   

4. Testing Mock the Serializer facade in tests:

   $this->app->instance(
       WayOfDev\LaravelSymfonySerializer\Facades\Serializer::class,
       Mockery::mock(Symfony\Component\Serializer\SerializerInterface::class)
   );