Optional Laravel Package

Product Decisions This Supports

• API and contract design. Choosing whether a method's "nothing here" case is modeled as null, a sentinel, an exception, or an explicit Optional<T> remains a product-level decision about how loudly the system forces callers to handle absence. This package is still the "force it" option, but v4.0.0-rc1 changes the cost/benefit calculus.
• Build vs. buy for a null-safety convention — now weighted toward fork/reference. The core concept remains small, but the v4.0.0-rc1 release removes the TypedOptional helper and removes Optional::toNullable. Those removals eliminate much of the "buy" justification cited previously (typed-trait helpers and convenience interop). Treat this package as adopt-as-reference or fork first; dependency adoption is now harder to defend unless you specifically want Java-parity semantics and are prepared to absorb major-version churn.
• Breaking-change and upgrade management. v4 is a major release with removed methods and behavioral changes (equals, flatMap, map, filter, ifPresent, getters). If already on v3, this is a roadmap item: pin v3, test v4 in a branch, and budget migration work. Do not start new work on v4.0.0-rc1 without an explicit pre-release policy.
• Feature scoping: "find" semantics. Still useful for lookup-shaped features — repository/DAO find* methods, cache reads, optional configuration, plugin/hook resolution — where a miss is normal and null invites silent null-propagation.
• Incident reduction roadmap item. Adopting an explicit-absence convention remains defensible against "reduce type-related incidents," but scope it to boundary layers and account for v4's semantic changes before claiming risk reduction.
• SDK/public-package ergonomics. If you publish a PHP client for Java/Kotlin/Scala-background consumers, Optional remains a recognizable contract. The v4 template covariance change improves subtyping ergonomics but may require static-analysis updates.
• Decisions this does not support. It is not a Result/Either type — do not use it for failure, validation errors, or reasons. It is not a substitute for typed properties, DTO validation, or non-nullable domain invariants. The removal of toNullable means you must choose a deliberate boundary-unwrapping convention rather than relying on a convenience method.

When to Consider This Package

Consider adoption when all of the following hold:

• Static analysis is already enforced (PHPStan/Psalm at a meaningful level, with generics declared via @var Optional<Foo> docblocks). Without this, the wrapper degrades into untyped ceremony.
• Absence is semantically meaningful at the boundary — a miss you expect, log, and branch on — not merely an uninitialized value.
• The team shares the idiom (Java/functional background, or an existing internal Optional-like helper you are consolidating).
• License is cleared. LGPL-3.0 is weak copyleft; legal sign-off is still required, and many enterprise policies block LGPL outright.
• Blast radius is small and reversible. Pilot in one module behind an interface; confirm you can vendor or fork the ~single-file core if upstream stalls.
• You have a pre-release strategy. v4.0.0-rc1 is a release candidate with breaking changes. Prefer waiting for a stable v4.0.0, pinning v3, or forking before adopting v4 in production.
• You have verified v4 interop. Optional::toNullable and TypedOptional are removed. Confirm your boundary conversion and type-helper needs are covered by remaining APIs (orElse, get, etc.) or by internal wrappers.

Look elsewhere when:

• You are on PHP 8+ and ?Type return types, ??, and ?-> already express the contract. For most codebases the language feature is cheaper and more idiomatic.
• You need to carry a reason for absence — that is a Result/Either or a small value object, not Optional.
• You are in a hot path. Every Optional::of() allocates; in tight loops and serialization layers this is measurable overhead for zero correctness gain.
• Governance blocks it. Zero public dependents, single maintainer, no security policy or LTS signal. If your org requires vendor accountability, maintenance guarantees, or CVE response, this is a fail.
• The codebase is already consistent without it. A second convention for "maybe a value" is worse than one imperfect convention used everywhere.
• You depend on the removed v4 APIs. If TypedOptional or toNullable was central to your design, stay on v3 with a fork plan or choose a different abstraction. Do not adopt v4.0.0-rc1 expecting those helpers to return.
• You require stable releases. v4.0.0-rc1 is explicitly a release candidate; if your release policy forbids RCs, wait or vendor.

How to Pitch It (Stakeholders)

For executives (one paragraph): This remains a small, low-cost coding convention that makes "this value might be missing" impossible to ignore, reducing a recurring class of production bugs. However, the new v4.0.0-rc1 is a major breaking release: it removes the TypedOptional helper and the toNullable method, changes template variance, and adjusts core semantics (equals, flatMap, map, filter, ifPresent, getters). That weakens the case for taking it as a dependency and strengthens the case for forking or staying on v3 until v4 stabilizes. Licensing risk is unchanged: LGPL-3.0 needs legal clearance before commercial distribution. Recommendation: do not adopt v4.0.0-rc1 org-wide; approve a scoped pilot on v3 or a vendored/forked core, and budget a day for legal review plus a migration spike for v4.

For engineering leads: v4.0.0-rc1 buys Java-parity semantics and covariance, but it removes TypedOptional and toNullable, which were previously part of the "buy" justification. If you already use those, v4 is a regression unless you add internal helpers. The equals/flatMap/map/filter/ifPresent alignment is good for correctness but requires test coverage before upgrading. Keep Optional constrained to repository/SDK boundaries, keep domain internals on native nullable types, and never use it for errors. Given the ~single-file core and the RC status, plan to vendor or fork so an upstream stall or another major release is a non-event.

Ask: a two-week, one-module pilot with a written rule for where Optional is allowed, a static-analysis gate, legal sign-off on LGPL-3.0, and an explicit upgrade decision: pin v3 now, test v4.0.0-rc1 in a branch, and pre-agree to fork the core internally if v4 stabilization or the removed helpers become blockers.