Product Decisions This Supports
- API contract and response shaping: The package is the layer that turns models/DTOs into JSON, so it directly affects what customers and partner integrations receive. v3.0.0 changes the engine underneath that layer, which makes this a customer-facing decision, not just a library swap.
- Build vs. buy for serialization: With JMS Serializer now powering serialization, the package covers complex cases (nested object graphs, groups, naming strategies, versioned payloads) that would otherwise be hand-rolled. This tilts build-vs-buy toward "buy/adopt" for teams with non-trivial payload requirements.
- New capability unlocked — array-of-objects serialization: Enables endpoints and jobs that emit collections of typed objects without custom marshalling code. Useful for list endpoints, batch exports, event payloads, and webhook fan-out.
- Roadmap sequencing: v3.0.0 is a major version with a serializer engine change. Upgrading is planned work with a validation phase, not an opportunistic bump. It should be scheduled like a migration, with a contract-regression gate before rollout.
- Upgrade vs. pin decision per service: Teams can hold existing services on v2 while new services start on v3. This is a portfolio-level decision about consistency versus delivery speed.
- Risk and dependency ownership: JMS Serializer brings its own configuration model, metadata/attribute conventions, and performance characteristics. Adopting v3 means owning that knowledge in-house.
When to Consider This Package
Consider it when:
- You need structured serialization beyond Laravel's built-in API Resources — nested objects, serialization groups, naming/versioning strategies, or per-context output.
- You are emitting arrays of heterogeneous or typed objects and want the library to handle the recursion rather than writing bespoke mapping code per endpoint.
- You want serialization behavior centralized and testable instead of scattered across controllers, resources, and jobs.
- You are starting fresh on v3 and can adopt JMS Serializer conventions from day one without migration debt.
Look elsewhere or delay when:
- Your payloads are flat and simple; Eloquent's
toArray() or API Resources are sufficient and cheaper to maintain.
- You are mid-flight on v2 with a large surface area of serialized output and no capacity for a contract-regression cycle. Pin v2 and revisit.
- Your team has no JMS Serializer familiarity and no appetite to own its configuration and metadata model.
- Hard constraints on PHP/Laravel versions or dependency budgets conflict with the v3 requirement set (validate before committing).
- You depend on Symfony Serializer-specific behavior — attribute/annotation semantics, normalizers, or custom encoders — that does not map cleanly to JMS.
Migration caution: The engine swap can change observable output — date formats, null handling, property visibility, naming, and circular-reference behavior. Treat every serialized response as a potential breaking change for consumers.
How to Pitch It (Stakeholders)
To executives: This release upgrades the serialization engine our API responses depend on and adds support for arrays of objects. It expands what we can ship without custom code, but it is a major version with a breaking change under the hood. Recommendation: adopt v3 for new work immediately, and fund a short, gated migration for existing services rather than a big-bang upgrade. The cost is bounded engineering time; the risk of skipping the gate is unintended changes to customer-facing API payloads.
To engineering: v3.0.0 replaces Symfony Serializer with JMS Serializer and adds array-of-objects serialization. Plan for: a dependency and PHP/Laravel compatibility check; an inventory of every serialized output surface; a golden-file or snapshot test suite comparing v2 and v3 payloads; explicit review of date, null, naming, and visibility behavior; and a documented rollback to v2 per service. New services should start on v3 to avoid accumulating migration debt. Treat the upgrade as a contract change with a validation gate, not a routine dependency bump.