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 for Laravel/PHP projects without altering runtime behavior. This aligns well with modern Laravel ecosystems that prioritize type safety, maintainability, and developer experience (e.g., via phpstan/extension-installer).
• Non-Invasive: Since it leverages PHPStan’s existing infrastructure, it integrates seamlessly with existing CI/CD pipelines (e.g., GitHub Actions, GitLab CI) and IDE tooling (PHPStorm, VSCode with Intelephense).
• Customizability: The wrapper allows granular rule selection (e.g., disabling specific rules like ergebnis.noPhpstanIgnore), which is critical for balancing strictness and practicality in large codebases.

Integration Feasibility

• Composer-Based: Installation is trivial (composer require wyrihaximus/phpstan-rules-wrapper), requiring no manual configuration beyond PHPStan’s baseline setup.
• Dependency Management: The package automatically updates its bundled rulesets (e.g., symplify/phpstan-extensions, phpstan/phpunit), reducing maintenance overhead for the TPM.
• PHP Version Requirement: PHP 8.4+ is enforced (since v12.0.0), which may necessitate upgrading legacy Laravel projects (e.g., LTS versions like 8.x/9.x). This is a blocker for older stacks but aligns with Laravel’s long-term PHP version policy.

Technical Risk

• Rule Conflicts: Some rules (e.g., strict-rules, dead-code-detector) may flag legitimate patterns in Laravel-specific code (e.g., dynamic property access, magic methods). Mitigation: Requires custom rule exclusion in phpstan.neon.
• Performance Overhead: PHPStan itself can be resource-intensive for large codebases. The wrapper adds minimal overhead, but parallel analysis (via phpstan --parallel) should be tested.
• Rule Deprecation: Underlying rulesets (e.g., phpstan/phpstan-deprecation-rules) may change behavior with PHPStan updates. Mitigation: Monitor phpstan/extension-installer for compatibility warnings.

Key Questions

1. Current PHPStan Usage:
   • Is PHPStan already integrated into the project? If not, what’s the baseline static analysis tool (e.g., Psalm, PHPMD)?
   • What’s the current PHP version? If <8.4, how will this be upgraded?
2. Rule Customization Needs:
   • Are there Laravel-specific patterns (e.g., Facades, Service Providers) that need rule exclusions?
   • Should the wrapper’s default ruleset be superseded by project-specific rules?
3. CI/CD Impact:
   • How will PHPStan execution time affect CI pipelines? Are there timeout thresholds?
   • Should results be published as annotations (e.g., GitHub PR comments)?
4. Maintenance:
   • Who will monitor rule updates and handle conflicts?
   • Is there a process for disabling/enabling rules as the codebase evolves?

Integration Approach

Stack Fit

• Laravel Ecosystem:
  • Native Compatibility: Works with Laravel’s dependency injection, testing (PHPUnit), and console tools.
  • Tooling Synergy: Integrates with:
    • phpstan/extension-installer (auto-loads rules).
    • rector/rector (for automated refactoring based on PHPStan findings).
    • pestphp/pest (if using Pest for testing).
• Non-Laravel PHP:
  • Useful for monorepos or shared libraries where Laravel and vanilla PHP coexist.

Migration Path

1. Assessment Phase:
   • Run PHPStan without the wrapper to establish a baseline.
   • Identify false positives in Laravel-specific code (e.g., app() helper, dynamic properties).
2. Incremental Adoption:
   • Start with non-breaking rules (e.g., phpstan-phpunit, strict-rules).
   • Gradually enable stricter rules (e.g., dead-code-detector, type-coverage).
3. Configuration:
   • Extend phpstan.neon to override defaults:

     includes:
         - vendor/wyrihaximus/phpstan-rules-wrapper/rules.neon
     excludeFiles:
         - 'tests/**/*' # Adjust as needed
     

   • Use phpstan analyze --generate-baseline to baseline existing issues.

Compatibility

• Laravel Versions:
  • LTS (10.x/11.x): Fully compatible (PHP 8.1+/8.2+).
  • Legacy (8.x/9.x): Requires PHP 8.4 upgrade or manual rule selection.
• PHPStan Version:
  • The wrapper targets PHPStan 2.x, which is stable but may deprecate rules in future versions.
• IDE Support:
  • Works with PHPStorm’s PHPStan plugin and VSCode’s Intelephense for real-time feedback.

Sequencing

1. Pre-requisites:
   • Upgrade PHP to 8.4+ (if needed).
   • Install phpstan/extension-installer:

     composer require --dev phpstan/extension-installer --dev
     

2. Install Wrapper:

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

3. Configure:
   • Add to phpstan.neon:

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

4. Test:
   • Run locally:

     vendor/bin/phpstan analyze
     

   • Integrate into CI (e.g., GitHub Actions):

     - name: PHPStan
       run: vendor/bin/phpstan analyze --level=max
     

5. Iterate:
   • Tune rules based on false positives.
   • Add custom rules for Laravel-specific patterns.

Operational Impact

Maintenance

• Dependency Updates:
  • The wrapper automatically updates its bundled rulesets via Composer. Risk: Breaking changes in underlying rules (e.g., symplify/phpstan-extensions).
  • Mitigation: Pin versions in composer.json if stability is critical:

    "extra": {
        "phpstan-rules-wrapper": {
            "symplify/phpstan-extensions": "1.20.0"
        }
    }
    

• Rule Maintenance:
  • Disable problematic rules in phpstan.neon:

    disableRules:
        - Rules\StrictRules\ForbiddenTodoCommentRule
    

  • Monitor PHPStan releases for rule deprecations.

Support

• Debugging:
  • Use --error-format=github for CI-friendly output.
  • Leverage phpstan debug to troubleshoot rule loading.
• Community:
  • Rulesets like symplify/phpstan-extensions have active communities; others (e.g., ergebnis/phpstan-rules) may require custom fixes.
• Fallback:
  • If the wrapper causes issues, revert to individual rulesets (e.g., composer require phpstan/phpstan-phpunit).

Scaling

• Performance:
  • Memory/CPU: PHPStan can be resource-heavy for large codebases (>50K LOC). Mitigations:
    • Use --parallel for multi-core analysis.
    • Exclude vendor/, node_modules/, and tests/ from analysis.
  • CI Timeouts: Run in parallel with other jobs or use cached dependencies.
• Team Adoption:
  • Onboarding: Document common false positives (e.g., Laravel’s app()->make()).
  • Gradual Enforcement: Start with --level=5 (basic) before --level=max.

Failure Modes

Ramp-Up

• Developer Training:
  • Workshop: Demo how to **