Dto Laravel Package

Product Decisions This Supports

• Where typed boundaries live in the architecture. Adopting a DTO layer is really a decision about where validation, casting, and shape enforcement sit: at the edge (HTTP/queue/CLI) versus scattered through services as array keys and ?? fallbacks. This package supports the "explicit typed object at the edge, plain values inside" pattern, which is a roadmap-relevant architectural standard, not a library choice.
• Build vs. buy vs. vendor. Because it is MIT-licensed, small-surface, and deliberately "no magic," it sits closer to source you adopt than a dependency you trust. That makes "vendor it and own it" a legitimate third option alongside "install it" and "write our own 50–100 line base class" — and a PM should force that comparison rather than letting it default to composer require.
• Sequencing a legacy cleanup. If the roadmap includes taming array-soup in an existing Laravel app, this enables incremental adoption — one request/response or one action at a time — without a framework-wide migration or a big-bang refactor commitment.
• Feature use cases it directly enables: API request/response shaping, queue and event payload contracts, third-party API response mapping, and stable internal interfaces between modules where serialization must be explicit and greppable.
• The anti-decision it supports: deliberately not adopting a heavy DTO/validation framework when transformation needs are shallow. Explicit typed properties keep stack traces and IDE navigation honest, which reduces debugging cost — a real but hard-to-quantify line item.
• Scoping guardrail. It does not replace Laravel validation, Eloquent casting, or API resources. A PM should treat it as sitting between those layers as an internal contract, and should not let it be sold internally as a data layer or a validation solution.

Record the caveat in the decision log: 12 stars and 0 dependents is not an ecosystem signal — at best it is a code-quality signal. Any adoption means we are the maintainers now.

When to Consider This Package

Consider it when:

• You are on PHP 8+ and want typed public properties with constructor hydration and array serialization, and little else.
• Mapping needs are shallow: flat or lightly nested structures — no computed fields, no conditional transforms, no validation pipeline.
• You want zero reflection or __get/__set indirection so debugging and IDE navigation point at real code.
• The team is willing to fork or vendor. Evaluate this as source you are adopting, not a dependency you are trusting: check last commit date, open issues, test coverage, PHP version support policy, and whether the API surface is small enough to reimplement in an afternoon.
• The blast radius is contained — internal tooling, a single service boundary, an SDK wrapper — not a cross-team or public contract.
• Someone is named as owner. An unowned tiny dependency decays silently and then gets rewritten under deadline pressure.

Look elsewhere when:

• You need validation, Eloquent model casting, nested collection mapping, lazy/partial hydration, or transformation pipelines. spatie/laravel-data is the dominant Laravel answer and is the right comparison on maintenance risk alone; symfony/serializer if you are framework-agnostic. Plan to reassess if requirements grow in this direction rather than extending the package yourself.
• The DTOs will be a public or cross-team contract. Near-zero adoption is a supply-chain and bus-factor question, not just a code-quality question.
• You need a documented security or long-term-support posture. There isn't one.
• Performance is a first-class constraint and you have not benchmarked. "No magic" suggests it should be competitive — that is an assumption to verify, not a selling point to repeat.
• Nobody wants to own it.

Verification checklist before adoption: confirm the actual API against source rather than the description (hydration, nested DTO handling, nullable/union behavior, collection support); confirm PHP 8.1/8.2/8.3+ support and current Laravel compatibility; confirm a test suite exists and runs; check PHPStan/Psalm friendliness; pin the commit and record the fork point in the ADR.

How to Pitch It (Stakeholders)

For executives: This is a small, free, MIT-licensed PHP utility that lets us define explicit, typed data structures at the boundaries of our application instead of passing loose arrays around. It is a low-cost, low-risk experiment — not a platform bet. The only real risk is not cost or licensing; it is that the project has negligible community adoption, so we would effectively own the code. Recommendation: pilot it on one bounded surface area, with the decision treated as reversible within a sprint.

For engineering leads: The appeal is the absence of magic — typed properties, no reflection-heavy hydration, no dynamic accessors, so debugging and IDE navigation stay honest. The trade-off is that we inherit maintenance. Before adopting: read the source (it is small), run the test suite, pin a commit, record the fork point, and isolate it behind an internal base class or adapter so it doesn't spread across the codebase. Start with one endpoint — request → validation → DTO → action → response — and define conventions for nested DTOs, dates, enums, and nullability before expanding. If requirements grow into validation, Eloquent casting, or nested collection mapping, stop and re-evaluate against spatie/laravel-data rather than building that ourselves.

For the delivery plan: integration effort is low; the cost is discipline, not code. Budget for conventions, one reference implementation, static analysis rules, and contract tests on hydration/serialization edge cases. Failure modes to watch: type errors on hydration, missing/extra fields, inconsistent nested handling, serialization drift against API resources, and Composer or PHP-version conflicts.

The one-line framing: Cheap to try, cheap to abandon, and cheap to own — worth a pilot, not worth a dependency you never look at again.