Phpstan React Laravel Package

Product Decisions This Supports

• Build vs. buy for correctness tooling in async PHP. The package is a static analysis extension, not a runtime library. It adds ReactPHP-aware rules on top of PHPStan, so the "build" alternative is writing and maintaining custom PHPStan rules in-house. For a team already running PHPStan in CI, buying (adopting) wins on cost: it is a dev-only Composer dependency with no runtime surface, no migration, and reversible in one commit.
• Enforcing an architectural standard rather than documenting it. Version 3.0 encodes ReactPHP conventions as machine-checkable rules: reach the event loop through Loop::… rather than injecting or storing LoopInterface, avoid Loop::get() indirection, and keep loop references out of domain models and promoted properties. This converts a code-review opinion into a CI gate, which is the decision a PM actually needs to fund (reviewer time vs. tooling time).
• Preventing production incidents in long-running processes. The core rule set flags blocking calls (sleep, usleep, time_nanosleep, file_get_contents, fopen, fread, fwrite, gethostbyname, mkdir, file_exists, is_dir, is_file, is_link, fclose) and names the ReactPHP replacement plus documentation link in each error message. For a product whose value proposition depends on responsiveness or concurrency, these are latent outages: one blocking file_get_contents in an event-loop handler stalls every in-flight request.
• De-risking fiber adoption. The react/async rules track which closures are wrapped in async and follow the call graph to catch indirect await reachability. This matters if the roadmap includes moving ReactPHP services toward fiber-style async; the tool surfaces the migration's sharp edges before runtime.
• Incremental rollout as a scoping decision. All rules are on by default but can be tuned under parameters.wyrihaximus.reactphp.rules, so a PM can sequence adoption (blocking-call rules first, event-loop rules second, async rules third) and stage the engineering cost across sprints rather than in one large PR.
• Deciding whether this is in scope at all. Despite the framing, this is not a Laravel package and has no Laravel integration. It is relevant only if the product runs ReactPHP in some form: long-running daemons, websocket or SSE servers, custom queue workers, or ReactPHP-based services adjacent to a Laravel app. If the stack is conventional Laravel request/response plus a standard queue driver, the value is close to zero and the correct decision is to pass.

When to Consider This Package

Adopt when:

• ReactPHP is already in production (any of react/event-loop, react/socket, react/stream, react/filesystem, react/dns, react/promise-timer, react/async) and long-lived processes serve user-facing traffic.
• PHPStan is already a CI gate and phpstan/extension-installer (or an explicit includes: entry) is in use, so marginal integration cost is one dependency plus one config line.
• There have been, or plausibly will be, blocking-call bugs in event-loop code, and the team would rather catch them in review/CI than in an incident.
• An architectural direction has been chosen (static Loop:: access, no injected loops) and you want that direction enforced automatically instead of by convention.
• You want to trial the fiber/async migration with guardrails before committing roadmap capacity to it.

Look elsewhere when:

• There is no ReactPHP in the stack. There is nothing here for a standard Laravel or Symfony application.
• The team does not run PHPStan, or runs it at level 0 to 2 as a formality. The rules presuppose meaningful static analysis discipline; adding them to a nominal setup yields noise without enforcement.
• A different analyzer is the house standard. There is no PHP CS Fixer or Rector equivalent here; replacing a Rector-based custom rule set with this would be a step down in fix automation.
• Maturity risk is unacceptable. This is a single-maintainer package (2 GitHub stars, 0 dependents, 2 contributors across 49 PRs in the 3.0 cycle, with most activity being dependency bumps). Bus factor is 1 and there is no commercial support. Acceptable for a dev-only linter that fails loudly and is removable; not acceptable as a load-bearing runtime dependency. It is not that today. The 3.0.0 release note "Total issues resolved: 0" alongside 49 merged PRs also indicates that the change log reflects maintenance hygiene more than a responsive issue backlog, so do not expect fast upstream turnaround on rule edge cases.
• The release cadence looks odd. Published release dates extend into 2026, which suggests either a forward-dated changelog or metadata that should be verified against Packagist before planning a dependency freeze around a specific version.
• You need rule coverage beyond the documented function list. The scope is deliberately narrow: a fixed set of blocking filesystem, sleep, and DNS functions plus loop/async patterns. It will not catch blocking database drivers, synchronous HTTP clients, or CPU-bound work, which are the larger real-world stalls. Pair it with a performance budget or load test rather than treating it as complete event-loop safety.
• You need Laravel integration, config publishing, or Artisan wiring. None exists, and none should be expected.

How to Pitch It (Stakeholders)

For executives, one paragraph. This is a free, MIT-licensed, dev-only quality gate for the part of our stack that handles many concurrent requests in a single long-running PHP process. It teaches our existing static analysis tool about ReactPHP so that blocking calls (sleep, file_get_contents, fopen and friends) and misplaced event-loop references fail the build instead of surfacing as production stalls. Cost is one dependency and one line of config, it never ships to production, and removing it is a one-commit reversal. It also gives us guardrails for the planned fiber/async work, so that migration is attempted with a safety net rather than blind.

For engineering leadership. Treat it as a review-automation investment, not a library adoption: it moves a recurring code-review conversation (use the async API, do not hold a loop reference, do not await outside an async closure) into PHPStan output with the suggested replacement and a documentation link attached to each violation. Rules are individually toggleable, so we can land blocking-call rules first and sequence the stricter event-loop rules behind team agreement, avoiding a single disruptive cleanup PR.

For engineering, the honest caveats to state up front. This is not a Laravel package; it applies only to our ReactPHP surfaces. It is a single-maintainer project with negligible download counts and no vendor support, so we should pin the version, expect to own any rule we need that upstream does not provide, and be prepared to fork. Coverage is limited to its documented function list: it will not detect blocking database or HTTP clients, so it complements rather than replaces load testing and performance budgets. Proposed pilot: enable on one ReactPHP service, run in non-blocking mode for two sprints to size the violation count, then promote to a CI gate and decide on the event-loop and async rule categories based on real findings.