Core Laravel Package

Product Decisions This Supports

• Tri-state modeling for surfaces where "absent" must be distinguishable from null: partial updates (PATCH/merge semantics), field-level resolution, and API response shaping where NOT_FOUND vs null changes client behavior.
• Negative caching and config resolution: UNKNOWN / UNDEFINED let you cache "we looked and there was nothing" without conflating it with "not yet computed," reducing stale-read and cache-stampede bugs.
• Access-control and redaction flows: HIDDEN provides a first-class value for "present but not visible to this actor," cleaner than overloading null in serializers, audit logs, and permission-aware payloads.
• Roadmap sequencing: v1.6.0 is a low-risk, additive primitive. If partial-update APIs, offline sync, or permission-aware serialization are on the roadmap, this is a cheap enabler shipped now rather than a bespoke internal convention later.
• Build vs. buy: adopting a maintained sentinel vocabulary is cheaper than inventing and documenting one per team, and it standardizes semantics across services. A minor release with no breaking changes lowers adoption cost.

When to Consider This Package

Consider it when:

• At least one flow has genuinely ambiguous null (missing vs. explicit null vs. forbidden vs. not-yet-loaded).
• You are designing partial-update endpoints, sync/merge logic, or permission-aware response serializers.
• You want a shared, documented vocabulary across multiple Laravel services instead of team-specific magic strings.

Look elsewhere or defer when:

• You are on PHP 8.1+ and already standardize on backed enums for this; global constants become a parallel, weaker convention.
• Global constant definitions are a concern in your bootstrap/autoload path (collision risk, no namespacing, weaker static analysis).
• Serialization boundaries (JSON, queues, database) require explicit encoding rules — confirm the package documents how sentinels round-trip before committing.
• The ambiguity is confined to a single module; a local enum or value object may suffice.

How to Pitch It (Stakeholders)

Executives: v1.6.0 is a small, additive release that standardizes a vocabulary for "unknown, invalid, undefined, not found, hidden." It is a low-cost enabler for partial-update APIs and permission-aware responses — areas where ambiguity bugs are expensive and user-visible. No breaking changes, no migration required; adoption can be selective.

Engineering: the release adds five global constants. Treat it as a convention layer, not a framework. Evaluate namespace collisions and static-analysis impact; if the codebase is enum-first, this may duplicate existing patterns. Otherwise it is a pragmatic way to make tri-state semantics explicit at API, cache, and serialization boundaries.