Value Objects Bundle Laravel Package

Product Decisions This Supports

• Build vs. buy for domain primitives. Every fintech/commerce-adjacent product re-implements the same core primitives: money amounts, currency, IBAN/BIC, email, phone, tax IDs, addresses, date ranges. This bundle is a ready-made answer to "do we build our own Money/Email/Iban layer, or adopt one?" — adopting lets the team spend the sprint on differentiating features instead of validation edge cases.
• Consistency across squads and services. A shared value-object bundle makes "what is a valid IBAN?" a single library concern rather than N slightly different regexes. That directly supports decisions about platform standardization and shared-kernel ownership.
• Defect-class elimination as a roadmap input. Money rounding, currency mismatches, and unvalidated identifiers recur as production incidents and support tickets. Choosing this package trades a small dependency for a measurable reduction in that incident class — quantify against your last 6–12 months of bug taxonomy.
• Compliance and data-quality posture. Immutable, self-validating objects make it structurally hard to persist an invalid IBAN or a negative amount that shouldn't be. That supports KYC/AML onboarding, payouts, invoicing, and any domain where auditors ask "how do you guarantee this field is well-formed?"
• Localization / market expansion. A bundle from a German-market company typically encodes DE/EU conventions (IBAN, BIC, VAT/tax IDs, EUR). That makes it a lever for "how fast can we launch in DACH?" — and a constraint to check if the roadmap goes multi-currency or multi-country.
• API and persistence contract decisions. Value objects with Eloquent casts and serialization behavior shape database columns, JSON payloads, and OpenAPI schemas. Adopting them early is cheap; retrofitting into an existing schema is a migration project.
• Make-vs-fork for internal reuse. Because the package is effectively a public dump of one company's internal conventions, the real decision is often not "adopt or not" but "vendor/fork as an internal shared library, or write our own thirty lines" — the fork preserves the design work while removing the supply-chain question.

When to Consider This Package

Consider it when:

• You are on Laravel + Eloquent and want value objects that cast cleanly to and from model attributes, form requests, and API resources — the bundle framing suggests exactly this integration layer.
• You have repeated, scattered validation of the same primitives (money, IBAN, email, phone, address) across multiple models or services, and duplication is already causing bugs or review friction.
• Your domain is DACH/EU-facing: EUR amounts, IBAN/BIC, German address and tax identifiers. Verify this against the source before committing.
• You need immutability and type safety enforced at the boundary, not just by convention and code review.
• Your team is small enough that writing primitives is a real opportunity cost, and large enough that cross-service inconsistency is already a problem.
• You are willing to vendor the code into your repo or your own package and own it from day one.

Look elsewhere — or treat it as reference material only — when:

• Adoption signals matter to your risk model. With zero stars and zero dependents, this is not a community-vetted dependency: no ecosystem evidence of production hardening, no third-party issue history, no maintenance guarantee. Unless you vendor and own it, you take single-maintainer risk on code sitting directly in your money and identity paths.
• You need battle-tested financial correctness. For monetary values, moneyphp/money plus brick/money has years of edge-case coverage (rounding modes, allocation, currency arithmetic). Do not let a convenience wrapper be the only thing between you and a rounding bug.
• A maintained, widely used alternative exists for the specific primitive — dedicated IBAN or phone libraries, symfony/uid, Laravel's own casts. Prefer one narrow, well-used dependency per concern over one bundle hiding several.
• You are not on Laravel, or use a different persistence layer (Doctrine, raw PDO, event-sourced stores) — the value is largely in the framework glue, which won't transfer.
• Your roadmap is explicitly multi-currency or multi-jurisdiction and the package encodes single-market assumptions you'd have to fight.
• You cannot fork. If policy forbids vendoring and the package isn't maintained, write your own — it is genuinely a few hundred lines for the subset you need.

How to Pitch It (Stakeholders)

To executives — the business case in one paragraph: We keep paying for the same class of bug: malformed IBANs, rounding errors on amounts, inconsistent phone and address data reaching downstream systems. This bundle wraps those primitives in validated, immutable objects that plug into our existing Laravel models, making invalid data structurally hard to write rather than something we catch in review or in production. The proposal is to vendor the code into our repo during a one-week spike, prove it on a single bounded context (payments or onboarding), and measure defect and review-time impact before rolling out. Cost is low and reversible; the upside is a permanently smaller bug surface in the areas most likely to attract compliance scrutiny.

To engineering — the honest framing: The design is sound and the integration pattern (Eloquent casts, validation, serialization) is the right shape for us. The caveat is maturity: zero stars, zero dependents, no public issue history, and a GitLab host that reduces ecosystem tooling and discoverability. So we do not take it as a Composer dependency in production. We vendor it, add our own test suite around the primitives we actually use, pin it in an ADR, and assign an owner. We carve out pieces we don't need (market-specific identifiers we don't operate in) and replace anything money-related with moneyphp/money if the bundle's arithmetic isn't provably equivalent. We keep our own namespace in front of it so there is a one-file-per-type exit ramp. Success criteria for the spike: the same three bugs from last quarter's taxonomy become unrepresentable, and we delete more validation code than we add.

To the security/compliance reviewer: Every value object validates at construction, so an instance existing at all is evidence the value is well-formed — easy to demonstrate in an audit, hard to achieve with scattered regex checks. Immutability removes a class of mutation-after-validation bugs. Supply-chain exposure is deliberately minimized by vendoring rather than depending, and no new runtime or daemon is introduced.

Ask: one engineer, one week, one bounded context, one ADR — with a go/no-go gate on test coverage and a rollback that costs nothing more than deleting the fork.