Valueobjects Laravel Package

Product Decisions This Supports

• Build vs. buy on domain primitives. This library is a candidate answer to "do we hand-roll Money, Email, Uuid, Phone, DateRange, or adopt a VO/entity toolkit?" That decision recurs in every billing, invoicing, identity, and KYC feature, so it is worth making once, deliberately, rather than per-squad.
• DDD adoption roadmap. If the roadmap includes moving from anemic Eloquent models to a richer domain layer, this package represents the "buy the building blocks" branch of that roadmap. Deciding against it is equally valuable: it tells engineering to standardize on native PHP 8.1+ readonly classes and a small internal primitives package instead.
• Invariant placement. The core product argument is defect prevention: validation and equality semantics live in one object instead of being re-implemented across form requests, jobs, and observers. That changes how we scope work on money handling, currency conversion, tax, and user identity — it becomes a refactor task with a shared vocabulary, not a per-feature concern.
• Standardization across teams. A shared VO vocabulary (Email, Money, Uuid) reduces the surface area of cross-team contracts and API boundaries. This is a platform-team decision, not a feature-team one.
• Sequencing. The opportunity score of 6.17 against an overall score of 0.305 is the key signal: the problem is real and worth solving; the package is not yet a proven vehicle. That argues for solving it now with a low-risk approach rather than deferring.

When to Consider This Package

Consider it when all of the following hold:

• You are building a greenfield domain layer where value objects are genuinely load-bearing (financial amounts, identifiers, regulated data), not just aesthetic.
• Your legal/procurement posture tolerates LGPL-3.0. For most SaaS use as an unmodified dependency this is workable, but it requires sign-off and a rule against modifying/forking the library in-tree. This is a hard blocker in some enterprises.
• You are willing to absorb maintenance risk: 9 stars, 0 dependents, and a low overall score indicate effectively no production user base. Assume you may be the first to hit edge cases, and budget for reading the source rather than the docs.
• A one-to-two sprint spike is cheap relative to the cost of getting money/identity primitives wrong.

Look elsewhere when any of the following apply:

• You need a maintained, auditable dependency. With zero dependents and no visible downstream usage, there is no evidence of battle-testing. For money or identity parsing, prefer brick/money or moneyphp/money, ramsey/uuid or symfony/uid, egulias/email-validator.
• You want Laravel-native ergonomics. There is no indication of Eloquent casts, a service provider, validation rule bridges, or serialization integration. Verify before assuming; if absent, you are writing the glue yourself, which erodes the buy argument.
• You need a permissive license (MIT/Apache) for redistribution or for embedding in a distributed product. LGPL complicates this.
• Your PHP baseline is 8.1+. Native readonly classes, enums, and constructor promotion cover a large share of what this library offers, at zero dependency cost and with full team familiarity.
• You need vendor accountability — SLA, security disclosure process, or a versioning/deprecation policy.

Vetting checklist before any adoption: last commit date, CI status, test coverage, supported PHP versions, static-analysis level, open-issue responsiveness, and whether the entity half of the library imposes a persistence model that conflicts with Eloquent.

How to Pitch It (Stakeholders)

To executives: This is a small open-source library for modeling domain concepts like money identifiers and contact details as self-validating objects. It addresses a real and recurring problem — our scores suggest the problem space is worth roughly 6/10 — but the package itself is unproven (9 stars, no known dependents) and carries an LGPL license. Recommendation: do not adopt as a platform dependency now. Fund a short evaluation spike, and in parallel adopt the pattern using native PHP features or a maintained alternative. Cost of the decision is one sprint; cost of a bad bet is a domain layer built on an abandoned dependency.

To engineering: Treat this as a reference implementation and a pattern checklist, not a dependency. Read it for its handling of equality, immutability, and validation-at-construction. If we build internally, we get MIT-equivalent freedom, Laravel-native casts, and full control — at the cost of maybe 300–500 lines. If we buy, we should buy from a maintained project with dependents. Either way, the outcome we want is the same: one canonical Money, one canonical Email, validated at the boundary, never re-implemented.

Decision requested: Approve a timeboxed spike to compare (a) native readonly internal primitives, (b) brick/money + ramsey/uuid, and (c) runn/valueobjects, scored on maintenance risk, license fit, Laravel integration effort, and coverage of our money/identity invariants.