Monads Laravel Package

Product Decisions This Supports

• Null and error-modeling architecture: Deciding whether to standardize on explicit Option/Maybe and Result/Either types versus idiomatic PHP null + exception flows. This package is a candidate foundation for railway-oriented programming in service and domain layers. The new PHPStan extension (v1.3.0) meaningfully de-risks this decision by making "panicking" unwraps (e.g. unwrap() that throws) a static-analysis violation rather than a code-review convention.
• Functional core vs. procedural shell: Informing a roadmap choice to adopt a functional core inside a Laravel app — using Option/Result at the boundaries (repositories, external API clients, jobs) while keeping Eloquent and controllers idiomatic. Static enforcement lets you define a boundary and mechanically keep the wrong idioms out of it.
• Build vs. buy for a small primitives library: Monads are ~500 lines of well-understood code. The decision is less "buy" and more "adopt vs. write in-house," and this package serves as a low-cost reference implementation to evaluate whether the team wants the pattern at all. A bundled PHPStan extension is real, non-trivial tooling that raises the cost of the in-house alternative — worth factoring into the comparison.
• Error-handling consistency across services: If the org is standardizing on typed error returns (e.g., for API clients, payment flows, async job results), a Result monad becomes the shared vocabulary. The PHPStan rule turns that standard from a style guide into a CI gate — a stronger input to a platform/standards decision.
• Use cases worth validating first: validation pipelines (accumulating errors without exceptions), nullable chained lookups (->map()->getOrElse()), and retry/Either-based job orchestration — each a bounded spike before broader adoption. Add "enforce the boundary with the PHPStan rule" to each spike's acceptance criteria.
• Team capability bet: Signals whether investing in FP fluency (composition, immutability, monad laws) is on the engineering development roadmap. A linter that catches the most common FP-in-PHP mistake lowers the fluency bar for adoption.

When to Consider This Package

Consider it when:

• The team has at least one champion fluent in FP/Elm/Scala/Rust who can own conventions and code review — now supplemented, not replaced, by the PHPStan rule.
• You have complex, high-consequence flows (payments, external integrations, multi-step validation) where explicit Result chains beat exception pyramids.
• You already run PHPStan (or are willing to): v1.3.0's main value is the opt-in static-analysis extension banning panicking unwraps. Teams without static analysis in CI capture much less of this release's benefit.
• You're okay vendoring or forking a tiny library — 6 stars, 0 dependents, and a low adoption score mean you should treat this as source code to audit and own, not a dependency you trust implicitly. A first-party PHPStan extension is a positive signal of maintenance intent, but it's one PR, not ecosystem validation.
• You want a fast, cheap spike to test whether monads improve your codebase before paying the cost of a home-grown abstraction.

Look elsewhere (or write ~200 lines in-house) when:

• The codebase is strongly idiomatic Laravel/Eloquent and developers will fight the abstraction.
• You don't run static analysis; you'd be adopting the library without its best guardrail.
• You need enterprise support, a security-review trail, or SOC2-relevant vendor posture.
• A more established alternative exists for the specific primitive — e.g., phpoption/phpoption (the de-facto Option type used by Symfony/Doctrine ecosystems) is the safer "buy" for null-safety alone.
• You need broad community scrutiny; six stars and zero dependents means no ecosystem pressure-testing.

How to Pitch It (Stakeholders)

To executives: This is a low-cost, low-commitment experiment, not a platform decision. A small monads library could reduce a class of null-handling and error-propagation bugs in our most complex flows. The latest release adds a static-analysis rule that automatically blocks the riskiest misuse pattern, which lowers the execution risk of the trial. The package itself is still early-stage (minimal community, no downstream adopters). Recommendation: fund a 2–3 day spike in one bounded area, measure defect reduction and engineer feedback, and only then make a build/buy/standardize call.

To engineering leadership: The real value is vocabulary and discipline, not the library. Monads give us explicit nullability (Option) and typed, composable failures (Result/Either) — a strong fit for external-API clients, payment orchestration, and validation pipelines. The v1.3.0 PHPStan extension directly addresses our top adoption risk (developers reaching for panicking unwraps under deadline pressure) by moving enforcement from PR review into CI. Remaining risks: team unfamiliarity, abstraction overhead, and the fact that a six-star package must be treated as auditable source we own, not a trusted dependency. Mitigation: vendor or fork it, require the PHPStan rule wherever the library is used, compare against phpoption/phpoption for the Option piece, and establish a one-page convention doc before wider rollout.

To engineering: Treat this as a patterns decision with a library attached. Prototype in one service boundary, keep Laravel-idiomatic code at the edges (controllers/Jobs), and enforce usage via the PHPStan extension plus PR review. Note the extension is opt-in — wiring it up is part of the spike, not an automatic benefit of upgrading. If it earns its keep, we either maintain the fork or graduate to a more established primitive.