Serialization Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require dlakomski/serialization
   

   Add to composer.json if not auto-loaded:

   "autoload": {
       "psr-4": {
           "App\\": "app/",
           "Dlakomski\\Serialization\\": "vendor/dlakomski/serialization/src/"
       }
   }
   

   Run composer dump-autoload.

2. First Use Case Define a serializable message class:

   use Dlakomski\Serialization\SerializableMessage;
   
   class UserCreatedMessage implements SerializableMessage
   {
       public function __construct(
           public string $userId,
           public string $email
       ) {}
   
       public function serialize(): string
       {
           return json_encode([
               'userId' => $this->userId,
               'email' => $this->email,
               'timestamp' => now()->toIso8601String(),
           ]);
       }
   
       public static function deserialize(string $data): self
       {
           $payload = json_decode($data, true);
           return new self($payload['userId'], $payload['email']);
       }
   }
   

3. Key Files to Reference

   • src/SerializableMessage.php (Core interface)
   • src/Serializer.php (Utility for conversion)
   • src/Exceptions/ (Custom exceptions)

Implementation Patterns

Core Workflow: Serialization/Deserialization

// Serialize
$message = new UserCreatedMessage('123', 'user@example.com');
$serialized = $message->serialize();

// Deserialize
$deserialized = UserCreatedMessage::deserialize($serialized);

Integration with Laravel

1. Queue Jobs

   use Dlakomski\Serialization\Serializer;
   
   class SendWelcomeEmailJob implements ShouldQueue
   {
       public function __construct(
           private string $serializedMessage
       ) {}
   
       public static function createFromMessage(SerializableMessage $message): self
       {
           return new self(Serializer::serialize($message));
       }
   
       public function handle()
       {
           $message = UserCreatedMessage::deserialize($this->serializedMessage);
           // Process...
       }
   }
   

2. API Responses

   return response()->json([
       'data' => Serializer::serialize($user),
       'meta' => Serializer::serialize($pagination),
   ]);
   

3. Database Storage

   // Store serialized data in DB
   $model->serialized_data = Serializer::serialize($message);
   $model->save();
   
   // Retrieve and deserialize
   $message = UserCreatedMessage::deserialize($model->serialized_data);
   

Extending Functionality

• Custom Serializers

  use Dlakomski\Serialization\SerializerInterface;
  
  class JsonSerializer implements SerializerInterface
  {
      public function serialize(mixed $data): string
      {
          return json_encode($data);
      }
  
      public function deserialize(string $data, string $class): mixed
      {
          return json_decode($data, false, 512, JSON_THROW_ON_ERROR);
      }
  }
  

• Middleware for API

  namespace App\Http\Middleware;
  
  use Closure;
  use Dlakomski\Serialization\Serializer;
  
  class SerializeResponse
  {
      public function handle($request, Closure $next)
      {
          $response = $next($request);
          $data = $response->getData(true);
  
          if (is_array($data) && isset($data['data'])) {
              $data['data'] = Serializer::serialize($data['data']);
              $response->setData($data);
          }
  
          return $response;
      }
  }
  

Gotchas and Tips

Pitfalls

1. Type Safety in Deserialization

   • Always validate deserialized data to prevent type mismatches or injection.
   • Example:

     public static function deserialize(string $data): self
     {
         $payload = json_decode($data, true);
         if (json_last_error() !== JSON_ERROR_NONE) {
             throw new \InvalidArgumentException('Invalid JSON data');
         }
         // Additional validation...
         return new self($payload['userId'], $payload['email']);
     }
     

2. Circular References

   • Avoid serializing objects with circular references (e.g., User->posts->user).
   • Use Serializer::serialize($object, ['ignore_circular' => true]) or implement __serialize() magic method.

3. Versioning

   • Serialized data may break if the class structure changes. Include a version field:

     public function serialize(): string
     {
         return json_encode([
             'version' => '1.0',
             'userId' => $this->userId,
             // ...
         ]);
     }
     

4. Performance

   • Serializing large objects (e.g., Eloquent collections) can be slow. Use Serializer::serialize($object, ['depth' => 1]) to limit recursion depth.

Debugging Tips

• Validate Serialized Data

  $serialized = $message->serialize();
  $deserialized = UserCreatedMessage::deserialize($serialized);
  assert($serialized === $message->serialize(), 'Serialization mismatch!');
  

• Log Serialized Output

  \Log::debug('Serialized message', [
      'data' => $serialized,
      'decoded' => json_decode($serialized, true),
  ]);
  

Extension Points

1. Custom Exceptions Extend Dlakomski\Serialization\Exceptions\SerializationException for domain-specific errors.

2. Serializer Registry Bind custom serializers to the container:

   $this->app->bind(SerializerInterface::class, function () {
       return new JsonSerializer();
   });
   

3. Event Dispatching Trigger events during serialization/deserialization:

   use Symfony\Component\EventDispatcher\EventDispatcher;
   
   class UserCreatedMessage implements SerializableMessage
   {
       public function serialize(): string
       {
           $event = new SerializingEvent($this);
           app(EventDispatcher::class)->dispatch($event);
           // ...
       }
   }
   

4. Testing Mock SerializableMessage for unit tests:

   $this->partialMock(UserCreatedMessage::class, ['serialize', 'deserialize'])
        ->shouldReceive('serialize')
        ->andReturn('{"userId":"123"}');