Monads Laravel Package

Technical Evaluation

Scope of change (v1.3.0). The release adds a PHPStan extension that bans "panicking" monad unwraps — i.e. calls that extract a value from a Left/None by throwing or aborting. This is a tooling and governance change, not an API change. No breaking changes, no new runtime behaviour, no new runtime dependency implied. The material point is that the single largest usage risk identified in the prior assessment — discipline erosion and silent failure swallowing — now has a shipped, first-party enforcement mechanism rather than something we would have had to build ourselves.

Architecture fit. Unchanged. Monads remain a domain-layer utility that sits alongside idiomatic, exception-driven Laravel rather than inside it. What changes is the shape of the fit: the package now ships a quality gate as well as an abstraction, which means it can be made self-policing at the CI boundary. That is a meaningfully better architectural story than "here is an abstraction, please use it carefully." It also strengthens the case for confining it to a bounded context, because the rule only protects code that is actually analysed and that actually uses the package's types.

Integration feasibility. Mechanical integration remains composer require. The new work is small and lives in the build, not the application: registering the extension (likely via phpstan/extension-installer or an explicit includes: entry), confirming the rule fires at our configured PHPStan level, and deciding whether it is an error or a warning in CI. The semantic integration cost — the ADR that says when Either/Option is mandatory and when exceptions remain correct — is not eliminated, but it is now partially executable rather than purely documentary. That converts a convention that erodes under team churn into a check that fails a pull request.

Technical risk (revised). The overall rating moves from high to moderate, with the caveats below. The prior assessment's top risks and their current status:

• Unvalidated in production — unchanged. Still low stars, still no meaningful dependent base. One release does not constitute ecosystem validation.
• Bus-factor of one — partially mitigated. PR #19 is authored by a second individual, the release is tagged with a compare link and changelog hygiene, and the repository identity (gosuperscript/monads-php) is now confirmed against a real tag history (v1.2.0 → v1.3.0). The prior "treat the release date as unconfirmed metadata" caveat is now resolved. A contributor is not a governance model or a security policy, but it is better evidence than a solo commit stream.
• PHP/Laravel compatibility unverified — unchanged for the runtime floor; see the new static-analysis compatibility question below.
• Static-analysis support — materially improved for PHPStan, unaddressed for Psalm. The prior assessment listed this as the single question that determined whether the abstraction delivered value. It is now answered for one of the two mainstream tools.
• New risk: PHPStan API coupling. PHPStan extensions compile against internal APIs that have historically churned across major versions (1.x → 2.x). A PHPStan upgrade on our side can break the guardrail, and a broken guardrail fails open — the rule stops firing and nobody notices. This is now a dependency-versioning concern in the build pipeline, not just a runtime concern.

Key questions (updated).

1. Is the extension shipped inside this package or as a separate companion package, and does it force PHPStan into require rather than require-dev?
2. What PHPStan version range does it support, and is there a stated policy for tracking PHPStan majors?
3. Is the banned-unwrap rule configurable — can we allowlist specific call sites, and does it respect @phpstan-ignore and baseline files? (If it does, the guardrail is advisory; plan accordingly.)
4. Does it cover only throwing unwraps, or also silently-lossy accessors and discarded results? Discarded Either was the most dangerous failure mode in the prior assessment.
5. Is there Psalm support, and are generics annotations present for Either<Foo, Bar> — or does type information still degrade to mixed?
6. Does the extension add measurable CI runtime, and does it interact badly with Larastan?
7. Which monads does the rule cover — all of them, or only Either/Option?
8. License, CLA/DCO, and security disclosure path — still outstanding from the prior audit.

Integration Approach

Stack fit. Neutral-to-positive, upgraded from poor-to-neutral for a new bounded context. The package still has no service provider, facade, or container bindings, and that remains correct — it should not. But it now has a place in a part of our stack we actually control uniformly: the PHPStan job in CI. That is a genuinely better integration surface than the application layer, because it is identical for every service and does not depend on developer discipline.

Migration path. Unchanged: greenfield, one bounded context, prove ergonomics over a quarter. The release does not make retrofit any more attractive — retrofitting monads is still a whole-codebase conversion with no incremental payoff, and a lint rule makes retrofitting harder, not easier, because it will flag existing panicking unwraps the moment it is enabled.

Compatibility. Verify before committing:

