Phprimitives Laravel Package

Technical Evaluation

Architecture fit. The package (evidenced by InvalidBackingValue, characteristic of backed value objects / enum-backed scalars) is a framework-agnostic PHP primitives library, not a Laravel extension. It lands in the domain layer rather than infrastructure, which is the right place for it — but it also means it becomes load-bearing across models, DTOs, and validation boundaries. Adopt it deliberately as a domain convention, not as an incidental utility dependency.

Integration feasibility. Standard Composer install; no service provider, config publishing, or facade implied. Integration effort is low and reversible. The real work is convention-setting, not wiring.

Technical risk. v1.0.2 is a patch release with a single change: removal of the FQCN from InvalidBackingValue's message. This is not an API break — the exception class, constructor, and throw sites are unchanged — but it is an observable behavior change at the message-string level:

• Tests asserting exact exception messages will fail; this is the most likely breakage vector.
• Log parsers, alert regexes, or dashboards keyed on the FQCN substring will stop matching.
• The message loses self-describing provenance in multi-package logs; the throwing class must now be captured explicitly (log $e::class, not just $e->getMessage()).
• A message-only change shipped in a patch release signals the maintainer treats exception text as non-contractual. Record that as a standing assumption rather than re-litigating it per release.
• Maturity signal is thin: early-version cadence (1.0.x), small change surface, single-maintainer bus factor.

Key questions.

1. Which of our value objects throw InvalidBackingValue, and do any tests or log queries assert on the message text?
2. What PHP and Laravel version constraints does the package declare, and do they cover our full runtime matrix?
3. Is exception message text covered by the maintainer's semver policy? (Evidence suggests no.)
4. Static analysis baseline — does it ship PHPStan/Psalm types, and does it pass at our level?
5. Security and maintenance posture: composer audit history, issue/PR responsiveness, release recency.

Integration Approach

Stack fit. composer require n-fasano/phprimitives. Treated as a plain library — no framework coupling, so it works identically in HTTP handlers, queue workers, console commands, and tests. It cannot leak HTTP-layer concerns into the domain, which is the main architectural argument for it.

Migration path. Greenfield adoption is trivial. For an existing codebase, introduce incrementally at the edges — request validation into domain construction — rather than a big-bang replacement of existing casts and accessors. Verify before assuming Eloquent integration: the package is not a cast provider, so $casts integration requires a custom cast wrapper on our side.

Compatibility. Pin with caret (^1.0) and commit composer.lock. Confirm the PHP constraint against our runtime matrix and against every Laravel major we support. Run composer audit in CI so upstream advisories surface without manual checking.

Sequencing.

1. Spike in a throwaway branch; validate PHP/Laravel constraints first.
2. Add PHPStan/Psalm to the pilot so misuse is caught at analysis time, not runtime.
3. Adopt in one bounded context (single domain area), not fleet-wide.
4. Codify exception handling up front: map InvalidBackingValue to a domain/validation error in the exception handler and log $e::class explicitly so the FQCN-free message doesn't degrade observability.
5. Expand once the convention is documented and the pilot has run a full release cycle.

Operational Impact

Maintenance. Small surface area, low upgrade cost per release — budget minutes, not days. The overhead is administrative: add to the dependency register, watch releases, and expect frequent small patch bumps given the current cadence.

Support. GitHub issues only; no commercial backing and a single maintainer. Name an internal owner for the value-object convention — upstream will not supply that guidance.

Scaling. No runtime scaling concerns; value objects are in-process and allocation-cheap. The scaling cost is cognitive: onboarding engineers to the primitive set and its exception semantics. Document once, reuse.

Failure modes.

• Silent breakage via exception message text (exactly what v1.0.2 does) — highest-probability, lowest-severity.
• Type coercion faults at hydration boundaries where backing types and DB column types disagree.
• Unhandled InvalidBackingValue on production paths producing 500s instead of 422s if no exception mapping exists.
• Abandonment: mitigated by the package's small scope — a fork is viable, so this is a nuisance rather than a blocker.

Ramp-up. Hours for a PHP-fluent engineer; the constraint is agreeing on the convention, not learning the API.

Release verdict. v1.0.2 does not change adoption guidance — non-breaking, no new capability, no deprecation. Action required is narrow: grep the codebase for assertions or log queries matching InvalidBackingValue message text before bumping.