Phpstan Frankenphp Laravel Package

Product Decisions This Supports

• Roadmap: PHP runtime modernization. This package directly supports the decision of whether and how to move from PHP-FPM to FrankenPHP. Its leveled rule sets map to a phased migration path (FPM → FrankenPHP classic → worker mode), which lets you sequence the work as incremental roadmap milestones rather than a single risky cutover.
• Build vs. buy for migration guardrails. The alternative is writing and maintaining custom PHPStan rules in-house to catch FPM-specific assumptions. Since this is MIT-licensed and narrowly scoped, "buy" (adopt) is cheap to trial and cheap to reverse — a low-commitment way to avoid a bespoke static-analysis investment.
• Feature-level risk assessment. The rules surface code that assumes per-request lifecycle semantics — superglobals, request-scoped state, static/global mutation, and long-running-process hazards — which is exactly the class of defect that makes worker mode unsafe. That gives you a concrete readiness signal per service or module.
• Use cases it enables: CI gates for worker-mode readiness, a migration checklist encoded as executable rules rather than a wiki, scoping which services are "classic-ready" vs. "worker-ready," and estimating remediation effort by counting violations per level.
• Release/quality gating. Because rules are split by level with demos for every case, you can adopt the lowest level as a non-blocking report and ratchet to blocking as violations reach zero — a progressive-delivery pattern PMs can schedule and communicate.

When to Consider This Package

Adopt when most of the following hold:

• Your stack is Laravel/PHP and you are actively evaluating or executing a FrankenPHP migration, or you have FrankenPHP classic in production and are weighing worker mode.
• PHPStan is already in CI. The package is a rule set, not a runtime tool; without PHPStan the integration cost dominates the benefit.
• You need incremental, per-level enforcement across many services or a large legacy codebase, and want a shared, objective definition of "migration-ready."
• You want a low-risk trial: static analysis rules do not touch runtime behavior, so a pilot can be time-boxed and dropped with no production exposure.
• You can accept early-stage OSS: 0 stars, 0 dependents, and a single maintainer imply limited community validation. Pin the version, review the rules, and treat it as a starting point you may need to fork.

Look elsewhere or defer when:

• FrankenPHP is not on the roadmap, or the decision is already made and the migration is complete — the rules then add CI time with little new information.
• The team does not use PHPStan, or uses a different static-analysis stack (e.g., Psalm) where porting the rules is real work.
• You need runtime validation, load testing, or worker-lifecycle diagnostics — this package cannot substitute for those.
• You require vendor SLAs or broad community support; a zero-adoption dependency in a release gate needs an internal owner willing to maintain or fork it.
• The codebase is small enough that a manual audit is cheaper than integrating and tuning rules.

How to Pitch It (Stakeholders)

To executives: FrankenPHP is a credible path to better PHP performance and simpler deployment, but the migration's real risk is not the runtime — it is latent assumptions in our code about how long a process lives. This package turns that risk into a measurable, staged checklist enforced automatically in CI, so we can migrate service by service with evidence instead of optimism. It is MIT-licensed, free, and static-only: it cannot affect production behavior, and we can pilot it and walk away at near-zero cost. The trade-off is maturity — it is an early-stage project, so we should treat it as an accelerator we own internally rather than a supported vendor product.

To engineering: This is a leveled set of PHPStan rules purpose-built for the FPM → FrankenPHP classic → worker-mode path, with demo cases for each rule. It plugs into the PHPStan setup we already run, lets us start in report-only mode and ratchet up to blocking, and gives us a shared, objective definition of "worker-safe." Expect to review the rules and possibly fork given the project's low adoption; budget a small spike to validate coverage against our codebase before making it a required gate.