Laminas Serializer Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require laminas/laminas-serializer
   

   For Laravel, use laminas/laminas-serializer with a DI container like laminas/laminas-servicemanager or php-di.

2. First Use Case: Serialize/deserialize a PHP object to/from JSON (default adapter):

   use Laminas\Serializer\Adapter\Json;
   use Laminas\Serializer\Adapter\AdapterInterface;
   
   $serializer = new Json();
   $data = ['name' => 'John', 'age' => 30];
   
   // Serialize to JSON string
   $jsonString = $serializer->serialize($data);
   
   // Deserialize back to PHP array
   $restoredData = $serializer->unserialize($jsonString);
   

3. Laravel Integration: Register the service in config/app.php or use a container binding:

   $container->bind(AdapterInterface::class, function ($container) {
       return new Json();
   });
   

Implementation Patterns

Core Workflows

1. Adapter-Based Serialization:

   • Use built-in adapters (Json, Xml, PhpSerialize, Igbinary) or extend AdapterInterface for custom formats.
   • Example: Switching between JSON and XML:

     $jsonAdapter = new Json();
     $xmlAdapter = new Xml();
     
     $serializedJson = $jsonAdapter->serialize($data);
     $serializedXml = $xmlAdapter->serialize($data);
     

2. Dependency Injection:

   • Laravel developers should bind adapters to the container for reuse:

     $container->bind('serializer.json', function () {
         return new Json(['pretty_print' => true]);
     });
     

   • Inject adapters into services:

     public function __construct(private AdapterInterface $serializer) {}
     

3. Custom Serialization Logic:

   • Implement AdapterInterface for custom formats (e.g., Protocol Buffers):

     class ProtobufAdapter implements AdapterInterface {
         public function serialize($data): string { /* ... */ }
         public function unserialize(string $data): mixed { /* ... */ }
     }
     

4. Configuration-Driven Serialization:

   • Use GenericSerializerFactory to configure default adapters:

     $factory = new GenericSerializerFactory();
     $serializer = $factory->createService([
         'default_adapter' => Json::class,
         'options' => ['pretty_print' => true]
     ]);
     

Laravel-Specific Patterns

1. Service Providers: Register adapters in a Laravel service provider:

   public function register() {
       $this->app->singleton(AdapterInterface::class, function () {
           return new Json();
       });
   }
   

2. API Responses: Serialize Eloquent models to JSON for API responses:

   public function show(User $user) {
       $serializer = app(AdapterInterface::class);
       return response()->json($serializer->serialize($user->toArray()));
   }
   

3. Caching: Use Igbinary for compact binary serialization in cache:

   $cacheAdapter = new Igbinary();
   $cachedData = $cacheAdapter->unserialize(cache('key'));
   

4. Form Requests: Deserialize JSON payloads in request handling:

   public function store(Request $request) {
       $serializer = app(AdapterInterface::class);
       $data = $serializer->unserialize($request->getContent());
       // Process $data
   }
   

Gotchas and Tips

Pitfalls

1. Type Safety:

   • PHP's unserialize() is unsafe. Use Json or Igbinary for secure deserialization.
   • Example: Avoid PhpSerialize for untrusted input:

     // UNSAFE: Use only with trusted data
     $phpSerializer = new PhpSerialize();
     $data = $phpSerializer->unserialize($_POST['serialized_data']);
     

2. Adapter Limitations:

   • Xml adapter may not handle all PHP types (e.g., DateTimeImmutable).
   • PhpSerialize has compatibility issues with closures or resources.

3. Laravel Container Conflicts:

   • Ensure no duplicate bindings for AdapterInterface exist in Laravel's container.

4. Deprecated Methods:

   • Avoid Laminas\Serializer\Serializer (deprecated in v2.16.0). Use AdapterInterface directly.

Debugging Tips

1. Validation:

   • Validate serialized strings before deserialization:

     if (!Json::isValid($jsonString)) {
         throw new \InvalidArgumentException('Invalid JSON');
     }
     

2. Error Handling:

   • Wrap deserialization in try-catch:

     try {
         $data = $serializer->unserialize($string);
     } catch (\RuntimeException $e) {
         Log::error('Deserialization failed: ' . $e->getMessage());
     }
     

3. Logging:

   • Log serialization failures for debugging:

     $serializer->setOptions(['logger' => $logger]);
     

Extension Points

1. Custom Adapters:

   • Extend AdapterInterface for new formats (e.g., Avro, MessagePack):

     class AvroAdapter implements AdapterInterface {
         public function serialize($data): string {
             // Custom Avro serialization logic
         }
         public function unserialize(string $data): mixed {
             // Custom Avro deserialization logic
         }
     }
     

2. Middleware for API:

   • Create middleware to serialize/deserialize API payloads:

     public function handle($request, Closure $next) {
         $data = app(AdapterInterface::class)->unserialize($request->getContent());
         $request->merge(['data' => $data]);
         return $next($request);
     }
     

3. Event-Based Serialization:

   • Use Laravel events to trigger serialization (e.g., on model saving):

     User::saved(function ($user) {
         $serialized = app(AdapterInterface::class)->serialize($user->toArray());
         // Store $serialized
     });
     

4. Testing:

   • Mock adapters in unit tests:

     $mockAdapter = Mockery::mock(AdapterInterface::class);
     $mockAdapter->shouldReceive('serialize')->andReturn('{"test":1}');
     $this->app->instance(AdapterInterface::class, $mockAdapter);
     

Configuration Quirks

1. Options Handling:

   • Pass adapter-specific options via constructor:

     $jsonAdapter = new Json(['pretty_print' => true, 'date_format' => 'c']);
     

2. Default Adapter:

   • Configure the default adapter in Laravel's config/services.php:

     'serializer' => [
         'default' => Laminas\Serializer\Adapter\Json::class,
         'options' => ['pretty_print' => false],
     ],
     

3. Performance:

   • For high-throughput apps, prefer Igbinary over Json for speed:

     $fastAdapter = new Igbinary();