Data Mapper Laravel Package

Technical Evaluation

Architecture fit Laravel's default persistence layer is Eloquent, an Active Record implementation. thruster/data-mapper is a Data Mapper, meaning the domain model is intentionally decoupled from the database schema, with mapping metadata, an identity map, and (presumably) a unit of work living outside the entities. That is a legitimate architectural choice, but it is a replacement for Eloquent in the bounded context where it is used, not a supplement. Adopting it means forfeiting the surrounding Laravel ecosystem for those models: route model binding, model events/observers, factories and seeders, Illuminate\Database relationship ergonomics, Eloquent-based packages (Nova, Filament resources, Spatie permissions, Laravel Scout), and the debugging muscle memory of the team. Fit is therefore narrow: greenfield, domain-rich modules where DDD purity is an explicit requirement. For CRUD-shaped features it is a net negative.

Integration feasibility Low. The last release is April 2016, which places it in the PHP 5.5–7.0 / Laravel 5.1–5.2 era. A package that old will almost certainly declare php and illuminate/* constraints that conflict with PHP 8.1+ and Laravel 10/11 under Composer's platform checks; installation will likely require --ignore-platform-reqs or a fork, both of which shift compatibility risk onto us. It is also unclear whether the package is Laravel-aware at all — Thruster published framework components for its own platform, so there may be no service provider, no auto-discovery, and no config publishing. With 1 star and 0 dependents there is no evidence of anyone running it in production, and no issue corpus to mine for known breakages.

Technical risk High and concentrated in three places. (1) Abandonment: ~9 years without commits means no PHP 8 compatibility work — dynamic properties (8.2 deprecations), each() removal, curly brace string offsets, and Reflection/annotation parsing differences are all plausible failure points. (2) Unknown internals: mapping metadata format (annotations vs. XML/YAML), transaction and identity-map semantics, and lazy-loading strategy are all undocumented from the outside; these determine whether the risk is "annoying" or "data-corrupting." (3) Upgrade gravity: pinning the package effectively pins the host application's PHP and Laravel versions. MIT licensing removes legal friction but not the maintenance burden.

Key questions

• Does it depend on illuminate/* at all, or is it framework-agnostic (PDO-only)?
• Does it ship a Unit of Work with real transaction boundaries, and an identity map with defined scoping?
• What is the mapping metadata format, and is it validated at build time or at runtime?
• Does the test suite exist, and does it pass on PHP 8.2/8.3?
• Is Thruster's own platform still maintained, or was this component orphaned with it?
• What is the actual LOC and dependency fan-out (transitive risk)?

Recommendation: treat as a research spike at most. Doctrine ORM (laravel-doctrine/orm) or Cycle ORM are the mature Data Mapper options with maintained Laravel bridges; if Data Mapper is genuinely required, one of those is the defensible choice.

Integration Approach

Stack fit Only viable if the requirement is "Data Mapper, and specifically this one." That requirement is rare. The realistic decision tree: if the driver is domain purity, use Doctrine/Cycle. If the driver is avoiding Eloquent's God-object problems, a repository abstraction over Eloquent gets most of the benefit at a fraction of the risk. thruster/data-mapper sits in a third bucket — pure paradigm alignment with a package nobody else uses — and should be justified on grounds other than architecture.

Migration path Never retrofit onto an existing Eloquent-backed domain; a dual-persistence hybrid in one module is the worst of both worlds and will leak. If pursued at all, do it greenfield and bounded: one module, its own database connection, domain entities with no framework imports, repository interfaces declared in the domain layer, and the data mapper confined to an infrastructure adapter behind those interfaces. That anti-corruption layer is the only thing that makes the dependency reversible, and it should be non-negotiable if the spike proceeds.

Compatibility Before any code is written, fork to an org-owned namespace (acme/data-mapper) and validate: composer.json constraints, PHP 8.1–8.3 compatibility, presence/absence of a service provider, and whether the package's own tests exist and pass. Budget 2–4 weeks for PHP 8 hardening if the codebase is small (Thruster components were typically thin), plus static analysis (PHPStan level 6+) to surface runtime-only breakages. Pin the fork to an exact tag; do not float a branch.

Sequencing

1. Two-to-three-day spike: install the fork in a Laravel 11 skeleton, run its test suite, map one entity end-to-end, exercise a rollback. Hard go/no-go gate here.
2. If green: harden for PHP 8, add CI across PHP 8.1–8.3 × Laravel 10/11, publish the fork.
3. Build one bounded context behind repository interfaces; write contract tests against the repository, not the mapper.
4. Only after a production cycle, consider a second context. Do not scale adoption speculatively.

Operational Impact

Maintenance Ownership transfers entirely to us on day one. There is no upstream to send patches to — assume we are the maintainer forever. Minimum viable maintenance: fork under org control, CI matrix, PHPStan/deprecation gates, and a documented upgrade runbook for Laravel majors. Realistic ongoing cost is small but non-zero (a few days per year plus unplanned breakage), and it is unbudgeted if the spike is framed as "just a composer require."

Support No documentation, no active issue tracker, no Stack Overflow corpus, no vendor. Every question is answered by reading source. Onboarding is a double cost: the Data Mapper pattern (identity map, unit of work, mapping metadata) is unfamiliar to most Laravel developers, and there is no community to fall back on when the pattern and the package diverge. Assume 1–2 weeks per engineer to productive, plus documentation we write ourselves.

Scaling Unknown and unproven. Identity maps retain every loaded entity per request/worker scope, which can bloat memory on large result sets; there is no evidence of a second-level cache, batch iteration, or read/write split support. In long-running workers (Octane, Horizon) an unscoped identity map is a correctness hazard — stale entities across jobs — not just a memory one. Query design and read scaling revert to our team; the package provides no leverage there.

Failure modes (ranked by probability × impact)

1. Upgrade lock — Composer constraint conflict blocks the next Laravel or PHP major. Highest probability; remediation is a fork patch, unbudgeted.
2. Silent PHP 8 breakage — deprecations escalating to errors on a minor bump; caught only by CI we build.
3. Identity map staleness — stale reads or partial writes in queue/Octane contexts if transaction and scope semantics are undocumented or wrong.
4. Partial writes — if Unit of Work transactionality is incomplete, failures leave inconsistent state without the guardrails Eloquent's conventions normally give.
5. Unpatched vulnerability — no upstream means no CVE response; MIT gives us the right to fix, not the capacity.

Ramp-up Plan for one senior engineer to own the spike and the fork (2–3 weeks end-to-end), followed by 1–2 weeks per additional engineer for pattern and package fluency. Multiply by the number of engineers who will touch the bounded context. Weigh that against three-to-five days to wire Doctrine into the same context and get a maintained upstream, documentation, and a hiring pool that already knows it.