Yadm Laravel Package

Product Decisions This Supports

• ODM selection for MongoDB-backed features. Yadm (Yet Another Document Mapper) is a direct alternative to Doctrine MongoDB ODM or jenssegers/mongodb. It informs the build-vs-buy decision for the persistence layer: adopt a proven fast mapper instead of hand-rolling hydration and change tracking.
• Throughput-sensitive roadmap items. Its stated value is "extremely fast persistence and hydration," which makes it relevant to decisions about read-heavy APIs, high-volume ingestion, event/audit log storage, catalog or content services, and any endpoint where serialization of large document sets is the bottleneck.
• Feature feasibility calls. If the team can demonstrate a 2–5x hydration improvement, features previously deferred for performance (bulk exports, wide list endpoints, per-request multi-document assembly) can be re-scoped into the near-term roadmap.
• Architecture choices within Laravel. Supports a split-persistence strategy: Eloquent/MySQL for transactional relational data, Yadm for document-shaped read models or aggregates. The decision point is whether the added cognitive load of a second ORM is justified by measured speed.
• Technology risk and tech-debt planning. The 2019 last release and 84 stars are decision inputs: adopting Yadm is a commitment to vendor/fork and internally own the library, which should be priced into the roadmap as maintenance capacity, not treated as a free dependency.
• Data migration and schema evolution strategy. Yadm's mapping/hydration model affects how document shapes are versioned and migrated; this should be decided before, not after, the first production dataset.

When to Consider This Package

Consider it when:

• MongoDB is already the chosen store and the domain model is genuinely document-shaped (aggregates, nested value objects), not relational data forced into documents.
• Performance is a measured, demonstrated problem — you have profiles or benchmarks showing hydration/serialization dominating request time, not speculation.
• The workload is read-heavy with large result sets, where identity map, partial hydration, and eager loading reduce round trips and object-construction cost.
• The team is comfortable reading a small library's source and can fork it, pin a version, and apply patches. Treat it as an internal, vendored component rather than an upstream-supported dependency.
• PHP version compatibility has been verified in a spike (the 2019 release predates recent PHP runtimes; confirm it runs cleanly on your target version before committing).
• You need a smaller conceptual footprint than Doctrine's ODM and are willing to give up its ecosystem (migrations tooling, community modules, documentation depth).

Look elsewhere when:

• You need an actively maintained dependency with security patching, an issue tracker with a response SLA, and PHP 8.x+ guarantees — Doctrine MongoDB ODM or the Laravel-native mongodb/laravel-mongodb are safer defaults.
• Your team expects documentation, tutorials, and Stack Overflow coverage; Yadm's small community means onboarding cost is borne internally.
• The application is CRUD-simple and MongoDB access is a minor part of the request — the performance win won't materialize, and the maintenance cost is pure overhead.
• You depend on mature support for complex aggregations, transactions, gridFS, or schema migrations; verify coverage explicitly in the spike rather than assuming parity.
• Compliance or procurement requires a maintained vendor with a current release cadence and a support channel.

How to Pitch It (Stakeholders)

To executives: Yadm is a free, MIT-licensed performance library for MongoDB. The pitch is a cost-avoidance and latency story: it lets us serve document-heavy endpoints faster without adding infrastructure or scaling out MongoDB prematurely. The honest counterweight is that it is a small, low-activity project last released in 2019 — so the proposal is not "add a dependency," it is "adopt and internally own a small piece of infrastructure." Ask for a bounded, time-boxed spike (one to two sprints) with a benchmark gate: if it does not deliver a clear, measured improvement over Doctrine or the Laravel MongoDB driver, we stop and keep the default stack. Do not approve it as a silent dependency.

To engineering: This is a framework-agnostic PHP ODM built around fast hydration and persistence — identity map, partial hydration, eager loading — so it fits behind a Laravel service provider alongside Eloquent rather than replacing it. The trade-offs are explicit: no upstream maintenance, thin docs, small community, and a 2019-era PHP baseline that must be validated against our runtime. If we proceed, we fork it, pin the fork, add it to our dependency-ownership register, and cover our document mappings with integration tests so upstream silence never becomes a production incident. The success criteria are benchmark numbers we agree to before we start, not enthusiasm after a demo.