Serializer Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require andrew-gos/serializer
   

   Ensure your project uses PHP 8.2+.

2. First Use Case: Serialize a simple array to JSON:

   use AndrewGos\Serializer\SerializerFactory;
   
   $serializer = SerializerFactory::getDefaultSerializer();
   $json = $serializer->serialize(['name' => 'John'], 'json');
   

3. Where to Look First:

   • SerializerFactory for default configurations.
   • Encoder\JsonEncoder and Encoder\XmlEncoder for built-in formats.
   • SerializerInterface for custom implementations.

Implementation Patterns

Core Workflow

1. Instantiation: Use SerializerFactory::getDefaultSerializer() for pre-configured serializers with default normalizers (scalars, arrays, objects).

2. Adding Encoders: Register encoders dynamically:

   $serializer->addEncoder('json', new JsonEncoder());
   $serializer->addEncoder('xml', new XmlEncoder());
   

3. Custom Normalizers: Register type-specific normalizers (e.g., for Eloquent models):

   $serializer->addNormalizer(
       App\Models\User::class,
       fn (App\Models\User $user) => [
           'id' => $user->id,
           'name' => $user->name,
       ]
   );
   

4. Serialization:

   $result = $serializer->serialize($data, 'json'); // or 'xml'
   

Integration Tips

• API Responses: Use JsonEncoder for Laravel API responses (e.g., in App\Http\Resources).
• XML Configs: Leverage XmlEncoder for generating config files or SOAP responses.
• Circular References: Automatically handled by XmlEncoder (no manual intervention needed).
• Middleware: Create a Laravel middleware to serialize responses:

  public function handle($request, Closure $next) {
      $response = $next($request);
      $serializer = app(SerializerInterface::class);
      $response->setContent($serializer->serialize($response->getData(), 'json'));
      return $response;
  }
  

Advanced Patterns

1. Nested Objects: Normalize nested objects recursively:

   $serializer->addNormalizer(
       App\Models\Post::class,
       fn (App\Models\Post $post) => [
           'title' => $post->title,
           'author' => $serializer->serialize($post->author, 'json'),
       ]
   );
   

2. Conditional Serialization: Skip properties based on conditions:

   $serializer->addNormalizer(
       App\Models\User::class,
       fn (App\Models\User $user) => [
           'email' => $user->email,
           'api_token' => $user->api_token ?? null,
       ]
   );
   

3. Custom Encoders: Extend EncoderInterface for new formats (e.g., YAML):

   class YamlEncoder implements EncoderInterface {
       public function encode($data, array $context = []): string {
           return \Spatie\ArrayToXml\ArrayToXml::convert($data);
       }
   }
   

Gotchas and Tips

Pitfalls

1. Circular References in JSON: JsonEncoder does not handle circular references by default. Use XmlEncoder or implement a custom normalizer to break cycles:

   $serializer->addNormalizer(
       stdClass::class,
       fn (stdClass $obj) => json_decode(json_encode($obj), true) // Flatten object
   );
   

2. Array vs. Object Reference Handling:

   • Arrays are passed by value, creating duplicate references in XML (see README for details).
   • Objects are passed by reference, avoiding duplicates. Prefer objects for complex recursive structures.

3. Normalizer Precedence: Normalizers are applied in registration order. The last registered normalizer for a type wins. Use hasNormalizer() to check for conflicts:

   if (!$serializer->hasNormalizer(stdClass::class)) {
       $serializer->addNormalizer(stdClass::class, ...);
   }
   

4. Performance: Avoid registering normalizers for every possible type in large applications. Group related types (e.g., all Eloquent models) under a base normalizer:

   $serializer->addNormalizer(
       App\Models\Model::class,
       fn (App\Models\Model $model) => $model->toArray()
   );
   

Debugging

1. Check Registered Normalizers/Encoders:

   $serializer->getNormalizers(); // Array of registered normalizers
   $serializer->getEncoders();    // Array of registered encoders
   

2. Inspect Serialization Context: Pass a context array to debug normalizer behavior:

   $serializer->serialize($data, 'json', ['debug' => true]);
   

3. XML Reference Keys: If XML output is unexpectedly large, verify reference keys are unique. Override XmlEncoder's generateReferenceKey() method:

   $encoder = new XmlEncoder();
   $encoder->setReferenceKeyGenerator(fn ($data) => spl_object_hash($data));
   

Extension Points

1. Custom Context Handling: Extend SerializerInterface to add context-specific logic:

   interface CustomSerializerInterface extends SerializerInterface {
       public function serializeWithMetadata($data, string $format, array $context = []): array;
   }
   

2. Normalizer Factories: Dynamically generate normalizers based on runtime conditions:

   $serializer->addNormalizerFactory(
       fn (string $class) => $class === App\Models\User::class
           ? fn (App\Models\User $user) => $user->toArray()
           : null
   );
   

3. Encoder Wrappers: Create wrapper encoders to add headers or modify output:

   class JsonApiEncoder implements EncoderInterface {
       public function encode($data, array $context = []): string {
           return '{"data": ' . (new JsonEncoder())->encode($data) . '}';
       }
   }
   

Configuration Quirks

1. Default Normalizers: SerializerFactory::getDefaultSerializer() includes normalizers for:

   • Scalars (int, string, etc.)
   • Arrays (array)
   • Objects (stdClass and subclasses) Override these if needed, but test thoroughly.

2. Encoder Format Names: Encoder format names (e.g., 'json') are case-sensitive. Use lowercase strings.

3. PHP 8.2 Features: Leverage named arguments in normalizers/encoders for clarity:

   $serializer->addNormalizer(
       App\Models\Post::class,
       fn (App\Models\Post $post) => [
           'title' => $post->title,
           'published_at' => $post->publishedAt->format('Y-m-d'),
       ]
   );