Laminas Serializer Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require laminas/laminas-serializer
   

   For Laravel projects, use laminas/laminas-serializer with a DI container (e.g., Laravel's built-in container or Laminas Service Manager).

2. Basic Usage:

   use Laminas\Serializer\Adapter\AdapterInterface;
   use Laminas\Serializer\Adapter\PhpSerialize;
   
   // Register the adapter (Laravel example)
   $container->bind(AdapterInterface::class, function ($container) {
       return new PhpSerialize();
   });
   
   // Usage
   $serializer = $container->make(AdapterInterface::class);
   $data = ['key' => 'value', 'nested' => ['foo' => 'bar']];
   
   // Serialize
   $serialized = $serializer->serialize($data);
   // Deserialize
   $deserialized = $serializer->unserialize($serialized);
   

3. First Use Case:

   • Caching: Store complex objects in Redis/Memcached.
   • API Responses: Convert objects to JSON/XML for APIs.
   • Session Storage: Serialize user sessions.

Implementation Patterns

Core Workflows

1. Adapter-Based Serialization:

   • Use AdapterInterface for type-agnostic serialization. Supported adapters:
     • PhpSerialize (default, PHP’s native serialize()).
     • Json (for JSON strings).
     • Xml (for XML strings).
     • IgBinary (for binary data).
   • Example:

     $jsonAdapter = new \Laminas\Serializer\Adapter\Json();
     $serialized = $jsonAdapter->serialize(['data' => 123]);
     

2. Dependency Injection:

   • Laravel’s container or Laminas Service Manager manages adapters.
   • Override defaults via configuration:

     $container->bind(AdapterInterface::class, function () {
         return new \Laminas\Serializer\Adapter\IgBinary();
     });
     

3. Custom Serialization:

   • Extend AdapterInterface for domain-specific needs:

     class CustomAdapter implements AdapterInterface {
         public function serialize($data): string {
             return json_encode($data, JSON_PRETTY_PRINT);
         }
         public function unserialize(string $serialized): mixed {
             return json_decode($serialized, true);
         }
     }
     

4. Error Handling:

   • Wrap calls in try-catch for malformed data:

     try {
         $data = $serializer->unserialize($corruptData);
     } catch (\RuntimeException $e) {
         log::error("Deserialization failed: " . $e->getMessage());
     }
     

Integration Tips

• Laravel Cache:

  $serializer = app(AdapterInterface::class);
  Cache::put('key', $serializer->serialize($data), $minutes);
  $data = $serializer->unserialize(Cache::get('key'));
  

• API Responses:

  return response()->json($serializer->serialize($resource));
  

• Queue Jobs:

  $job->handle($serializer->unserialize($job->payload));
  

Gotchas and Tips

Pitfalls

1. Type Safety:

   • unserialize() may return false or throw exceptions for invalid data. Always validate:

     if ($result = $serializer->unserialize($data)) {
         // Safe to use
     }
     

   • PHP’s serialize() is not secure for untrusted input (risk of object injection). Use Json or IgBinary for APIs.

2. Adapter Limitations:

   • PhpSerialize handles PHP-specific types (e.g., DateTime, SplObjectStorage) but fails for non-PHP data.
   • Json/Xml lose type information (e.g., DateTime becomes a string).

3. Performance:

   • IgBinary is faster than Json for large data but less human-readable.
   • Avoid serializing giant objects (e.g., Eloquent collections with lazy loading).

4. Deprecations:

   • Laminas\Serializer\Serializer (v2) is removed in v3. Use AdapterInterface directly.
   • Niche adapters (MsgPack, Wddx) are dropped in v3.

Debugging

• Corrupt Data:
  • Use var_dump($serializer->unserialize($data)) to check for partial deserialization.
  • For Json/Xml, validate the string first:

    json_decode($data); // Returns null on failure
    

• Memory Issues:
  • Large objects may hit PHP’s memory_limit. Stream data or chunk serialization:

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

Tips

1. Configuration:

   • Override the default adapter in Laravel’s config/services.php:

     'serializer' => [
         'adapter' => \Laminas\Serializer\Adapter\IgBinary::class,
     ],
     

   • Use GenericSerializerFactory to customize options (e.g., Json pretty-printing).

2. Testing:

   • Mock AdapterInterface in unit tests:

     $mock = $this->createMock(AdapterInterface::class);
     $mock->method('serialize')->willReturn('mocked');
     

   • Test edge cases: null, empty arrays, circular references.

3. Security:

   • Sanitize input before unserialize(). For APIs, prefer Json:

     $data = json_decode($request->input(), true);
     

   • Use IgBinary for binary data (e.g., file uploads) to avoid PHP object injection.

4. Extending:

   • Create a custom adapter for domain-specific needs (e.g., Protobuf):

     class ProtobufAdapter implements AdapterInterface {
         public function serialize($data): string {
             return \Protobuf::encode($data);
         }
         public function unserialize(string $serialized): mixed {
             return \Protobuf::decode($serialized);
         }
     }
     

   • Register it via the container:

     $container->bind(AdapterInterface::class, ProtobufAdapter::class);
     

5. Laravel-Specific:

   • Bind the adapter in AppServiceProvider:

     public function register() {
         $this->app->bind(AdapterInterface::class, function () {
             return new \Laminas\Serializer\Adapter\Json();
         });
     }
     

   • Use in middleware for request/response transformation:

     $serialized = app(AdapterInterface::class)->serialize($responseData);
     return response($serialized, 200, ['Content-Type' => 'application/json']);