Dto Laravel Package

Product Decisions This Supports

• API boundary hardening (build vs. buy): Decides whether internal API request/response shapes get hand-rolled arrays or a typed contract layer. A lightweight DTO package lets you adopt typed boundaries without pulling in a full serialization framework or re-architecting controllers.
• Integration surface area: Choosing a consistent way to map third-party payloads (webhooks, partner APIs, queue messages) into internal types. fromArray() / fromJson() + toArray() / toJson() gives a single, testable seam — useful for scoping "how much work is the Stripe webhook integration?" questions.
• Roadmap sequencing for a "data contracts" initiative: If the roadmap includes tightening domain boundaries, decoupling layers, or preparing for a service split, DTOs are a prerequisite. This is a low-cost enabler rather than a feature in itself.
• Feature scoping on validation and error handling: Validation-friendly design means you can decide whether validation lives in FormRequests, DTO constructors, or a dedicated layer — a real architectural decision that affects where error messages and UX copy originate.
• Extensibility vs. convention (new in 0.1.20): A globally registered TransformerRegistry (casters for hydration, serializers for output) plus per-field transformFrom / transformTo hooks means there is now a real decision about where custom type mapping lives: global registry, per-field transform, or a hand-written mapper outside the package. Worth pinning down before teams diverge.
• Whether to enable code generation: The package compiles a fast path for hydration/serialization, with transforms compiled to direct calls (~4x cheaper per transformed field when the generated file declares strictTypes; unsafe callables fall back to the runtime path). This is a performance lever we can turn on for hot payloads and leave off elsewhere — not an all-or-nothing commitment.
• Build vs. buy on internal tooling: At ~30 stars and a single-maintainer profile, this is a "small dependency" decision, not a platform bet. It supports a decision to standardize a thin convention internally rather than adopt a heavyweight framework dependency. 0.1.20 shows active maintenance, but at fix-level cadence, not a support contract.
• Serialization consistency across channels: Deciding whether one DTO definition can serve HTTP JSON, queue payloads, and internal service calls — reduces duplicate mapping code and the class of bugs where two layers disagree on field names or types.
• Test strategy for generated code: 0.1.20 (#114) fixed a case where the generated fast path bypassed globally registered registry casters during fromArray(), and scoped guards so casters affect input only and serializers affect output only. That is the classic codegen risk — generated and interpreted paths diverging. Any adoption decision should explicitly budget for parity testing between generated and non-generated paths.
• Not supported: Anything requiring strong vendor SLAs, enterprise support, or a large hiring pool familiar with the library. This is a convenience layer, not infrastructure.

When to Consider This Package

Adopt when most of these hold:

• You are on Laravel/PHP and the boundary is thin. Request → DTO → service → response is the dominant flow, and you want casts, nested DTOs, and typed collections without the ceremony of a full data-mapping framework.
• Payload shapes are stable and small-to-medium. A dozen or so DTOs with mostly scalars, enums, dates, and one level of nesting. This package is at its best here.
• You want minimal surface area. Teams that find heavier DTO frameworks opinionated or over-featured (magic properties, implicit validation pipelines, deep Laravel coupling) benefit from a package that does casting and serialization and gets out of the way.
• You have hot paths worth optimizing. High-volume ingestion — webhook bursts, queue consumers, large response payloads — can use the compiled fast path (with strictTypes declared for compiled field transforms). If throughput is not a constraint, ignore the codegen entirely; nothing else depends on it.
• You want per-field control. transformFrom / transformTo covers the "this one field needs custom handling" case without a global caster, and the 0.1.20 change makes that cheap without changing semantics.
• You are prepared to own the risk. Low star count and a thin contributor base mean you should be comfortable reading the source, pinning versions, and potentially vendoring or forking. That is a reasonable trade for a mapping layer of this size, and unreasonable if no one on the team will maintain it. Note that the codegen/fast-path machinery widens the surface beyond simple mapping code — read it before enabling it.
• You need a migration path, not a rewrite. from() on an existing object or array means you can introduce DTOs incrementally at one boundary rather than converting the whole codebase.

Look elsewhere when:

• You need first-class validation rules, authorization, or resource transformation. spatie/laravel-data or Laravel API Resources cover that ground with far more community support.
• You need an established ecosystem. Thirty stars means few Stack Overflow answers, few blog posts, and no guarantee of a response to a security report. If your org's dependency policy scores on community health, this will not clear the bar.
• You have complex polymorphic or deeply recursive payloads where explicit, hand-written mappers may be clearer than fighting a casting layer.
• Your team will not debug generated code. The fast path is compiled PHP; when a mapping bug lands on-call, someone has to reason about generated output versus the runtime path. If that is unrealistic, disable codegen or pick a simpler mapper.
• You need long-term vendor assurance — regulated environments, or a platform team that will not accept a single-maintainer dependency for anything on the critical path.

How to Pitch It (Stakeholders)

To executives: This is a small, MIT-licensed utility that makes the data moving between our systems explicitly typed instead of loose arrays. The business value is defect prevention: a large share of integration bugs are shape mismatches — a field renamed on one side, a string where a number was expected, a null where an object was assumed. Typed DTOs move those failures from production to development. The latest release is maintenance-grade: a correctness fix in the generated mapping path and a performance improvement for custom field transforms. Cost is low and reversible; the main caveat is unchanged — it is an early-stage community project, so we pin the version and treat it as a replaceable internal detail rather than a strategic dependency.

To engineering: Adopt it at one boundary first — a webhook handler or a public API response. It gives you typed construction and serialization with nested DTOs and typed collections, enums, dates, per-field transforms, and a global caster/serializer registry, without the implicit magic of larger frameworks. There is no heavy framework lock-in: the DTOs are plain PHP classes, and the compiled fast path is an opt-in performance feature rather than a requirement. The 0.1.20 fix is a reminder that generated code can drift from the runtime path — treat that as a testing obligation, not a reason to avoid the feature. Recommend four guardrails: pin the version; wrap fromArray/toArray behind our own small base class or trait so the dependency is swappable; require a round-trip test per DTO; and require that any DTO using the generated path is also exercised through the non-generated path in CI.

To the architecture/security reviewer: Flag the dependency-health score honestly — 30 stars, unknown repository provenance, single maintainer. The 0.1.20 release is a net positive signal (issues triaged and fixed, perf work landed) but also confirms the package now contains a code-generation layer, which is more to audit than plain mapping helpers. Mitigation is containment: no DTO on an authentication, payment, or PII-handling critical path until we have either contributed upstream or vendored the code, and no codegen on those paths regardless.