Getting Started

Minimal Setup

Installation:

composer require alexacrm/strong-serializer

Add the service provider to config/app.php:

'providers' => [
    // ...
    Alexacrm\StrongSerializer\StrongSerializerServiceProvider::class,
],

Basic Usage: Register a serializer for a model (e.g., User) in a service provider or boot method:
```
StrongSerializer::register(User::class, new UserSerializer());
```

First Use Case: Serialize a model to an array:

$user = User::find(1);
$serialized = StrongSerializer::serialize($user);

Deserialize back to an object:

$deserialized = StrongSerializer::deserialize($serialized, User::class);

Where to Look First:
- Serializer Interface (defines serialize() and deserialize() methods).
- StrongSerializer Facade (entry point for most operations).
- Example Serializers (if provided in the package).

Implementation Patterns

Common Workflows

Model Serialization: Create a dedicated serializer for each model (e.g., UserSerializer):

class UserSerializer implements SerializerInterface
{
    public function serialize($object): array
    {
        return [
            'id' => $object->id,
            'name' => $object->name,
            'email' => $object->email,
            'created_at' => $object->created_at->toDateTimeString(),
        ];
    }

    public function deserialize(array $data, string $class): User
    {
        return User::create($data);
    }
}

API Responses: Use the serializer in controllers to standardize API responses:

public function show(User $user)
{
    return response()->json(StrongSerializer::serialize($user));
}

Request Validation: Deserialize incoming requests into strongly typed objects:

public function store(Request $request)
{
    $validated = $request->validate([...]);
    $user = StrongSerializer::deserialize($validated, User::class);
    $user->save();
}

Nested Serialization: Handle relationships by recursively serializing associated models:

public function serialize($object): array
{
    return [
        'id' => $object->id,
        'posts' => StrongSerializer::serialize($object->posts),
    ];
}

Caching Serialized Data: Cache serialized output for performance (e.g., in API responses):

$serialized = cache()->remember("user.{$user->id}.serialized", now()->addHours(1), function() use ($user) {
    return StrongSerializer::serialize($user);
});

Integration Tips

Laravel Events: Trigger serialization/deserialization in model events (e.g., retrieved, saved).

Form Requests: Extend FormRequest to deserialize input automatically:

public function rules()
{
    return [...];
}

public function prepareForValidation()
{
    $this->merge(StrongSerializer::deserialize($this->all(), User::class)->toArray());
}

API Resources: Use alongside Laravel’s ApiResource for hybrid serialization logic.

Testing: Mock serializers in tests to isolate business logic:

$this->app->instance(SerializerInterface::class, MockSerializer::new());

Gotchas and Tips

Pitfalls

Circular References:

Issue: Serializing nested models with circular references (e.g., User has posts, Post has user) causes infinite recursion.

Fix: Use a visited array in serializers or implement a depth limit:

private $visited = [];

public function serialize($object): array
{
    if (in_array(spl_object_hash($object), $this->visited)) {
        return ['__circular_reference__' => true];
    }
    $this->visited[] = spl_object_hash($object);
    // ...
}

Deserialization Ambiguity:
- Issue: Deserializing an array into multiple possible classes (e.g., User or Admin).
- Fix: Use a factory or pass a class hint explicitly:
```
StrongSerializer::deserialize($data, User::class); // Force class
```

Type Safety:

Issue: Deserialized data may not match the target class’s constraints (e.g., invalid dates, missing required fields).

Fix: Validate deserialized data before creating objects:

public function deserialize(array $data, string $class): User
{
    $validator = Validator::make($data, User::$rules);
    if ($validator->fails()) {
        throw new \InvalidArgumentException($validator->errors()->first());
    }
    return User::create($data);
}

Performance Overhead:
- Issue: Deeply nested serialization can be slow for large objects.
- Fix: Lazy-load relationships or use with() in Eloquent queries to limit loaded data.
Package Versioning:
- Issue: The package is new (1 star, low score) and may lack documentation or stability.
- Fix: Test thoroughly and consider forking if critical features are missing.

Debugging Tips

Log Serialized Output:

\Log::debug('Serialized:', ['data' => StrongSerializer::serialize($object)]);

Validate Serializers: Ensure serialize() and deserialize() are inverses:

$original = new User(...);
$serialized = StrongSerializer::serialize($original);
$roundTrip = StrongSerializer::deserialize($serialized, User::class);
expect($original->toArray())->toEqual($roundTrip->toArray());

Check for Registered Serializers:

\Log::debug('Registered serializers:', StrongSerializer::getRegisteredSerializers());

Extension Points

Custom Serializer Storage: Override the default storage mechanism (e.g., swap StrongSerializer’s registry for a database-backed system).

Dynamic Serialization: Implement a DynamicSerializer to handle runtime class discovery:

StrongSerializer::registerDynamic(function (string $class) {
    return new DynamicSerializer($class);
});

Event Hooks: Extend the package by dispatching events during serialization/deserialization:
```
event(new Serializing($object, $serializer));
```

Middleware for API: Create middleware to serialize/deserialize requests/responses globally:

public function handle($request, Closure $next)
{
    $request->merge(StrongSerializer::deserialize($request->all(), $request->wantsJson ? 'App\\JsonRequest' : 'App\\FormRequest'));
    return $next($request);
}

Fallback Serializers: Provide fallback logic for unregistered classes:
```
StrongSerializer::setFallbackSerializer(new ArraySerializer());
```

Strong Serializer Laravel Package