Lara Asp Serializer Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require lastdragon-ru/lara-asp-serializer
   

   The package auto-registers, so no additional service provider configuration is needed.

2. First Use Case: Serialize a model or array to JSON with custom normalization:

   use LastDragon\LaraAspSerializer\Facades\Serializer;
   
   $data = User::find(1);
   $serialized = Serializer::serialize($data, 'json');
   

3. Where to Look First:

   • Facade: LastDragon\LaraAspSerializer\Facades\Serializer (primary entry point).
   • Configuration: config/lara-asp-serializer.php (default settings, normalization groups, and encoders).
   • Documentation: Check the Examples/ directory in the repo for use cases like nested objects, custom normalization, and API responses.

Implementation Patterns

Core Workflows

1. Basic Serialization/Deserialization:

   // Serialize to JSON
   $json = Serializer::serialize($object, 'json');
   
   // Deserialize from JSON
   $object = Serializer::deserialize($json, get_class($object), 'json');
   

2. Normalization Groups: Define groups in config (normalization_groups) and use them to control what gets serialized:

   // In config/lara-asp-serializer.php
   'normalization_groups' => [
       'user:public' => ['id', 'name', 'email'],
       'user:admin'  => ['*'],
   ];
   
   // Usage
   $serialized = Serializer::serialize($user, 'json', ['groups' => ['user:public']]);
   

3. Custom Normalizers: Register a custom normalizer for a specific class:

   Serializer::getContainer()->get('serializer')->getNormalizers()->addNormalizer(
       new CallbackNormalizer(
           fn ($object) => ['custom_key' => $object->customMethod()],
           ['groups' => ['user:custom']]
       ),
       100 // Priority
   );
   

4. API Responses: Integrate with Laravel responses for consistent JSON formatting:

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

5. Caching Serialized Data: Leverage Symfony’s cache system for performance:

   $serialized = Serializer::serialize($data, 'json', [
       'cache_key' => 'user.1.api',
       'cache_ttl' => 3600,
   ]);
   

Integration Tips

• Eloquent Models: Use traits or accessors to define normalization groups:

  class User extends Model
  {
      public function getApiRepresentation(): array
      {
          return Serializer::normalize($this, ['groups' => ['user:public']]);
      }
  }
  

• Form Requests: Deserialize incoming data:

  $validated = Serializer::deserialize(
      $request->getContent(),
      UserRequest::class,
      'json'
  );
  

• Queue Jobs: Serialize payloads for delayed processing:

  $job = new ProcessUser($user->id);
  $job->handle(Serializer::serialize($user, 'json'));
  

Gotchas and Tips

Pitfalls

1. Circular References: Symfony’s serializer handles circular references by default, but custom normalizers may break this. Use DenormalizerInterface or NormalizerInterface with ignore_circular_references: true in config.

2. Group Conflicts: If multiple normalization groups are defined for the same class, ensure priorities align with your use case. Overlapping groups may serialize unexpected data.

3. Performance with Large Data: Avoid serializing/deserializing massive datasets in loops. Use batch processing or caching:

   // Bad: Serializing 10,000 records in a loop
   foreach ($users as $user) {
       $serialized = Serializer::serialize($user, 'json');
   }
   
   // Good: Batch and cache
   $serializedBatch = Serializer::serialize($users, 'json', ['groups' => ['batch']]);
   

4. Type Safety: Deserialization assumes the target class exists and is compatible with the input. Validate types or use DenormalizerAwareInterface for custom logic:

   Serializer::deserialize($json, User::class, 'json', [
       'object_to_populate' => $existingUser,
   ]);
   

Debugging

• Enable Debug Mode:

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

• Inspect Normalizers: Dump registered normalizers to debug serialization flow:

  dd(Serializer::getContainer()->get('serializer')->getNormalizers()->getNormalizers());
  

• Validate Config: Ensure encoders and normalizers in config/lara-asp-serializer.php match your use case. Missing encoders (e.g., json) will throw errors.

Extension Points

1. Custom Encoders: Add support for new formats (e.g., XML, CSV) by extending the config:

   'encoders' => [
       'csv' => new \Symfony\Component\Serializer\Encoder\CsvEncoder(),
   ],
   

   Then use:

   Serializer::serialize($data, 'csv');
   

2. Middleware for API: Create a middleware to auto-serialize responses:

   public function handle($request, Closure $next)
   {
       $response = $next($request);
       if ($response->isJson()) {
           $data = $response->getData(true);
           $response->setData(Serializer::serialize($data, 'json', ['groups' => ['api']]));
       }
       return $response;
   }
   

3. Dynamic Group Resolution: Override group resolution logic by binding a custom GroupResolver:

   $serializer = Serializer::getContainer()->get('serializer');
   $serializer->getNormalizers()->setGroupResolver(new CustomGroupResolver());
   

4. Event Listeners: Hook into serialization/deserialization events via Symfony’s event system:

   $serializer->addSubscriber(new class implements SerializerSubscriberInterface {
       public function hasMethods(string $format): bool { return true; }
       public function getSubscribedMethods(): array { return ['onSerialize']; }
       public function onSerialize(SerializeEvent $event) { /* ... */ }
   });