Phpstan Rules Wrapper Laravel Package

Technical Evaluation

Architecture Fit

• Static Analysis Integration: The package is a PHPStan rules wrapper, meaning it extends static analysis capabilities in a Laravel/PHP codebase without modifying runtime behavior. This aligns well with Laravel’s reliance on PHP for core logic and its growing adoption of static analysis tools (e.g., Pest, Laravel Pint).
• Non-Invasive: Since it leverages phpstan/extension-installer, it integrates seamlessly with existing PHPStan configurations, avoiding conflicts with Laravel’s autoloading or service container.
• Rule Customization: The wrapper bundles 10+ PHPStan rule sets (e.g., strict rules, dead code detection, PHPUnit-specific checks), offering a pre-configured but modular approach. Teams can disable/enable rules via PHPStan’s configuration without forking the wrapper.

Integration Feasibility

• Low Friction: Requires only a Composer install (composer require wyrihaximus/phpstan-rules-wrapper) and minimal PHPStan config updates (e.g., adding includes or level directives). No Laravel-specific setup is needed.
• Dependency Management: The wrapper abstracts versioning for 10+ rule sets, reducing Composer dependency sprawl. However, this introduces a single point of failure if the wrapper’s versioning strategy lags behind critical rule updates.
• PHP Version Requirement: PHP 8.4+ is enforced (since v12.0.0), which may require Laravel teams to upgrade if using older versions (e.g., Laravel 10.x supports PHP 8.2+).

Technical Risk

• Rule Conflicts: Some bundled rules (e.g., ergebnis/noPhpstanIgnore) are disabled by default due to known conflicts. Teams must review the disabled rules list to avoid false positives/negatives.
• Performance Overhead: PHPStan’s static analysis adds CPU/memory usage during CI/CD. The wrapper’s bundled rules may increase analysis time, especially for large codebases. Benchmarking is recommended.
• Maintenance Burden: The wrapper is actively maintained (last release: 2026-06-19), but its monolithic dependency model could complicate future customizations (e.g., swapping a rule set).

Key Questions

1. Rule Set Alignment:
   • Do the bundled rules (e.g., symplify/phpstan-extensions, tomasvotruba/type-coverage) align with our team’s coding standards?
   • Are there critical rules missing (e.g., Laravel-specific checks like no-hardcoded-config)?
2. Customization Needs:
   • Will we need to override or disable any bundled rules? If so, how will we manage this long-term?
3. CI/CD Impact:
   • How will this affect our PHPStan execution time in CI? Should we run it in parallel or cache results?
4. Upgrade Path:
   • How will we handle major version bumps of PHPStan or Laravel? Will the wrapper’s versioning strategy (e.g., ^) cause compatibility issues?
5. Tooling Ecosystem:
   • Does this integrate with our existing tools (e.g., GitHub Actions, Laravel Forge, or custom scripts)?

Integration Approach

Stack Fit

• Laravel Compatibility: The package is Laravel-agnostic but works harmoniously with Laravel’s PHP-centric stack. Key integrations:
  • PHPStan: Laravel teams already using PHPStan (via phpstan/extension-installer or phpstan/phpstan) will benefit from the wrapper’s pre-configured rule sets.
  • CI/CD: Works with any PHPStan-compatible pipeline (e.g., GitHub Actions, GitLab CI). Example:

    # GitHub Actions example
    - name: Run PHPStan with wrapper
      run: vendor/bin/phpstan analyse --level=max app/
    

  • IDE Support: Rules will propagate to IDEs (PHPStorm, VSCode) via PHPStan’s native integration.
• Alternatives Considered:
  • Manual Rule Configuration: More flexible but requires maintaining individual rule set versions.
  • Custom PHPStan Extensions: Overkill for most teams; the wrapper provides 80% of use cases out-of-the-box.

Migration Path

1. Assessment Phase:
   • Audit current PHPStan config (phpstan.neon) for conflicts with bundled rules.
   • Run a dry analysis with the wrapper to identify false positives/negatives.
2. Integration:
   • Install the wrapper:

     composer require --dev wyrihaximus/phpstan-rules-wrapper
     

   • Update phpstan.neon to include the wrapper’s rules:

     includes:
         - vendor/wyrihaximus/phpstan-rules-wrapper/rules.neon
     

   • Adjust level or paths as needed.
3. Validation:
   • Test in a staging environment or CI pipeline before full adoption.
   • Verify no false positives (e.g., Laravel’s dynamic properties triggering strict rules).

Compatibility

• PHPStan Version: The wrapper targets PHPStan 2.x, which is stable but may introduce breaking changes. Check PHPStan’s upgrade guide for Laravel-specific quirks.
• Laravel-Specific Rules: The wrapper lacks Laravel-native rules (e.g., for Eloquent, Blade, or service container). Teams may need to supplement with:
  • phpstan/laravel (for Doctrine/Eloquent).
  • Custom rules for framework-specific patterns.
• Tooling Conflicts: Ensure no overlap with other static analysis tools (e.g., Psalm, PHPMD).

Sequencing

1. Phase 1: Pilot in a non-critical module (e.g., a feature branch).
2. Phase 2: Gradually expand to core modules, disabling rules as needed.
3. Phase 3: Integrate into CI/CD gates (e.g., block PRs on failures).
4. Phase 4: Optimize by customizing the wrapper (e.g., forking to remove unused rules).

Operational Impact

Maintenance

• Dependency Updates: The wrapper’s automated dependency updates (via Renovate) reduce manual maintenance but require quarterly reviews to ensure compatibility with:
  • PHPStan major versions.
  • Laravel’s PHP version requirements.
• Rule Customization:
  • Short-term: Override rules in phpstan.neon:

    disableRules:
        - 'Shipmonk\DeadCodeDetector\DeadCodeDetectorRule'
    

  • Long-term: Fork the wrapper if heavy customization is needed (e.g., adding Laravel-specific rules).
• Documentation:
  • Maintain a runbook for:
    • Disabling/enabling rules.
    • Upgrading PHPStan/Laravel.
    • Troubleshooting false positives.

Support

• Troubleshooting:
  • False Positives: Use PHPStan’s --error-format=github for actionable feedback.
  • Performance: Profile with phpstan --memory-limit=1G and adjust CI timeouts.
• Community Resources:
  • Limited direct support (MIT license, no official maintainer contract). Rely on:
    • GitHub Issues (e.g., #212 for rule conflicts).
    • PHPStan’s Slack/Discord.
• Fallback Plan: If the wrapper becomes unmaintained, migrate to individual rule sets (e.g., composer require phpstan/phpstan-strict-rules).

Scaling

• Codebase Growth:
  • PHPStan’s incremental analysis (--generate-baseline) helps scale to large codebases.
  • Consider parallel execution (e.g., split rules by file type).
• Team Adoption:
  • Onboarding: Document rule sets in CONTRIBUTING.md or a wiki.
  • Enforcement: Start with --level=5 (recommended) and adjust based on team feedback.
• CI/CD Scaling:
  • Cache PHPStan results (e.g., GitHub Actions cache or phpstan --cache-results).
  • Run in matrix tests for multi-PHP-version projects.

Failure Modes