Skeleton Mapper Laravel Package

Product Decisions This Supports

• Read-path architecture: Informs whether to introduce a typed read-model layer for reporting, dashboards, exports, search, and other read-heavy endpoints where SQL is hand-written and results need to become typed PHP objects rather than arrays.
• Build vs. buy (or build vs. borrow): If engineering proposes hand-rolling a row-to-object hydrator to avoid ORM overhead, this package is the reference implementation. The realistic decision is "adopt, fork, or copy the pattern" — not "take a dependency and move on," given the archived status.
• ORM scope decisions: Helps draw the line between "reads go through hand-written SQL + mapper" and "writes/domain logic go through Eloquent or Doctrine ORM." Supports a pragmatic CQRS-lite split without a full architectural migration.
• Roadmap input: A data point for whether investing in a dedicated read-model/hydration layer is worth a sprint, or whether Eloquent API Resources, casts, or Doctrine ORM DTO hydration (SELECT NEW) already cover 90% of the need.
• Use cases where it fits: Legacy or externally owned schemas, complex joins and aggregates the ORM expresses poorly, high-throughput read endpoints, incremental migration of reads off an ORM.
• Explicit non-goals: Write paths, aggregates, identity map, unit of work, lazy loading, relations. This is not an ORM replacement and should not be scoped as one.

When to Consider This Package

Consider it when:

• Doctrine DBAL is already in the stack (standalone or via a Laravel–Doctrine integration), so the mapper is additive rather than a new dependency tree.
• You have hand-written SQL that must map to typed, immutable objects, and hydration cost has been measured as material on a hot path.
• The team is comfortable with code generation steps, non-standard mapping configuration, and accepting ownership of an unmaintained library (vendoring or forking).
• The scope is deliberately narrow: one or two read endpoints in a spike, with a benchmark against the incumbent approach.

Look elsewhere when:

• The application is a standard Laravel app — Eloquent with casts, API Resources, or spatie/laravel-data covers the same ground with first-class support and community.
• You need relations, lazy loading, or a unit of work — use Doctrine ORM with DTO hydration, which is maintained and documented.
• The product is long-lived and subject to security or dependency-lifecycle policy. An archived package with ~100 stars and no upstream support is a procurement blocker regardless of technical merit.
• No Doctrine experience on the team, or the read path is simple CRUD where the setup cost exceeds any benefit.
• You require a vendor SLA, security patching, or framework-version compatibility guarantees.

How to Pitch It (Stakeholders)

To executives: This is a narrow technical experiment, not a platform commitment. The package is archived and lightly adopted, so the recommendation is to spend a short spike proving whether typed read models measurably improve our slowest read endpoints — then either implement the pattern in-house or fork it. We should not put an unmaintained dependency on the production critical path without an explicit ownership plan. Downside is bounded and reversible; upside is simpler, faster read code.

To engineering: It is a focused data mapper for DBAL result sets into typed objects, with code generation replacing reflection-based hydration. It solves a real problem — typed reads without ORM overhead — and is worth benchmarking against Doctrine ORM DTO hydration and Eloquent resources on one representative endpoint. Costs are the codegen step in the build, custom wiring (there is no Laravel service provider), and permanent ownership if adopted. Treat it as a design reference first, a dependency second.