Laravel Value Objects Laravel Package

Product Decisions This Supports

• Primitive obsession cleanup / domain modeling. The package gives you ready-made immutable wrappers (email, phone, name, UUID-style identifiers, numeric and text types) so you can stop passing raw strings and ints through your domain. That is a build vs. buy decision: writing and testing a dozen small value objects is a week you could spend on features, and this package is MIT and readable enough to audit in an afternoon.
• Standardizing validation and normalization at the boundary. The recurring PM-visible problem is inconsistent handling — one form trims and lowercases emails, another doesn't; phone numbers arrive in five formats. A shared value-object layer turns "please be consistent" into an enforced contract, which reduces a class of support tickets and data-quality bugs without a re-architecture.
• Roadmap sequencing for a DDD-lite or modularization effort. If the roadmap includes extracting a shared kernel, splitting modules, or introducing typed boundaries between a Laravel monolith and a service, value objects are the cheapest first step. This package lets you prove the pattern on one bounded context before committing to a larger framework or a bespoke domain layer.
• Platform-upgrade readiness. Release 7.0.2 adds a PHP 8.4 test matrix. If a PHP 8.4 / Laravel upgrade sits on the roadmap, the package is now explicitly exercised against it rather than merely hoping to be compatible — a small but real de-risking of the upgrade track.
• Onboarding and cross-team consistency. New engineers get typed, self-documenting signatures (Email $email rather than string $email) and a single place to look for the rules. That shortens review cycles and reduces "how do we validate X here?" questions.
• Dependency risk budgeting. Still the honest framing: ~205 stars, effectively one maintainer, zero dependents, low overall score against a high "opportunity" score. The category is underserved and useful; this specific package is a utility, not battle-tested infrastructure. 7.0.2 is a mildly positive signal — a correctness fix plus CI expansion, with a first-time outside contributor — but it is a patch release on a thin project, not evidence of a support commitment. Treat adoption as "vendor a utility," not "adopt a platform."

When to Consider This Package

Adopt when:

• You're a Laravel shop with duplicated, drifting validation/normalization logic across controllers, form requests, and jobs.
• You want value objects as a utility, not as a framework — small surface, no runtime magic, no persistence opinions.
• You're doing a first, low-risk DDD pass and want to demonstrate value quickly on one or two types (email, phone, name) rather than a full domain layer.
• You need something permissive (MIT) that you can fork or vendor without legal or upgrade friction.
• You're on, or moving to, PHP 8.4 and want dependencies that are at least tested against it — 7.0.2 covers this.
• Use 7.0.2 or later, not 7.0.0/7.0.1. The 7.0.2 patch fixes negative-number handling in the Number value object. If any code path relied on signed numeric value objects before this fix, audit those call sites for silently wrong results — this is exactly the class of data-quality defect the package exists to prevent, so patch discipline is part of the deal.
• You're comfortable pinning a version and owning the code if the maintainer goes quiet.

Look elsewhere when:

• You need money/currency. Don't use a generic value-object grab bag for monetary correctness; use a dedicated library (brick/money or equivalent) with rounding, allocation, and currency semantics. The recent Number negative-handling fix reinforces that generic numeric wrappers are not a substitute for a domain-specific money type.
• You actually need DTOs, hydration, or request mapping. spatie/laravel-data is the mature answer; this package won't cover casting, nested objects, or transformation.
• You need typed IDs across models. Look at Eloquent-level casting options or a dedicated typed-ID package rather than hand-rolling UUID/Eloquent glue here.
• Your domain rules are non-trivial or regulated. Phone numbers are the classic trap — region-specific parsing and formatting need a real library (e.g., libphonenumber-backed), not a regex. Same for addresses, tax IDs, and anything compliance-adjacent.
• Your org requires maintained dependencies with a support path. One maintainer, near-zero adoption, and an infrequent release cadence remain a governance objection you should expect and plan for. A patch release does not change that conversation.
• You're not prepared to wrap it. If you intend to sprinkle the vendor classes directly through your domain, the switching cost later is higher than the cost of writing your own.

How to Pitch It (Stakeholders)

To executives: This is a small, free (MIT) utility library that helps us enforce consistent, correct data handling — emails, phone numbers, names, identifiers — in one place instead of scattered ad-hoc checks. The expected payoff is fewer data-quality defects and faster reviews, at roughly the cost of a few days of integration work. The risk is contained and easy to reason about: the library is a thin, readable code layer, not a platform, and because it's MIT we can vendor it or replace it if it stops being maintained. Its latest patch includes a correctness fix for numeric values and adds coverage for PHP 8.4, which keeps it aligned with our upgrade path. Recommendation: approve as a scoped pilot in one module, with a review gate, rather than a codebase-wide standard. Success looks like measurably fewer validation-related bugs and no increase in support load.

To engineering: It's a curated set of immutable value objects with Laravel-friendly ergonomics — validation and normalization live in the type, so signatures become self-documenting and invalid states become hard to construct. It's deliberately small, so audit it before adopting, pin it, and wrap it behind our own interfaces (e.g., our own Email extending or adapting theirs) so we retain the option to swap or fork. Land on 7.0.2 or newer: it fixes negative-number handling in Number, so re-check any signed-numeric usage, and it adds a PHP 8.4 test matrix, which matters for the upgrade roadmap. Do not use it for money, phone-number parsing, or complex DTO hydration — bring in dedicated libraries there. Budget a short spike: read the source, pick 2–3 types, apply them at one boundary, and measure. Treat the low adoption and single-maintainer signal as a reason to own the code locally, not a reason to avoid the pattern.