Serialization Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require amphp/serialization
   

   Ensure your project uses PHP 7.4+ (hard requirement).

2. Basic Usage:

   use Amp\Serialization\JsonSerializer;
   use Amp\Serialization\NativeSerializer;
   use Amp\Serialization\CompressingSerializer;
   
   // For interoperable, human-readable data (e.g., logs, configs)
   $jsonSerializer = new JsonSerializer();
   $serialized = $jsonSerializer->serialize(['key' => 'value']);
   $deserialized = $jsonSerializer->unserialize($serialized);
   
   // For internal IPC with compression (e.g., worker pools)
   $compressedSerializer = new CompressingSerializer(new NativeSerializer());
   $payload = $compressedSerializer->serialize([
       'task' => fn() => 'async_work',
       'data' => new stdClass()
   ]);
   

3. First Use Case:

   • AMPHP IPC: Serialize closures/resources for Unix sockets or shared memory.

     $socket = new Amp\Socket\Socket('unix:///tmp/worker.sock');
     $serializer = new CompressingSerializer(new NativeSerializer());
     socket_write($socket, $serializer->serialize(['task' => $closure]));
     

Where to Look First

• Serializer Interface: Amp\Serialization\Serializer for method signatures and exceptions.
• Implementations:
  • JsonSerializer for JSON-based workflows.
  • NativeSerializer for PHP-native types (use cautiously).
  • CompressingSerializer for payload optimization.
• Exceptions: SerializationException for error handling.

Implementation Patterns

Usage Patterns

1. Layered Serialization: Combine serializers for specific needs (e.g., compression + native types):

   $serializer = new CompressingSerializer(
       new NativeSerializer()
   );
   

   • Use Case: IPC where payload size matters and objects must persist (e.g., closures, resources).

2. Passthrough for Already-Serialized Data: Avoid double-serialization with PassthroughSerializer:

   $passthrough = new PassthroughSerializer();
   $alreadySerialized = $passthrough->serialize('existing_string');
   

3. Error Handling: Wrap serialization in try-catch blocks for async contexts:

   try {
       $data = $serializer->unserialize($payload);
   } catch (SerializationException $e) {
       // Fallback to JsonSerializer or rethrow
       throw new RuntimeException('Failed to deserialize payload', 0, $e);
   }
   

Workflows

1. AMPHP Worker Pools:

   • Serialize tasks with NativeSerializer + compression.
   • Deserialize in workers using the same serializer instance.

   // Master process
   $task = ['command' => 'process', 'args' => $data];
   $serializedTask = $serializer->serialize($task);
   $worker->send($serializedTask);
   
   // Worker process
   $task = $serializer->unserialize($receivedPayload);
   

2. Shared Memory: Use NativeSerializer for complex objects (e.g., Amp\ByteStream\Buffer):

   $sharedMemory = new Amp\SharedMemory\Segment();
   $serializer = new NativeSerializer();
   $sharedMemory->write($serializer->serialize($object));
   

3. Hybrid Serialization: Conditionally use JsonSerializer for public data and NativeSerializer for internal IPC:

   $serializer = $isInternalIpc
       ? new CompressingSerializer(new NativeSerializer())
       : new JsonSerializer();
   

Integration Tips

1. Laravel Compatibility:

   • Avoid for HTTP/API layers: Use Laravel’s json_encode() or spatie/array-to-object instead.
   • Queue Jobs: Only use for internal worker communication (not payloads). Extend Illuminate\Bus\Queueable with custom serialization:

     public function serialize(): array
     {
         return ['data' => $this->data]; // Simplified; use NativeSerializer for complex types
     }
     

2. AMPHP Integration:

   • Pair with amphp/byte-stream for socket-based IPC:

     use Amp\ByteStream\Socket;
     use Amp\Serialization\CompressingSerializer;
     
     $socket = Socket::connect('tcp://worker:1234');
     $serializer = new CompressingSerializer(new NativeSerializer());
     socket_write($socket, $serializer->serialize($message));
     

3. Testing:

   • Mock Serializer interface for unit tests:

     $mockSerializer = $this->createMock(Serializer::class);
     $mockSerializer->method('serialize')->willReturn('mocked');
     $mockSerializer->method('unserialize')->willReturn(['data' => 'test']);
     

4. Performance:

   • Benchmark compression gains:

     $data = ['large' => str_repeat('x', 1024)];
     $jsonSize = strlen((new JsonSerializer())->serialize($data));
     $compressedSize = strlen((new CompressingSerializer(new NativeSerializer()))->serialize($data));
     // Compare $jsonSize vs. $compressedSize
     

Gotchas and Tips

Pitfalls

1. PHP 7.4+ Hard Requirement:

   • Error: Class 'Amp\Serialization\Serializer' not found on PHP 8.x.
   • Fix: Pin to PHP 7.4 in composer.json or use a fork with PHP 8.x support.

2. NativeSerializer Security Risks:

   • Pitfall: unserialize() can execute arbitrary code.
   • Mitigation:
     • Only use for trusted internal IPC (never user input).
     • Whitelist allowed classes:

       $serializer = new NativeSerializer();
       $serializer->setAllowedClasses(['App\Task', 'Amp\ByteStream\Buffer']);
       

     • Alternative: Use JsonSerializer for untrusted data.

3. Circular References:

   • Pitfall: NativeSerializer may fail on circular references.
   • Fix: Use JsonSerializer or implement custom logic:

     $serializer = new JsonSerializer(JsonSerializer::FLAGS_DISALLOW_CIRCULAR_REFERENCES);
     

4. Closure/Resource Serialization:

   • Pitfall: JsonSerializer cannot serialize closures/resources.
   • Fix: Use NativeSerializer but restrict to trusted contexts.

5. Compression Overhead:

   • Pitfall: Compression may increase CPU usage for small payloads.
   • Tip: Benchmark before using CompressingSerializer.

6. Attribute Conflicts (PHP 8.x):

   • Pitfall: #[Override] may conflict with Laravel attributes (e.g., #[Cacheable]).
   • Fix: Avoid PHP 8.x or patch the library.

Debugging

1. Serialization Failures:

   • Check for unsupported types (e.g., resources, closures) with JsonSerializer.
   • Use NativeSerializer for complex objects but validate inputs.

2. Corrupted Payloads:

   • Ensure the same serializer is used for serialization/deserialization.
   • Add checksums for critical IPC:

     $payload = $serializer->serialize($data);
     $checksum = hash('crc32b', $payload);
     

3. Performance Bottlenecks:

   • Profile compression gains with CompressingSerializer:

     $data = ['large' => str_repeat('x', 1024 * 1024)]; // 1MB
     $start = microtime(true);
     $serialized = (new CompressingSerializer(new NativeSerializer()))->serialize($data);
     $time = microtime(true) - $start;
     // Log $time and strlen($serialized)
     

Configuration Quirks

1. NativeSerializer Allowed Classes:

   • Explicitly whitelist classes to prevent unserialize() risks:

     $serializer = new NativeSerializer();
     $serializer->setAllowedClasses([
         Amp\ByteStream\Buffer::class,
         App\Task::class,
     ]);
     

2. JSON Flags:

   • Configure JsonSerializer for strict parsing:

     $serializer = new JsonSerializer(
         JsonSerializer::FLAGS_DISALLOW_CIRCULAR_REFERENCES |
         JsonSerializer::FLAGS_DISALLOW