Phpstan React Laravel Package

Getting Started

Install the package as a dev dependency and configure PHPStan to include its rules. Begin by identifying blocking synchronous functions in your ReactPHP codebase that should be replaced with async equivalents. The default configuration highlights functions like file_get_contents, sleep, and fopen — flagging them as violations.

composer require wyrihaximus/phpstan-react --dev

Then in phpstan.neon:

includes:
    - vendor/wyrihaximus/phpstan-react/phpstan-reactphp-rules.neon

Run vendor/bin/phpstan analyse — the output will list offending synchronous calls with suggested ReactPHP replacements.

Implementation Patterns

• Refactor on demand: Let PHPStan errors drive incremental migration. For example, if file_get_contents() is flagged, refactor to use React\Filesystem\Node\FileInterface::getContents(), ensuring the callback/promise-based signature is handled correctly.
• Baseline cautiously: Use phpstan.neon’s ignoreErrors or errorLevel to gradually tighten checks — start at level 1 (errorLevel: 1) to catch only critical blocking calls, then elevate.
• CI enforcement: Add PHPStan to your pipeline to block PRs introducing blocking I/O. A single CI failure提醒 developers to use async patterns from day one.
• Pattern mapping: Leverage the documented replacements (e.g., gethostbyname() → ResolverInterface::resolve() from react/dns) as quick reference cheat-sheets during pair programming or code reviews.

Gotchas and Tips

• No auto-fixes: This package only reports violations — no --fix support. Be prepared to manually refactor, ideally with tests in place first.
• False positives possible: Functions like file_exists() may be unavoidable in initial setup logic (e.g., before spawning reactor), but still flagged. Add them to ignoreRules with comments justifying their use.
• ReactPHP version drift: Ensure your ReactPHP packages match the versions the rule set expects (e.g., react/filesystem v1 vs v2). A mismatch may yield incorrect suggestions or miss cases.
• Dependency on PHP 8.4+: The last release indicates 2025-04-26 — likely a typo — and dependencies suggest strict PHP 8.4+ support. Confirm compatibility before upgrading projects.
• Debug with -c and --debug: Use phpstan analyse -c phpstan.neon --debug to trace why a function was flagged, especially if the NEON config includes other extensions.