Symfonyboot Bundle Laravel Package

Getting Started

• Require ^3.0: composer require vendor/package:^3.0. v3 replaces symfony/serializer with jms/serializer; remove Symfony Serializer if it was only present for this package.
• Publish and inspect the package config (config/serializer.php or equivalent). v3 config keys follow JMS conventions (cache_dir, metadata, context options), not Symfony Serializer options.
• First use case: inject the bound serializer and serialize a DTO or model to JSON.

use JMS\Serializer\SerializerInterface;

$serializer = app(SerializerInterface::class);

$json = $serializer->serialize($orderDto, 'json');

For the new array-of-objects support:

/** @var array<App\Dto\Order> $orders */
$json = $serializer->serialize($orders, 'json');

The elements must be concrete, serializable objects. Nested arrays still need type metadata (@Type("array<App\Dto\Order>") or attributes) on the property.

Implementation Patterns

• Prefer DTOs over raw Eloquent models. JMS will traverse object graphs; Eloquent lazy loading, relations, and cycles cause noisy payloads and N+1 queries.
• Use JMS metadata on DTOs: #[Type], #[Groups], #[SerializedName], #[Exclude], and #[Since] / #[Until] for API versioning.
• Serialize with groups per context:

use JMS\Serializer\SerializationContext;

$json = $serializer->serialize(
    $dto,
    'json',
    SerializationContext::create()->setGroups(['list'])
);

• For arrays and collections, declare element types explicitly. Top-level arrays of objects work in v3, but nested arrays still rely on JMS type hints:

#[Type('array<App\Dto\Order>')]
public array $orders = [];

• Register custom JMS handlers for value objects (money, enums, IDs) via the package config. Do not implement Symfony NormalizerInterface or EncoderInterface; those are no longer used.
• In controllers, return the serialized string through a JsonResponse or a response with Content-Type: application/json. Avoid double-encoding.
• Use SerializationContext attributes for runtime flags instead of package-specific globals.

Gotchas and Tips

• v3 is breaking. The serializer engine changed from Symfony Serializer to JMS Serializer. Symfony annotations, normalizers, encoders, and context options do not carry over. Rewrite custom normalizers as JMS handlers or visitors, and change annotation namespaces to JMS\Serializer\Annotation (or attributes).
• Metadata cache matters. JMS writes metadata to the configured cache_dir. Ensure it is writable, clear it after DTO annotation changes, and warm it during deployment. A stale cache produces confusing “property not found” or missing-field behavior.
• Array-of-objects needs types. An untyped array will serialize as arrays of arrays or fail. Add @Type("array<Fully\Qualified\Class>") on properties and docblocks. For top-level arrays, confirm each element is serializable without context that is only available on a parent object.
• Config caching quirk. If you run php artisan config:cache, make sure the JMS cache path is absolute and not inside a path that gets cached incorrectly. Re-run cache clears after changing serializer config.
• Performance. JMS metadata parsing is slower on a cold cache than Symfony Serializer in some workloads. Warm metadata in CI/deploy, and keep DTOs narrow with groups/exclusion policies.
• Debugging. Use SerializerBuilder directly in Tinker to isolate binding issues, inspect generated metadata in the cache directory, and enable JMS debug options temporarily. For missing fields, check groups, @Exclude, and naming strategy before assuming a package bug.
• Extension points. Custom handlers, event subscribers (PreSerializeEvent, PostSerializeEvent), naming strategies, and SerializationContext attributes are the supported customization surface in v3. Prefer these over forking the package.
• Dependency hygiene. Keep symfony/serializer only if another package needs it. JMS Serializer is now a hard dependency and may conflict with packages that expect Symfony Serializer metadata or normalizers.