Value Objects Bundle Laravel Package

Technical Evaluation

Architecture fit. plusforta/value-objects-bundle is a leaf-type library: immutable, self-validating value objects for strings, numbers, booleans, collections, and equality/comparison helpers, plus Symfony/PHP framework configuration. For a TPM this matters because the blast radius is small — value objects hold no I/O, no state, and no framework coupling beyond the cast/serialization layer, so the dependency is easy to reason about, easy to wrap, and easy to remove. The real question is not architectural fit but domain vocabulary fit: adopting this bundle means adopting someone else's decisions about what a valid IBAN, a money amount, or a normalized string looks like. That is a product decision as much as an engineering one.

Integration feasibility. Mechanically low-cost — Composer install, provider registration, config publish, casts on Eloquent attributes. The integration surface is narrow (casts, validation, serialization), so a spike is measured in hours to a week, not sprints. The limiting factor is confidence, not effort: zero stars, zero dependents, GitLab-hosted, no public issue history, no community-authored usage examples, and no visible changelog discipline. Feasibility is high; assurance is low until the source and tests are read.

Technical risk.

• Supply-chain / abandonment. Zero dependents means zero external pressure to maintain. This reads as an internal package published publicly for CI convenience rather than a supported OSS product. Treat it as code to vendor, not a dependency to consume.
• Bus factor. Likely one or two authors at Plusforta, with an internal roadmap we cannot see or influence.
• Semantic lock-in. Validation policy is embedded (regex vs. filter_var for email, libphonenumber-backed phones or not, DE/EU conventions for IBAN/BIC/VAT). Divergence from our policy forces forks or local overrides.
• Compatibility drift. Unknown Laravel support matrix and PHP 8.x pinning; an unmaintained release can freeze us onto an older illuminate/support.
• Immutability guarantees. Worth verifying whether readonly/private constructors are enforced or merely conventional — PHP value objects frequently leak mutable internals (arrays, DateTime).
• Financial correctness. For money specifically, do not let this bundle be the only thing between us and a rounding bug; moneyphp/money + brick/money carry years of edge-case coverage.

Key questions.

1. What is the API surface — base abstractions only, or an opinionated type catalog? (Foundation vs. vocabulary.)
2. Hard Laravel dependency, or framework-agnostic with an optional bridge? Determines reuse in non-Laravel workers/services.
3. Release cadence, Laravel LTS tracking, semantic versioning, changelog presence?
4. Are exceptions part of the public contract, and do they couple our error handling to the package?
5. Is there test coverage, and is the CI pipeline readable?
6. License — does it permit proprietary use and internal redistribution?
7. Does the package own persistence/serialization format, and therefore migration cost on exit?
8. Which primitives are DACH/EU-specific, and does that constrain a multi-currency or multi-jurisdiction roadmap?

Integration Approach

Stack fit. Presumed Laravel 9/10/11, PHP 8.1+, Composer, Eloquent, with Symfony-style configuration. It introduces no new runtime — no extension, no daemon, no service — so it sits in the cheapest integration category. That is precisely why governance and domain risk, not engineering risk, should drive the decision. Confirm fit first: composer why-not plusforta/value-objects-bundle in a scratch project mirroring our composer.json, watching illuminate/support, illuminate/database, and the php constraint. A single-minor Laravel pin means point-in-time adoption and self-owned patches.

Migration path. Recommend the strangler/pilot, not big-bang:

• Big-bang — swap primitives repo-wide. High churn, hard to evaluate in isolation, hard to reverse. Not recommended given the confidence gap.
• Strangler / pilot — adopt in one bounded context (billing or onboarding), behind our own thin interface. Define App\Domain\ValueObjects\* as subclasses or delegating wrappers so application code depends on our namespace. Small ceremony, one-file-per-type exit ramp.

For persistence, cast at the model boundary while keeping raw column representations (string/int) unchanged, so schema and JSON contracts are not coupled to the package's serialization choices.

Compatibility. Verify against our actual matrix before committing: PHP range, Laravel version support, illuminate/* constraints, and whether the bundle's Symfony configuration conflicts with existing service providers. Record the verified matrix in the ADR so future upgrades have a baseline.

Sequencing.

1. Read the source (1–2 hours). Enumerate public classes, confirm immutability enforcement, read tests, confirm license and support matrix. This likely resolves most open questions.
2. Decide build/buy/fork. Given zero adoption signals, the realistic decision is vendor and own versus write the ~300 lines we actually need. Pick per-primitive: use the bundle for structure, replace money with moneyphp/money.
3. Pilot in one bounded context on a feature branch; measure ergonomics and lines-of-validation deleted versus added.
4. Wrap behind a local namespace and add contract tests asserting the validation, equality, and serialization behavior we depend on, so an upstream change or abandonment is a local fix.
5. Pin via ADR with a named owner, an upgrade trigger (e.g., Laravel major), and a sunset criterion.
6. Roll out context by context, only where the primitives map cleanly to existing domain concepts — not into aggregates that already express them differently.

Operational Impact

Maintenance. Vendored, this is our code: we own bug fixes, PHP/Laravel upgrades, and security patches. Budget a modest, recurring line item — realistically a few days per year plus upgrade-window work at each Laravel major. Un-vendored, maintenance is outside our control, which is unacceptable for types sitting in money and identity paths. Assign a named owner and record it in the ADR; unowned shared primitives decay into N divergent forks.

Support. No vendor support, no SLA, no public issue history to gauge responsiveness. Internal support means internal documentation: which types we adopted, which we deliberately excluded, and how to add a new one. Expect onboarding friction to be low for consumers (types are self-documenting, validation errors are explicit) and moderate for contributors (they must understand the immutability and equality contracts before extending).

Scaling. Runtime cost is negligible — these are plain PHP objects, and the casts add microseconds. The scaling concern is organizational: a shared value-object vocabulary is a shared kernel, and shared kernels need governance. Without a lightweight change process, one squad's stricter email validation becomes another squad's production incident. Define who may add types and how breaking changes to validation policy are communicated.

Failure modes.

• Abandonment — mitigated by vendoring and local namespaces.
• Silent validation drift — upstream tightens or loosens a rule on upgrade; mitigated by contract tests around every primitive we rely on.
• Immutability leaks — mutable internals (arrays, DateTime) escaping an ostensibly immutable object; test for it explicitly.
• Serialization coupling — changing the package changes DB columns or API payloads; avoided by keeping raw column representations and casting at the boundary.
• Money correctness — a rounding or allocation bug reaching production; mitigated by delegating monetary arithmetic to moneyphp/money and property-testing against known vectors.
• Orphaned fork — the internal copy diverges with no upstream and no owner; mitigated by ownership assignment and a recorded upgrade trigger.

Ramp-up. Engineers need roughly a day to be productive with the base abstractions (construction, validation, equality, casting) and a week to be confident extending them or debugging serialization. TPM-facing ramp-up is the ADR plus a short "which primitive for which field" table so product and engineering converge on the same vocabulary — that table, more than the code, is what keeps squads consistent. Success criteria for the pilot: the same recurring defect classes from the last 6–12 months of the bug taxonomy become unrepresentable, and net validation code decreases. The rollback costs nothing more than deleting the fork.