Serializer Bundle Laravel Package

Getting Started

• First, the reality check: this is a Symfony bundle, not a Laravel package. It ships a Bundle subclass plus a DI extension, so composer require happyr/serializer-bundle inside a Laravel app gets you a package that never boots — there is no service provider, no config file to publish, no facade. Its wiring only happens inside a Symfony kernel.
• What it actually gives you: a pre-configured Symfony\Component\Serializer\Serializer service plus an annotation-driven metadata layer so you can decorate plain PHP objects with @Exclude, @Groups, @VirtualProperty, @SerializedName-style markers instead of hand-maintaining arrays. Read src/Annotation/ first — the API surface is tiny and the README is thin; that directory is the whole value proposition.
• For Laravel, take the dependency, not the bundle: composer require symfony/serializer works standalone in Laravel. Bind it as a singleton in a service provider:

$this->app->singleton(Serializer::class, function () {
    $normalizer = new ObjectNormalizer(null, new MetadataAwareNameConverter(...));
    return new Serializer([$normalizer, new JsonEncoder()], [new JsonEncoder()]);
});

• First use case: a controller returns a domain object where you want to hide password, remember_token, internal flags, and expose a computed full_name — without writing a per-endpoint toArray() or a resource class for every shape. If that's your problem, Symfony Serializer (the library) solves it; the bundle is only the annotations convenience layer on top.

Implementation Patterns

• Groups over hardcoded arrays. Instead of $user->only(['id','name']) in one controller and $user->toArray() in another, annotate properties with a group and select per endpoint:

$serializer->serialize($user, 'json', ['groups' => ['list']]);

This is the pattern worth stealing even if you drop the bundle — it makes payload shape a property of the model, not of the controller.

• @Exclude for write-only/sensitive fields. Treat it as defense-in-depth alongside Eloquent's $hidden. $hidden only affects toArray()/toJson(); it's bypassed the moment someone iterates getAttributes(), and it doesn't protect nested value objects.
• Virtual properties for computed output. full_name, avatar_url, unread_count belong on the object as annotated accessors so every response includes them consistently. In Laravel this is the same role as an accessor + $appends, but scoped to serialization instead of leaking into every toArray().
• Context propagation is the workflow. Pass ['groups' => ..., 'attributes' => [...], 'skip_null_values' => false] at the top level; the ObjectNormalizer forwards child context into nested objects. Build one helper (ApiSerializer::for('list')) so nobody hand-writes context arrays in fifty places.
• Laravel integration means a ModelNormalizer. Symfony doesn't understand Illuminate\Database\Eloquent\Model or Collection. Without a custom normalizer it getter-walks the model, which triggers relation lazy-loading (N+1 on a list endpoint) and dumps internals. Normalize from getAttributes() + explicitly requested getRelations(), and add a Collection normalizer.
• Register custom normalizers ahead of ObjectNormalizer. Money, UUIDs, Carbon dates, enums, and DTOs should be handled explicitly; order in the serializer array decides who wins.
• Versioning via groups or @Since/@Until-style markers keeps /v1 and /v2 payloads in one class instead of duplicating resources.

Gotchas and Tips

• Unmaintained since 2016-07. Expect PHP 5.5/7.0-era constraints and symfony/serializer ~2.7|~3.0. It will not resolve alongside Symfony 5/6/7, and its annotation reader depends on doctrine/annotations, which is deprecated in favour of PHP 8 attributes. Do not put this on a new build — port the ideas.
• Eloquent getters leak. ObjectNormalizer calls public get*/is*/has* methods. On an Eloquent model that means getKey, getAttributes, getQueueableRelations, and more end up in your JSON, and is()-style business methods become booleans. Serialize DTOs, not models.
• Bidirectional relations recurse infinitely. user->posts->user->posts... throws CircularReferenceException. Either set circular_reference_handler in context or, better, don't serialize model graphs — build the tree you intend to return.
• @Exclude filters output, it doesn't skip work. The accessor still runs; expensive computed properties cost you even when excluded. Use the attributes context key to prune before normalizing hot paths.
• Null handling surprises clients. Symfony drops null values in newer versions by default (skip_null_values); Laravel consumers often expect explicit null keys. Set it deliberately per endpoint.
• Metadata cache staleness. The annotation reader caches parsed metadata. After editing annotations, clear the cache directory — a stale cache silently ignores your new @Groups. In Laravel, cache metadata only outside local.
• Groups don't inherit the way you expect across interfaces and abstract parents. Annotate the concrete class, or use AbstractNormalizer::GROUPS at the call site.
• Catch the typed exceptions at the edge: NotNormalizableValueException, ExtraAttributesException, CircularReferenceException → map to 422/500 rather than letting them bubble as opaque 500s.
• Extension points that outlive the bundle: custom normalizers, custom encoders (CSV/XML), MetadataAwareNameConverter for camelCase→snake_case, and setCallbacks are all plain Symfony Serializer features you keep even after dropping the bundle.
• Migration targets: Symfony\Component\Serializer\Attribute\Groups (PHP 8 attributes, Symfony 6.3+) if you want to stay on the component, or spatie/laravel-data / API Resources if you want the same declarative shape with Laravel-native testing, validation, and pagination ergonomics.