Yadm Bundle Laravel Package

Technical Evaluation

Architecture fit. The package is not a Laravel package — it is a Symfony bundle (makasim/yadm-bundle) wrapping makasim/yadm, a lightweight MongoDB document mapper positioned as a faster alternative to Doctrine MongoDB ODM. The bundle provides the Symfony-specific surface: a DI extension, configuration tree, compiler passes, console commands, and (likely) a profiler data collector. The value — "extremely fast persistence and hydration" — lives in the underlying yadm core library, which is framework-agnostic. For a Laravel codebase, the bundle itself is architecturally inert; only the core library is a candidate.

Integration feasibility. Low for the bundle, moderate for the core library.

• The bundle's Composer constraints were last touched in May 2019 and almost certainly pin symfony/framework-bundle, symfony/dependency-injection, and symfony/config to the 3.4/4.x line and PHP to 7.x. A modern Laravel app pulls Symfony 6.x/7.x components transitively, so composer require will either fail resolution outright or require --with-all-dependencies surgery that leaves two incompatible Symfony majors in the tree.
• The core yadm library can be instantiated manually (DocumentManager + mapping config + hydrator generation) inside a Laravel service provider, but that is us writing the integration layer that the bundle used to provide.
• Practical feasibility is therefore: "adopt a 2019 unmaintained library and own its framework glue," not "install a package."

Technical risk. High.

• Abandonment: last release May 2019, 7 stars, 0 dependents, single maintainer with no evident roadmap here. No upstream security response path.
• Runtime compatibility: hydration in yadm relies on generated/reflective object construction and metadata introspection — exactly the surface most affected by PHP 8.x changes (ReflectionParameter::getClass() deprecation, typed property semantics, dynamic property deprecation). Expect fatal errors or silent mis-hydration on 8.1+ until patched. Validate with a spike, do not assume.
• Driver drift: the pinned mongodb/mongodb library and ext-mongodb assumptions predate several driver majors. Some aggregation/session/bulk-write APIs will be unavailable or behave differently.
• Unvalidated premise: the "extremely fast" claim is the entire reason to accept the above risk. It is unbenchmarked in our context and may be reproducible with lean projections on a maintained driver.
• Signal quality: the 0.125 score and 1.91 opportunity figure are consistent with "tiny, stale, unused" — treat as a red flag, not a hidden gem.

Key questions.

1. Is the target application actually Symfony 3.4/4.x, or is this being evaluated for a Laravel app? (If Laravel, the bundle is disqualified on mechanism alone.)
2. What is the read/write profile — high-volume document hydration in PHP workers, or ordinary CRUD where ODM overhead is irrelevant?
3. Do we need ODM semantics (identity map, unit of work, references, lifecycle events), or would a thin repository over mongodb/mongodb suffice?
4. What is the measured gap between this and mongodb/laravel-mongodb (official, maintained) on our real document shapes?
5. Does our dependency policy permit unmaintained, single-maintainer libraries in production? Who signs off?
6. Can we fork and harden it (licence permits — MIT), and do we have the PHP internals depth to maintain reflection-based hydration?

Integration Approach

Stack fit. Decouple the decision. If the host is Laravel, do not install the bundle; bind the core library behind our own DocumentManager interface in a service provider so the persistence engine is swappable. The default recommendation for a Laravel + MongoDB stack is mongodb/laravel-mongodb (official, actively maintained) or raw mongodb/mongodb with a hand-rolled repository layer; both eliminate the framework-glue and PHP-8 support problems entirely.

Migration path. Treat persistence as an interchangeable adapter from day one:

• Define an internal repository/port interface; implement it once against yadm and once against the incumbent or official driver.
• yadm's mapping is explicit (array/YAML/PHP config) rather than annotation-driven, which actually helps migration — metadata is declarative and mechanically translatable to Doctrine ODM attributes or to the official package's schema.
• Because MongoDB collections and document shapes are engine-independent, swapping mappers is a code refactor, not a data migration — provided we avoid yadm-specific storage conventions (custom _id generation strategies, embedded-document ordering assumptions) in the persisted schema.

Compatibility. Validate in this order during the spike, on the exact target PHP and MongoDB server versions:

