Phprimitives Laravel Package

Getting Started

• Install with composer require n-fasano/phprimitives.
• Start with the package README, then inspect src/ and tests/ for the exact primitive classes, construction methods, and exception behavior. The release note specifically touches InvalidBackingValue, so check that exception and where it is thrown first.
• First practical Laravel use case: wrap one request-derived value in a FormRequest or DTO before passing it into an action/service. For example, take a validated string/integer input, construct the package primitive at the boundary, and let the action depend on that typed value instead of a raw scalar.
• Catch InvalidBackingValue at the boundary when constructing from untrusted input, and translate it into a Laravel ValidationException if the failure should appear as a form validation error.

Implementation Patterns

• Use primitives at application boundaries: FormRequests, DTOs, console commands, and service/action inputs. Keep controllers thin by converting request data into primitives before calling domain code.
• Pair Laravel validation with primitive construction. Use Laravel rules for user-facing validation messages, then construct the primitive as a domain invariant check. Do not rely on exception messages for user-facing output.
• In Eloquent, prefer custom casts or accessors/mutators that convert between the database scalar and the primitive. Keep the database representation simple and the primitive usage inside application/domain layers.
• In API resources and Blade views, convert primitives back to scalars explicitly. Avoid leaking package objects into JSON unless the package clearly supports serialization for that type.
• In tests, assert on the exception class and the invalid input rather than exact exception text. This is especially important after v1.0.2, which changed the InvalidBackingValue message.
• Centralize exception translation in one place, such as a FormRequest helper or exception handler mapping, so package-specific exceptions do not spread across controllers.

Gotchas and Tips

• v1.0.2 only removes the FQCN from InvalidBackingValue’s message. Treat this as a patch-level message cleanup, but update any tests, log assertions, or snapshots that matched the old text.
• Catch InvalidBackingValue by type, not by message. Message text is not a stable contract.
• Be careful with nullable/optional fields. Decide whether null is a valid primitive state or whether absence should bypass primitive construction entirely.
• Do not wrap every scalar indiscriminately. Use primitives where they add domain meaning or invariants; otherwise they become extra ceremony.
• Check PHP and Laravel version constraints in composer.json before adopting the package in an existing app.
• If you need package-specific error messages, wrap construction in your own factory or validation adapter rather than depending on the package exception message.
• Extension point to watch: custom casts, DTO factories, and FormRequest conversion helpers are usually the cleanest places to adapt the package to your app’s conventions.