Adaptive Entity Manager Bundle Laravel Package

Product Decisions This Supports

• Domain-modeling depth vs. delivery speed: this bundle lets entities carry value-object metadata (money, email, identifiers, date ranges) without hand-rolling mapping, hydration, and persistence plumbing per entity. That is a build-vs-buy decision you can now defer rather than re-litigate each quarter.
• Shared kernel / platform standardization: 3.1.0's split of ValueObjectAwareEntityManagerInterface from the base EntityManagerInterface signals a stable, contract-first design. Teams can standardize on the bundle's entity manager as the single persistence surface across services instead of one bespoke implementation per bounded context.
• Roadmap for "rich domain, thin framework" initiatives: if the roadmap includes moving business rules out of controllers/services into domain objects, this package is a credible enabler. It is the kind of dependency that shortens the runway for a DDD-lite migration.
• Upgrade-cost budgeting: 3.1.0 tightens field metadata validation and shifts VO helpers onto a narrower interface. This is a minor-version release with real typehint implications — it belongs in the sprint's tech-debt allocation, not a "silent composer update."
• Criteria/storage alignment: the upstream 1.6 line aligns query criteria with storage behavior, which reduces the class of bug where filtering in code and filtering in the database disagree. That is a correctness argument for feature work involving search, saved views, or reporting filters.

When to Consider This Package

Adopt when:

• Your entities genuinely have value-object-shaped fields (money, quantities, periods, identifiers) and you are currently flattening them into scalars plus accessor glue.
• You have, or expect, more than one entity manager / persistence path and want a shared contract rather than duplicated metadata logic.
• You are on a supported Laravel/PHP baseline and are comfortable taking a dependency on a small, single-maintainer package line (kabiroman/*) — i.e. you have a fork-and-patch contingency, or the blast radius of removal is contained.
• You can absorb a minor-version upgrade with a typing caveat: any application code that typehints EntityManagerInterface and calls VO helpers (getValueObjectRegistry(), hasValueObjectSupport()) must switch to ValueObjectAwareEntityManagerInterface or the concrete AdaptiveEntityManager. Budget this before adopting, because it is a recurring pattern, not a one-off.

Look elsewhere when:

• Your domain is thin CRUD — Eloquent casts, custom cast classes, and accessors cover it with far less surface area.
• You need a vendor with an SLA, long-term support commitments, or a large contributor base. This is a focused library, not an enterprise platform.
• Your team has no appetite for maintaining interface-level abstractions; the value only materializes if the abstraction is used consistently, otherwise it becomes an indirection tax.
• You are mid-freeze on a release train and cannot schedule the typehint audit that 3.1.0 implies.

How to Pitch It (Stakeholders)

To executives (one paragraph): We are evaluating a small Laravel package that lets our domain objects own their own validation and value semantics — prices, emails, date ranges — instead of scattering that logic across controllers and services. The latest release (3.1.0) is a maturity signal: it separates the value-object-aware contract from the general entity manager, so teams can depend on the narrower, safer interface, and it tightens field metadata validation, which means fewer silent data-shape bugs. Cost is a small, time-boxed upgrade — a dependency bump plus a targeted audit of typehints where we call value-object helpers. Recommendation: adopt in one pilot service, keep the upgrade in this sprint's tech-debt budget, and treat it as a build-vs-buy saving on custom mapping code rather than as new scope.

To engineering (summary): adaptive-entity-manager-bundle 3.1.0 requires kabiroman/adaptive-entity-manager ^1.6, which brings value-object metadata that no longer depends on ValueObjectInterface, a dedicated ValueObjectAwareEntityManagerInterface, criteria/storage alignment, and stricter field metadata checks. Bundled services still expose the concrete AdaptiveEntityManager. The upgrade action is explicit: run composer update kabiroman/adaptive-entity-manager-bundle, then grep for EntityManagerInterface typehints on any call site using VO helpers and retarget them to ValueObjectAwareEntityManagerInterface or AdaptiveEntityManager. Stricter metadata means some previously-tolerated field definitions will now fail fast — expect a short tail of fixture/config fixes. No deprecations were announced, and the concrete manager satisfies both contracts, so runtime breakage should be limited to interface-level typehints and any metadata that was previously accepted loosely. Land it behind the existing test suite, in its own PR, before the next feature branch cut.