Doctrine Value Object Laravel Package

Product Decisions This Supports

• Rich vs. anemic domain model: Gives the team a low-friction path to embedding real value objects (Money, Email, Address, DateRange, OrderId) directly in Doctrine entities instead of passing primitives around. This is a domain-modeling decision, not just a library choice.
• Build vs. buy for mapping boilerplate: The core value is eliminating repetitive #[Embeddable] / #[Embedded] wiring and constructor/setter noise. Decision input: is this worth an external dependency, or is it ~100–200 lines we should own internally? At 13 stars and 0 dependents, "vendor or fork" is a legitimate third option alongside build/buy.
• Persistence strategy lock-in: Only relevant if the product is on Doctrine ORM, not Eloquent. In a typical Laravel codebase this is a minority architecture decision; adopting this package effectively signals (or follows) a commitment to Doctrine + a DDD-style domain layer. Treat it as a downstream consequence of that architectural bet, not a driver of it.
• Roadmap scoping for a domain refactor: Useful as a sizing input when planning a "replace primitive obsession" epic — it reduces the per-value-object cost, which changes how many VOs are feasible in a given sprint.
• Consistency standard: Establishes one canonical way to map value objects, which supports code review criteria, onboarding docs, and static-analysis rules (e.g., "no raw strings for emails in entities").
• Not a differentiator: This does not move user-facing metrics. It should be funded from tech-debt/quality budget, not from a feature roadmap line.

When to Consider This Package

Consider it when all of the following hold:

• The service genuinely uses Doctrine ORM (Symfony-style, or Laravel with Doctrine via laravel-doctrine). If the stack is Eloquent, stop here — casts and custom cast classes already solve this.
• The domain layer has, or is about to have, multiple value objects (roughly 5+). Below that threshold, hand-rolled embeddables are cheaper than a dependency.
• PHP 8.1+ and Doctrine ORM 2.x/3.x compatibility are satisfied — verify against the released version (last release 2024-07-08), since ORM 3 attribute/mapping changes can break embeddable helpers.
• The team accepts a small-community, single-maintainer dependency and is willing to vendor/fork it under MIT.
• You want conventions enforced more than features delivered — the package's real payload is a pattern, not novel capability.

Look elsewhere (or don't adopt) when:

• Adoption risk outweighs the boilerplate saved. 13 stars, 0 dependents, no release in ~a year: no community backstop, no third-party battle-testing, and a bus-factor of one. For a long-lived core service, this is a maintenance liability.
• You need SLAs, security response, or vendor support. There is none.
• Custom DBAL types are the real requirement. Scalar value objects (UUIDs, money-as-minor-units) usually need a doctrine/dbal Type, not an embeddable — look at ramsey/uuid-doctrine or write a Type. Embeddables solve a different problem (composite values), and conflating them creates awkward schemas.
• Schema simplicity matters. Embeddables inline columns; if you need a single serialized/json column or a normalized table, you want a custom Type or a related entity.
• The alternative is trivial. Doctrine's native #[Embeddable]/#[Embedded] already covers the happy path; a 20-line internal trait may be strictly better than an unmaintained package.

Mitigation if adopted: fork into the org's VCS, pin the version, add contract tests around hydration/mapping, and assign an owner. Budget a small recurring maintenance line.

How to Pitch It (Stakeholders)

For executives (30 seconds): This is a small, free (MIT) utility that makes it cheaper for the engineering team to model core business concepts — money, emails, addresses, IDs — as proper typed objects instead of loose strings and floats, which reduces a class of data-integrity bugs. It is not a strategic bet and not a customer-facing feature; it's a quality-of-implementation lever with near-zero license cost. The main risk is that it's a tiny, single-maintainer open-source project, so we would fork it internally and own it rather than depend on it directly. Cost is a few engineering days, not a procurement cycle.

For engineering: It removes repetitive Doctrine embeddable mapping boilerplate so value objects drop into entities cleanly and consistently. It's a convention enforcer, not a framework. Caveats to state plainly: 13 GitHub stars, zero dependents, last release July 2024 — treat it as reference code, not a dependency. Recommended path: timebox a one-day spike against our actual Doctrine version, and if it earns its place, vendor the source into the repo with tests and an owner. If the spike shows friction, write the equivalent trait ourselves — the surface area is small enough that "build" is a credible competitor to "buy" here.