• PHPStan version alignment. Pin explicitly and add a CI assertion that the rule is actually active (a trivial "known-bad" fixture that must fail). Without that canary, a PHPStan bump silently disables the guardrail.
• Larastan coexistence. Confirm the extension and Larastan's own rules coexist without conflicting or masking each other.
• Psalm gap. If any team standardises on Psalm, this release delivers nothing for them; budget a custom rule or accept the gap.
• PHP floor versus our runtime matrix, unchanged from the prior assessment.
• Serialization of monad wrappers across queue and cache boundaries, unchanged and still required.
• Pipeline semantics — do not mix Laravel's Pipeline with monadic short-circuiting in one chain, unchanged.

Sequencing. The prior plan holds with two adjustments:

1. Spike (1–2 weeks) — now explicitly includes wiring the PHPStan extension and, critically, deliberately writing a panicking unwrap and confirming CI rejects it. A guardrail you have not seen fail is not a guardrail.
2. Provenance audit — now partly satisfiable from the tag history and PR record; complete the licence, security-policy, and support-window items.
3. ADR — unchanged in importance, but shorter, because the rule now carries part of the convention.
4. Contained pilot — ship one non-critical internal feature with the rule enforced at error level.
5. Decision point — promote, or fork. Note the fork calculus has shifted: forking now means owning a PHPStan rule as well as the monad classes, which raises the cost of the vendor-it-yourself path enough that the dependency is now more likely to earn its place if the maintainer stays responsive.

Operational Impact

Maintenance. Runtime maintenance remains effectively zero. The convention-drift burden — previously described as the real ongoing cost, requiring us to author and maintain a custom PHPStan rule — is now substantially offloaded to the package. What replaces it is a smaller, sharper obligation: keep the guardrail working across PHPStan upgrades. That means a pinned version, a canary fixture, and a line in the dependency-upgrade runbook. This is a strictly better maintenance profile than before: a bounded, testable build concern in place of an unbounded, social one.

Support. Marginally improved but still the primary risk. There is now evidence of a second contributor and a real release cadence, which is more than most single-maintainer packages offer. There is still no Stack Overflow corpus, no tutorials, and no peer users to consult; onboarding material remains in-house work. Containment to one bounded context remains the load-bearing operational control, and should be stated as a hard architectural constraint rather than a preference.

Scaling. Runtime cost still negligible. The cognitive scaling concern is partially mitigated: a reviewer who does not know monad idioms can still trust that CI blocks the dangerous patterns, and a junior engineer gets feedback at commit time rather than in review. The comprehension tax on readers remains — the rule prevents misuse, not unfamiliarity — so gating adoption on team tenure and PHP sophistication is still correct.

Failure modes (updated).

• Silent failure swallowing — downgraded from critical to managed. Now blocked at CI for panicking unwraps. Residual exposure: ignored results, baseline files, and @phpstan-ignore comments. Treat the rule as a strong default, not a proof.
• Guardrail failure-open — new. A PHPStan upgrade, a misconfigured includes:, or a forgotten canary silently disables enforcement. This is the failure mode to instrument; it fails quietly and everyone believes they are protected.
• Boundary leakage — unchanged; monads escaping into HTTP responses, Blade, or queue payloads.
• Abandonware — unchanged, still mitigated only by containment.
• Type erosion — improved for PHPStan, unchanged for Psalm.
• Convention split — unchanged; two error-handling idioms can still coexist.

Ramp-up. Roughly 2–4 weeks to productivity for a mid-level engineer new to functional patterns, unchanged in magnitude, though the shipped rule shortens the feedback loop considerably — learners get corrected by tooling instead of by reviewers, which compresses the tail of the learning curve. Senior engineers with Scala/Kotlin/Rust exposure still take days. Keep the half-day workshop and living cookbook. Remember the cost is paid by readers as well as writers.

Recommendation for the TPM. The prior recommendation holds with a firmer footing and a slightly better risk profile. Do not adopt as a platform standard. Run the two-week spike — with the PHPStan guardrail wired and proven to fail — and complete the provenance audit in parallel. A positive pilot licenses use in one bounded context only, with the rule enforced at error level and a canary test protecting it from toolchain drift. This release materially reduces the strongest objection to the package (unpoliced usage) and provides the first real evidence of a functioning project rather than a personal repository. It does not change the core judgement: with a small dependent base and a single maintainer, this remains a bet on an unproven library. Keep the commitment reversible, contained, and cheap to unwind — and add "re-verify the guardrail fires" to the quarterly dependency review.