Serializer Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require egeloen/serializer-bundle
   

   Add the bundle to config/bundles.php in Laravel (via App\Providers\SerializerServiceProvider if using a custom provider wrapper):

   Egeloen\SerializerBundle\SerializerBundle::class,
   

2. Basic Usage: Serialize an object to JSON (default format):

   use Egeloen\SerializerBundle\Serializer\Serializer;
   use Symfony\Component\Serializer\Encoder\JsonEncoder;
   
   $serializer = app(Serializer::class);
   $data = ['name' => 'John', 'age' => 30];
   $json = $serializer->serialize($data, 'json');
   

3. First Use Case: Convert Eloquent models to JSON for API responses:

   $user = User::find(1);
   return response()->json($serializer->serialize($user, 'json'));
   

Implementation Patterns

Common Workflows

1. API Response Serialization: Use Serializer in controllers to standardize API responses:

   public function show(User $user)
   {
       return response()->json(
           $this->serializer->serialize($user, 'json', [
               'groups' => ['api']
           ])
       );
   }
   

2. Request Deserialization: Parse incoming JSON/XML/YAML requests:

   $data = $this->serializer->deserialize(
       $request->getContent(),
       'stdClass',
       'json'
   );
   

3. Normalization Groups: Define groups in entities (e.g., #[Groups(['api'])]) and use them in serialization:

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

4. Custom Encoders/Normalizers: Register additional formats (e.g., CSV) via config:

   # config/packages/egeloen_serializer.yaml
   egeloen_serializer:
       encoders:
           csv: ~
       normalizers:
           csv: Egeloen\SerializerBundle\Normalizer\CsvNormalizer
   

5. Event Listeners: Hook into serializer.post_serialize/serializer.post_deserialize events for pre/post-processing:

   $serializer->addListener('serializer.post_serialize', function ($event) {
       $event->getData()['timestamp'] = now()->toIso8601String();
   });
   

Integration Tips

• Laravel HTTP Responses: Use SerializerInterface with Laravel’s Response helper:

  return response($serializer->serialize($data, 'json'), 200, [
      'Content-Type' => 'application/json',
  ]);
  

• Form Requests: Deserialize request data in handle():

  $data = $this->serializer->deserialize(
      $request->getContent(),
      StoreUserRequest::class,
      'json'
   );
  

• Queue Jobs: Serialize payloads for delayed processing:

  $job = new ProcessOrder($serializer->serialize($order, 'json'));
  dispatch($job);
  

Gotchas and Tips

Pitfalls

1. Circular References: Default behavior throws CircularReferenceException. Use max_depth or custom handlers:

   $serializer->serialize($data, 'json', [
       'circular_reference_handler' => function ($object) {
           return $object->getId();
       }
   ]);
   

2. Date Handling: Dates serialize as ISO strings by default. Override with a custom normalizer or use DateTimeNormalizer:

   egeloen_serializer:
       normalizers:
           datetime: Symfony\Component\Serializer\Normalizer\DateTimeNormalizer
   

3. XML Namespaces: XML serialization may require explicit namespace handling:

   $serializer->serialize($data, 'xml', [
       'xml_format_output' => true,
       'xml_root_node_name' => 'root',
   ]);
   

4. Performance: Avoid serializing large objects (e.g., collections) without pagination. Use max_depth or partial serialization:

   $serializer->serialize($user->posts, 'json', ['max_depth' => 1]);
   

Debugging

• Enable Debug Mode:

  egeloen_serializer:
      debug: true
  

  Logs serialization/deserialization events to var/log/dev.log.

• Check Normalizer Order: Use Serializer::getNormalizers() to debug which normalizers are applied. Reorder via config:

  egeloen_serializer:
      normalizers:
          order:
              - Egeloen\SerializerBundle\Normalizer\ObjectNormalizer
              - App\Normalizer\CustomNormalizer
  

Extension Points

1. Custom Normalizers: Extend Symfony\Component\Serializer\Normalizer\NormalizerInterface and register:

   $serializer->addNormalizer(new App\Normalizer\MyNormalizer());
   

2. Context Overrides: Dynamically modify serialization context in middleware:

   $serializer->setContext([
       'groups' => request()->header('accept') === 'internal' ? ['internal'] : ['api']
   ]);
   

3. Event Subscribers: Modify serialized data globally:

   $serializer->addSubscriber(new class implements EventSubscriberInterface {
       public function getSubscribedEvents() {
           return ['serializer.post_serialize'];
       }
       public function onPostSerialize(PostSerializeEvent $event) {
           $event->getData()['meta'] = ['version' => '1.0'];
       }
   });
   

4. CSV Quirks: CSV serialization requires arrays or objects with getCsvData() method. For custom objects:

   $serializer->serialize($data, 'csv', [
       'csv_associative' => true,
       'csv_headers' => ['id', 'name']
   ]);
   

Config Quirks

• Default Format: Override the default format (JSON) in config:

  egeloen_serializer:
      default_format: xml
  

• Encoder Priorities: Ensure encoders are registered before normalizers. Use encoder key in config:

  egeloen_serializer:
      encoders:
          yaml: Symfony\Component\Serializer\Encoder\YamlEncoder
  

• Cache Normalizers: Enable caching for performance (requires symfony/cache):

  egeloen_serializer:
      normalizers:
          cache: true