Serialization Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require amphp/serialization
   

   Ensure your project uses PHP 7.4+ (Laravel 8.x or lower).

2. First Use Case: Serialize a simple array for IPC (e.g., Unix sockets) with compression:

   use Amp\Serialization\CompressingSerializer;
   use Amp\Serialization\NativeSerializer;
   
   $serializer = new CompressingSerializer(new NativeSerializer());
   $data = ['task' => fn() => 'hello', 'value' => 42];
   $serialized = $serializer->serialize($data);
   // Send $serialized via IPC (e.g., socket_write)
   

3. Where to Look First:

   • Serializer interface: Core contract for all serializers.
   • CompressingSerializer: Wrap any serializer for payload optimization.
   • JsonSerializer: Laravel-compatible alternative for APIs/caches.
   • NativeSerializer: Use only for trusted internal IPC (closures, resources).

Implementation Patterns

Usage Patterns

1. IPC Workflows (AMPHP):

   • Unix Sockets/Shared Memory:

     $serializer = new CompressingSerializer(new NativeSerializer());
     $payload = $serializer->serialize($workerTask);
     socket_write($socket, $payload);
     

   • AMPHP Redis:

     $redis = new Amp\Redis\Client();
     $serializer = new JsonSerializer(); // Avoid NativeSerializer for Redis
     $redis->set('key', $serializer->serialize($data));
     

2. Laravel Integration (Limited):

   • Queue Jobs (Avoid NativeSerializer):

     use Amp\Serialization\JsonSerializer;
     
     class MyJob implements ShouldQueue {
         public function handle() {
             $serializer = new JsonSerializer();
             $serialized = $serializer->serialize($this->data);
             // Use $serialized for custom storage (not recommended for Laravel queues)
         }
     }
     

   • Cache Drivers:

     Cache::put('key', (new JsonSerializer())->serialize($data), $seconds);
     

3. Compression Strategy:

   • Wrap serializers for large payloads (e.g., CLI workers):

     $compressedSerializer = new CompressingSerializer(new NativeSerializer());
     $compressedData = $compressedSerializer->serialize($largeObject);
     

Workflows

1. Serializer Chaining:

   $serializer = new CompressingSerializer(
       new JsonSerializer() // Fallback to JSON if compression fails
   );
   

2. Error Handling:

   try {
       $data = $serializer->unserialize($payload);
   } catch (SerializationException $e) {
       Log::error("Deserialization failed: " . $e->getMessage());
       // Fallback to JsonSerializer or rethrow
   }
   

3. AMPHP Async Context:

   $serializer = new NativeSerializer();
   $data = yield $serializer->serialize($fiberData);
   

Integration Tips

• Avoid in Laravel Controllers: Use json_encode() instead.
• Prefer JsonSerializer for APIs: Ensures compatibility with Laravel’s ecosystem.
• Benchmark Compression: Only use CompressingSerializer if payloads exceed 1KB (overhead for smaller data).
• Isolate Usage: Restrict to CLI workers, custom IPC, or non-critical paths.

Gotchas and Tips

Pitfalls

1. Security Risks:

   • NativeSerializer is unsafe for untrusted data (e.g., user input, IPC from external sources).
     • Fix: Use JsonSerializer + manual validation for public-facing data.
   • unserialize() vulnerabilities persist in PHP 7.4+. Avoid for any external data.

2. PHP Version Lock-In:

   • No PHP 8.x support: Blocks Laravel 9+/10 adoption.
     • Workaround: Isolate to PHP 7.4-only environments or fork the package.

3. Laravel Incompatibility:

   • No Eloquent support: Circular references, relationships, or accessors may fail.
     • Fix: Use JsonSerializer for Laravel models or implement custom logic.
   • Queue Jobs: Laravel’s ShouldQueue expects json_encode() by default. Overriding serialization requires custom job handling.

4. Compression Overhead:

   • Small payloads (<1KB) slow down due to compression/decompression.
     • Tip: Benchmark with microtime(true) before adopting.

5. No Laravel-Specific Features:

   • No cache driver integration: Manual wrapping required for Illuminate\Cache.
   • No queue worker hooks: Custom serialization logic needed for Illuminate\Bus.

Debugging

1. Serialization Failures:

   • Symptom: SerializationException with no clear cause.
   • Debug:

     try {
         $serializer->serialize($data);
     } catch (SerializationException $e) {
         dd(gettype($data), $data, $e->getMessage());
     }
     

   • Common Causes:
     • Closures/resources in NativeSerializer (expected).
     • Circular references in JsonSerializer (use JSON_THROW_ON_ERROR).

2. Compression Issues:

   • Symptom: Payloads grow larger after compression.
   • Debug: Check if data is already compressed (e.g., gzipped strings).

3. PHP 7.4+ Attributes:

   • Symptom: #[Override] not recognized in Laravel.
   • Fix: Use JsonSerializer or implement custom attribute handling.

Config Quirks

1. Default Serializer:

   • The package does not provide a global default. Always instantiate explicitly:

     // Bad: Assumes global state
     $data = unserialize($payload);
     
     // Good: Explicit serializer
     $serializer = new JsonSerializer();
     $data = $serializer->unserialize($payload);
     

2. Compression Level:

   • CompressingSerializer uses default zlib compression (level 6).
   • Customize via constructor (if extended):

     $compressor = new \Amp\Serialization\CompressingSerializer(
         $serializer,
         ['level' => 9] // Max compression
     );
     

Extension Points

1. Custom Serializers:

   • Implement Amp\Serialization\Serializer for domain-specific logic:

     class MySerializer implements Serializer {
         public function serialize($data): string {
             return base64_encode(serialize($data));
         }
         public function unserialize(string $data) {
             return unserialize(base64_decode($data));
         }
     }
     

2. Attribute-Based Serialization:

   • Use #[Override] for custom logic (PHP 7.4+):

     #[Override]
     public function serialize($data): string {
         // Custom logic
     }
     

3. Fallback Chains:

   • Combine serializers for resilience:

     $fallbackSerializer = new CompressingSerializer(
         new JsonSerializer(),
         new NativeSerializer() // Fallback to native if JSON fails
     );
     

Laravel-Specific Tips

1. Avoid in Controllers:

   • Laravel’s json_encode() is optimized for APIs. Use:

     return response()->json($data); // Preferred
     // Not:
     return response((new JsonSerializer())->serialize($data));
     

2. Queue Jobs:

   • Do not replace Laravel’s default serialization. Instead:

     // In job constructor
     public function __construct(public array $data) {}
     
     // In handle()
     $serializer = new JsonSerializer();
     $this->data = $serializer->unserialize($this->data);
     

3. Cache:

   • Use Laravel’s built-in compression (e.g., Redis) instead of CompressingSerializer:

     Cache::put('key', $data, $seconds); // Uses Redis compression if enabled