Valueobjects Laravel Package

Technical Evaluation

Architecture fit

• Framework-agnostic PHP value-object/entity primitives (interfaces, abstract bases, equality/serialization traits) sitting in a DDD-style domain layer. No Laravel service provider, facade, config, or container bindings — zero framework coupling, which is good for portability and bad for drop-in ergonomics.
• Laravel is not DDD-native; adopting this package means introducing a parallel modeling layer alongside Eloquent models. The natural seam is a domain boundary (domain entities/VOs behind repositories), not a wholesale replacement of Eloquent.
• The package is a base library, not a solution. Value delivery depends entirely on the glue a team writes: Eloquent custom casts (CastsAttributes), validation rules, form-request mapping, JSON resources, and factory/seed support. That glue is the real cost and is not shipped.

Integration feasibility

• Technically low friction: composer require runn/valueobjects, PSR-4 autoloading, no runtime dependencies on Laravel internals. Integration is additive and reversible.
• Real effort concentrates in four areas: (1) CastsAttributes for each VO persisted as a scalar column, (2) custom ValidationRule objects to keep request validation aligned with VO constructors, (3) JsonResource/JsonSerializable output contracts so APIs don't leak VO internals, (4) factories/seeders and tests that construct VOs rather than raw scalars.
• Because the package supplies abstractions rather than a curated set of concrete VOs (verify which concrete types actually ship — Email, UUID, Money, etc.), much of the value is deferred to internal implementation work.

Technical risk

• Maintenance risk (high): 9 stars, 0 dependents, single-maintainer "Runn Me!" ecosystem. Effectively unmaintained by market signals; assume you will own the code.
• Runtime compatibility (high): PHP 7.x-era library; verify PHP 8.2/8.3 support, strict_types, return types, readonly/deprecation behavior, and PHPUnit/PHPStan/Psalm parity. A failure here is a hard stop.
• License (medium): LGPL-3.0 in a Composer context is generally treated as dynamic linking, but enterprise legal policies frequently blanket-ban GPL/LGPL. Needs explicit legal sign-off before code is merged, not after.
• API stability (medium): No semantic-versioning guarantees documented; a pre-1.0 or loosely versioned base library can change method signatures in patch releases.
• Opportunity signal (6.17) vs. adoption (0 dependents): the abstract opportunity is real (Laravel lacks first-class immutable VOs), but this specific package captures almost none of it.

Key questions

1. Does it install and pass tests on PHP 8.2/8.3 and the Laravel version(s) on our support matrix?
2. What is the test coverage, and does it pass PHPStan/Psalm at a level we'd accept in CI?
3. Which concrete value objects ship versus which we must build?
4. Is equality/hashing implemented correctly for floats, money, and collections-of-VOs (precision, ordering, nested equality)?
5. Does LGPL-3.0 clear our legal policy for a distributed or SaaS product?
6. Is the maintainer responsive, and is there a credible fork path? Who internally would own it?
7. Does it conflict with or duplicate other RunnMe packages we might pull in transitively?
8. How does it behave under serialization (queue payloads, cache, session) — is it round-trip safe?

Integration Approach

Stack fit

• Composer/PSR-4 library, PHP 7.4+ (verify 8.x), no Laravel coupling. Fits cleanly behind Laravel: domain layer holds VOs, infrastructure layer holds Eloquent models and casts. Avoid letting VOs bleed into controllers, Blade, or migrations.
• Best-fit contexts: money/currency, identifiers (UUID, external refs), email/phone, date ranges, quantities with units — anywhere primitive obsession is currently causing validation drift or formatting bugs.

Migration path

• Incremental and bounded-context scoped. Do not attempt a repository-wide DDD retrofit; that is a multi-quarter program, not a package adoption.
• Sequence: (1) timeboxed spike on one VO in one module; (2) build the cast + validation rule + JSON resource trio as reusable internal infrastructure; (3) apply to one bounded context behind existing DB columns (VOs serialize to the same scalars, so no schema migration required); (4) expand only where the trio demonstrably removes bugs.
• Keep the exit ramp open: define an internal interface/abstract wrapper around the package's base classes so a swap (or fork) is a one-file change.

Compatibility

• Verify constraint intersections with the installed Laravel/Symfony/PHPUnit versions before committing; a Composer conflict discovered late invalidates the whole plan.
• Existing columns remain the source of truth — VOs hydrate from and dehydrate to the same scalars, so this is additive and rollback-safe.
• Watch for double-casting (Eloquent $casts + accessors) and for VOs leaking into toArray()/queue payloads.

Sequencing

1. Legal/license review (gate).
2. Compatibility spike: PHP 8.x + target Laravel, CI green, static analysis baseline.
3. Internal integration kit: cast base class, validation rule base class, JSON serialization contract, test helpers.
4. Pilot in one bounded context with measurable acceptance criteria (e.g., reduction in invalid-state bugs, validation rule duplication removed).
5. Decision gate: expand, fork internally, or abandon and hand-roll ~200 lines of VO base classes.

Operational Impact

Maintenance

• Assume full ownership. With 9 stars and 0 dependents there is no upstream community to absorb fixes; security patches and PHP-version bumps land on your team. Budget for an internal fork or vendored copy within the first year.
• Ongoing cost is small but non-zero: keeping the integration kit current with Laravel major releases (custom cast API changes), plus periodic review of the fork.

Support

• No commercial support, no documentation site of note, no Discord/Slack. Onboarding documentation must be written internally — expect a short internal README covering the cast/validation/serialization trio to be the highest-leverage artifact.
• Failure diagnosis falls entirely to the adopting team; stack traces will land in unfamiliar library internals.

Scaling

• Runtime cost is negligible: VOs are lightweight immutable objects; the only measurable overhead is construction/equality on hot paths (e.g., hydrating large collections). Benchmark only if hydrating thousands of rows with casts.
• Architectural scaling is the real concern: value objects scale well when confined to a domain boundary and poorly when they leak into views, API contracts, and queue payloads. Enforce the boundary with static analysis or code review, not convention.

Failure modes

• Composer resolution break on a PHP or Laravel upgrade → blocked deploy; mitigated by the internal fork.
• Breaking change in a minor release → silent behavioral drift in equality/serialization; mitigated by pinning exact versions and a lockfile policy.
• Eloquent hydration failure or null/empty-value handling mismatch (empty string vs. null) → runtime exceptions on legacy data; mitigated by a compatibility test against production-shaped fixtures.
• JSON contract drift if VO jsonSerialize() output differs from prior scalar output → breaks API consumers; mitigated by contract tests on responses.
• License exposure discovered post-release → costly remediation; mitigated by the gate in step 1.
• Contributor abandonment of the fork after the original author disappears → single point of failure; mitigate with two named owners.

Ramp-up

• Engineers unfamiliar with DDD will need a short primer on immutability, equality-by-value, and where VOs belong. Expect a 1–2 day learning curve plus review friction for the first few PRs.
• The integration kit lowers ramp-up substantially — teammates use internal casts and rules rather than the package API directly, which also insulates them from upstream churn.
• Recommend pairing the pilot with a written internal convention doc and one exemplar module before broad adoption.