Adaptive Entity Manager Bundle Laravel Package

Getting Started

• Pull the bundle in with composer require kabiroman/adaptive-entity-manager-bundle:^3.1. This release pins kabiroman/adaptive-entity-manager:^1.6, so the DOM/value-object layer arrives as a transitive dependency — don't require it separately at a different constraint or you'll get a solver conflict.
• Register the bundle/service provider and confirm the container resolves the entity manager. In a Laravel app the bundle's services land in the container as-is; bind whichever interface your application code depends on in AppServiceProvider::register() rather than typehinting the concrete class everywhere.
• Look here first: ValueObjectAwareEntityManagerInterface, then the concrete AdaptiveEntityManager service. In 3.1.x the VO helpers (getValueObjectRegistry(), hasValueObjectSupport()) live on the aware interface only — reading these two files tells you what the bundle actually exposes before you touch config.
• First use case: take an existing model that is currently mass-assigned from a request array (or hydrated from a storage row) and route it through the entity manager instead — array/storage payload → field metadata → domain object with value objects constructed in the right order. Start with one aggregate, one storage adapter, and assert the round-trip in a test before expanding.

Implementation Patterns

• Typehint deliberately. Inject plain EntityManagerInterface for anything that only creates/persists/removes entities. Inject ValueObjectAwareEntityManagerInterface only in the classes that actually need getValueObjectRegistry() or hasValueObjectSupport(). Mixing the two in one class is the fastest way to carry 3.1.0's interface split into your whole codebase.
• Bind once, not everywhere. $this->app->bind(ValueObjectAwareEntityManagerInterface::class, AdaptiveEntityManager::class) in a service provider keeps the rest of the app free of concrete-class references — important because the bundle's own services are still registered as AdaptiveEntityManager.
• Hydration flow. Build a single "write" path: request payload → validated DTO → entity manager → entity → storage. Keep the manager out of controllers; wrap it in an application service per aggregate so the criteria and storage choices live next to the domain they serve.
• Use criteria objects for reads. Pass criteria rather than raw query fragments so the same criteria can be evaluated against different storage adapters and against in-memory collections in tests. This is the main reason to reach for the package over hand-rolled repositories.
• VO metadata is now plain domain metadata. Without a required ValueObjectInterface, you declare value-object fields explicitly in field metadata instead of relying on interface detection. This is more verbose but removes the "implement an interface you don't want" tax on domain classes — lean into it by keeping your domain classes free of package interfaces entirely.
• Testing. Point the manager at an in-memory/fake storage adapter in unit tests and assert on the object graph plus the registry contents, not on generated SQL. Keep one integration test per aggregate against the real adapter so criteria/storage drift gets caught.

Gotchas and Tips

• The 3.1.0 upgrade trap: any application code that typehints EntityManagerInterface and then calls getValueObjectRegistry() or hasValueObjectSupport() will fail after composer update. Grep for those two method names and for EntityManagerInterface in the same file; switch those callsites to ValueObjectAwareEntityManagerInterface (or AdaptiveEntityManager) rather than widening the plain interface.
• Bundle services were not renamed. Container aliases still resolve to AdaptiveEntityManager. Don't "clean up" your bindings to an interface that the bundle never registers — you'll get Target [X] is not instantiable at resolution time.
• Stricter field metadata is a runtime, not compile-time, failure. Missing or incomplete field metadata that used to be inferred now throws when the manager builds its map — usually on first hydrate, not at boot. Run your fixture/test suite immediately after upgrading rather than discovering this in a request.
• Losing interface-based VO detection means old entities that were picked up implicitly will now be treated as plain fields. Symptom: value objects come back as raw scalars/arrays in hydrated entities. Fix by adding the explicit metadata entry.
• Criteria/storage alignment: the 1.6 alignment work means criteria are validated against what the storage actually supports. A criteria your adapter can't express may now surface as an error instead of a silently wrong result set — but older adapters can still degrade to in-memory filtering, so confirm which path your adapter takes.
• Debugging aids: dump getValueObjectRegistry() and the resolved field metadata for one entity to see exactly what the manager knows; confirm hasValueObjectSupport() is true on the instance you injected; app()->bound(...) checks catch alias mistakes fast.
• Extension points to keep in mind: custom storage adapters, custom metadata sources, and (if you need it) decorating the entity manager rather than extending AdaptiveEntityManager — the concrete class is the bundle's, so decoration keeps your upgrades clean.