1. composer require makasim/yadm (not the bundle) resolves cleanly.
2. DocumentManager constructs, generates hydrators, and round-trips a representative nested document.
3. PHP 8.1+ deprecation/fatal surface is enumerated — this is the go/no-go input, not a footnote.
4. ext-mongodb and mongodb/mongodb versions align with what the platform team supports.

If the bundle is genuinely required (legacy Symfony app), pin the whole Symfony minor line for that service and isolate it — do not let it contaminate shared libraries.

Sequencing.

1. Week 1–2 — Spike: core library only; round-trip + hydrate a realistic document; record failures on target PHP.
2. Week 2–3 — Benchmark: hydration throughput, per-document memory, write throughput, large-result-set behaviour vs. the official Laravel MongoDB package. This decides everything.
3. Week 3–5 — Fork & harden (conditional on a positive benchmark): strip the bundle, widen Composer constraints, add PHP 8.2 CI, fix reflection/typed-property issues, publish internally under our vendor namespace.
4. Week 5–6 — Adapter layer: service provider + repository port implementation behind a feature flag.
5. Week 6+ — Incremental rollout per collection/aggregate, with the official driver path retained as fallback.

Decision gate: proceed past step 2 only if the benchmark shows a material (>20–30%) improvement on a workload we actually run. Absent that, the risk is uncompensated.

Operational Impact

Maintenance. We become the maintainer. Budget roughly 1–2 engineer-weeks of initial hardening plus ~0.1 FTE ongoing (PHP minor upgrades, dependency bumps, hydration regressions). All patching is manual by definition — there is no upstream to consume. The internal fork should drop the Symfony bundle surface entirely; keeping it multiplies the upgrade cost every time Symfony ships a major.

Support. Effectively none. 7 stars, 0 dependents, no community, no vendor, negligible Stack Overflow coverage, and thin documentation (README-level). Debugging falls entirely to the adopting team, and the fastest diagnostic path is reading library source. Add an explicit knowledge-concentration risk: the maintainer's attention has visibly moved to other projects.

Scaling. The choice of mapper does not change MongoDB's scaling characteristics — sharding, replica sets, and index strategy are unaffected. What it changes is PHP-side cost per document (CPU for hydration, memory per unit of work), which matters for high-volume read APIs and queue consumers. Two caveats: the unit-of-work/identity map retains hydrated objects, so large result sets inflate worker memory and can push long-running consumers toward OOM; and horizontal scaling of PHP workers is unchanged, so the win is density-per-worker, not capacity. Validate on a replica set with production-shaped documents.

Failure modes.

• Build blocked: Composer resolution failure against modern Symfony components / PHP 8 — high likelihood, detected early.
• Runtime fatal: deprecated reflection APIs or typed-property assignment on missing document fields.
• Silent corruption: document-shape drift produces partially hydrated objects that fail only on property access downstream — the worst class of bug, and the reason for golden-file round-trip tests.
• Stale reads / memory bloat: identity-map retention in long-lived queue workers.
• Supply chain: pinned, unpatched transitive dependencies (mongodb/mongodb, old symfony/*) with no CVE response path.
• Bus factor 1: no fix available if the maintainer is unreachable; mitigation is the fork, which is also the cost.
• Null result: we pay adoption and fork cost and discover the performance premise doesn't hold on our workload.

Ramp-up. A Symfony-fluent engineer needs 2–3 days for yadm's concepts (explicit mapping, unit of work, hydrator generation). A Laravel-only team should plan 1–2 weeks including fork mechanics, plus separate MongoDB schema-design competency. Internal documentation, a mapping cookbook, and a hydration regression suite must be authored — none of it exists upstream.

TPM recommendation. Do not adopt for a Laravel stack; the bundle is structurally inapplicable and the core library is unmaintained and PHP-8-at-risk. Run the two-week benchmark against the official mongodb/laravel-mongodb package first — lean projections on a maintained driver typically capture most of the hydration win with none of the ownership burden. Reserve a yadm PoC for the narrow case of an existing Symfony 3.4/4.x service already depending on it, where the question is migration cost rather than adoption.