Functional Laravel Package

Product Decisions This Supports

• Build vs. buy for domain-layer plumbing. A Result/Either type is ~100 lines to write in-house; a type-safe generic collection with working PHPStan/Psalm annotations is not. The package bundles both, so the buy decision should be split: buy the collection and monad vocabulary, build nothing, but budget a half-day to verify static-analysis behaviour against your own PHPStan level before committing.
• Scoping an "FP island" rather than an app-wide architecture mandate. This is the highest-leverage decision the package enables. Use it inside a bounded context (pricing, payments, third-party integrations, import/export pipelines) where transformations are dense and error-as-value is genuinely better than exceptions. Deciding where not to use it is as important as adopting it.
• Whether to fund a correctness/tech-debt sprint. Explicit Result and Option types convert implicit failure modes (null returns, swallowed exceptions, mixed collections) into compile-time-visible contracts. That gives you a defensible roadmap item measured in defect rate and static-analysis findings, not in "code cleanliness."
• Dependency and vendor-risk policy. At ~200 GitHub stars, MIT-licensed, with a March 2025 release, this is a tactics-grade dependency, not a platform bet. The decision it drives is your policy threshold for small-maintainer packages: fine for an internal library of ~50 classes, not fine as a load-bearing assumption in a product you'll support for five years without a fork plan.
• Hiring and team-capability decisions. Monads have a real onboarding tax. Adopting this signals (and requires) an FP-literate team or an explicit investment in mentoring — a signal worth surfacing before you commit headcount plans to a functional architecture.
• Feature gating via typed errors. Result/Option makes it cheap to model partial-success and multi-failure flows (batch imports, webhook processing), which often unlocks product features that were previously deferred as "too messy to handle errors for."

When to Consider This Package

Consider adoption when:

• You have a distinct domain layer (DDD, hexagonal, or at least service classes outside Eloquent) where you can apply it without fighting the framework.
• Your codebase runs PHPStan or Psalm at a meaningful level and you're already feeling the pain of mixed from Laravel's untyped Collection. Type-safe generics are the single strongest justification here.
• You handle integrations where failure is expected and routable — payment declines, third-party API errors, validation of external payloads — rather than exceptional.
• You have an FP-leaning engineer or two who will own the pattern and review for drift, and a team small enough that the convention propagates.
• The scope can stay bounded: an internal package, a module, or one service.

Look elsewhere (or build a 150-line Result instead) when:

• The application is conventional CRUD on Laravel. Eloquent's ModelNotFoundException, the validation exception flow, and Laravel's central exception handler are the idiomatic, well-documented error path; wrapping them in Result creates impedance mismatch at every boundary and buys little.
• Your team has no static-analysis discipline. Without PHPStan/Psalm, the generics and monad types degrade into runtime ceremony with no compile-time payoff.
• You need vendor support, a large hiring pool familiarity, or a community large enough to guarantee a fix within weeks. 203 stars does not provide that; accept the fork-and-maintain cost explicitly or decline.
• You're already deep into Illuminate\Support\Collection / LazyCollection and the mental-model overlap would cause confusion rather than clarity.
• You're on an older PHP version — verify the minimum requirement before designing around it, since the ergonomics depend heavily on PHP 8 features (enums, readonly, union types, first-class callables).
• The decision rests on "we should be more functional." That is not a business case; defer until a concrete failure mode points here.

Adjacent alternatives worth benchmarking before deciding: native PHP 8 nullsafe/union types plus enums for simple cases, Laravel's Pipeline for composition, and a hand-rolled Result for the narrow error-handling use case.

How to Pitch It (Stakeholders)

To executives — one paragraph: This is a small, MIT-licensed PHP library that makes failure and absence explicit in code rather than implicit. We are evaluating it for a limited, high-value area — [payments / integrations / data import] — not as a platform-wide rewrite. It carries no licence cost and no vendor lock-in; the realistic downside is engineering time, capped at [X days] for a spike plus [Y days] if we adopt. The upside is a measurable reduction in the class of bugs that come from unhandled nulls and swallowed exceptions, plus stronger automated checking of our code. Recommendation: fund a timeboxed spike in one bounded context, with a go/no-go decision at the end.

To engineering — the substance: The differentiated value is not the monads, it's the generic collections with proper static-analysis annotations, which close a real gap in Laravel's Collection. Result/Option give us explicit error paths in domain code where exceptions are the wrong tool. The costs are honest: a learning curve, a boundary layer where we convert framework exceptions into Result and back, and the fact that this is a ~200-star package — mitigated by MIT licensing and a small surface area we could fork. Ask engineering to answer three questions in the spike: does it hold up at our PHPStan level, what does the Eloquent/HTTP boundary conversion actually look like, and will a non-FP-enthusiast on the team be productive in it after a week.

To the team — the framing: We are trying this in one place, with a named owner, and we will stop if it doesn't pay for itself. Nobody is being asked to rewrite working code.