Product Decisions This Supports
- Build vs. buy on the serialization layer. Every project that exchanges JSON/YAML/queue messages eventually writes a bespoke mapper (array → object → array).
crell/serde lets us buy that layer off the shelf instead of maintaining hand-rolled hydration code, freeing engineering capacity for product work.
- API contract strategy. Attribute-driven mapping on typed DTOs gives us a single, explicit source of truth for wire formats. This directly supports roadmap items like public API v2, versioned payloads, and deprecation of legacy response shapes.
- Integration roadmap. Webhook ingestion, partner APIs, and third-party data imports all need defensive deserialization of untrusted payloads. Strong typed deserialization with explicit field mapping reduces the "malformed payload crashes the consumer" class of incidents.
- Multi-surface reuse. A format-agnostic mapper (object model separate from formatter) means the same DTOs serve HTTP responses, queue messages, CLI exports, and internal service-to-service calls. That is a real reducer of duplicated code across surfaces.
- Domain-model hygiene. It supports the decision to stop passing associative arrays around the codebase and adopt explicit DTOs. That is a product-quality decision as much as an architecture one: fewer null-field bugs, clearer contracts, easier onboarding.
- Schema evolution and backwards compatibility. Explicit field names and control over which properties serialize let us ship additive changes without breaking consumers — a lever for release cadence.
When to Consider This Package
Adopt when:
- The stack is PHP 8.1+ and the team is comfortable with attributes as configuration.
- The core need is typed object ↔ structured-format mapping (JSON first), especially nested objects, collections of DTOs, and nullable/optional fields.
- We want decoupling between the domain object and the wire format, and expect to support more than one format over time.
- We value strictness and explicit mapping over convention-magic — i.e., we want deserialization failures to be loud and typed.
- The team is small enough that a lightweight, focused dependency beats a large framework integration.
Look elsewhere when:
- We are on PHP 7.x or cannot rely on attributes/enums — the package's premise doesn't apply.
- We need heavy XML/CSV/EDI support, or deep framework integration (e.g., Symfony Serializer's normalizers, JMS Serializer's ecosystem, API Platform's metadata pipeline). Mature ecosystems win on breadth and hiring familiarity.
- Licensing is unresolved. The metadata reports
NOASSERTION; legal must confirm the actual license before it enters a commercial product. Treat this as a gating item, not a footnote.
- Maintenance concentration is a concern. ~354 stars and effectively a single-maintainer project is fine for a utility library, but it should be treated as a dependency with a bus factor. If serialization is on a critical path, budget for the ability to fork or wrap it behind our own interface.
- Hot-path performance is the dominant constraint — reflection-driven mapping needs benchmarking against our payload sizes before we commit.
How to Pitch It (Stakeholders)
To executives: We have a recurring, low-glamour cost — every service hand-writes code to turn JSON into objects and back, and that code is where malformed-payload bugs live. This package replaces that with a small, focused, typed library. It buys us faster delivery of partner integrations and API changes, and fewer production incidents caused by bad input. The ask is small: one dependency, a legal license check, and an engineering spike to validate it against our payloads.
To engineering: Adopt explicit, attribute-mapped DTOs instead of arrays. We get typed deserialization, clear failure modes on bad input, format-agnostic mapping, and one place to change when a contract evolves. It's a small surface area, easy to wrap behind our own interface, and easy to test.
To architecture/security: Untrusted input is deserialized into known types with explicit field mapping rather than mass-assigned into loose structures — a meaningful reduction in the attack and bug surface. The trade-offs are reflection overhead on hot paths and a single-maintainer dependency, both mitigable with a thin adapter layer and a benchmark gate before rollout.