Phpstan Extension Ide Helper Laravel Package

Technical Evaluation

Architecture Fit

• Purpose Alignment:

  • Unchanged: Remains a developer tooling aid for PHPStan extension development, generating IDE stubs for PHAR-internal classes/functions.
  • New Focus: Release 2.2.4 aligns with PHPStan 2.2.x, reinforcing its role for teams using PHPStan 2.2+ (e.g., custom rules, custom nodes).
  • Non-Use Case: Still irrelevant for projects not writing PHPStan extensions or relying on PHAR-only workflows.

• Laravel-Specific Fit:

  • Direct Impact: No change. Laravel core/packages rarely write PHPStan extensions, but custom rule development (e.g., for domain-specific validation) remains a niche use case.
  • Indirect Impact: Useful for monorepos or projects with strict static analysis pipelines (e.g., Laravel + PHPStan 2.2+).

Integration Feasibility

• Composer Dependency:

  • Unchanged: Installs as a dev dependency; no runtime impact.
  • Version Pinning: Now explicitly tied to PHPStan 2.2.x (critical for compatibility).
    • Risk: Projects using PHPStan <2.2 or >2.2 will break stub generation.
    • Mitigation: Document strict version alignment in composer.json:

      "require-dev": {
        "phpstan/phpstan": "^2.2",
        "headercat/phpstan-extension-ide-helper": "^2.2"
      }
      

• Build/IDE Integration:

  • Unchanged: Works with PHPStorm/WebStorm (native PHAR stub support) and VSCode (requires Intelephense).
  • New Consideration: PHPStan 2.2.4 may introduce internal API changes requiring stub updates. Test IDE behavior post-update.

Technical Risk

• Stale Stubs (Amplified):

  • Risk: PHPStan 2.2.x may introduce breaking internal API changes (e.g., renamed classes/namespaces).
  • Mitigation:
    • Monitor PHPStan changelog for 2.2.x updates.
    • Automate stub regeneration (e.g., GitHub Actions on PHPStan 2.2.x releases).
    • Fallback: Manually trigger updates via GitHub issue (as before).

• IDE-Specific Quirks:

  • Risk: PHPStan 2.2.4 may alter PHAR structure, causing IDEs to misinterpret stubs.
  • Mitigation:
    • Test in target IDEs (PHPStorm/VSCode) after updating.
    • Document workarounds (e.g., Intelephense config tweaks).

• False Positives/Negatives:

  • Unchanged: Stubs are still "dummies"; validate with actual PHPStan execution.

Key Questions for TPM

1. Is the team using PHPStan 2.2.x?
   • If not, this package requires upgrading PHPStan (may introduce breaking changes).
2. Which IDEs are primary?
   • PHPStorm: Likely seamless.
   • VSCode: Requires Intelephense + manual PHAR stub path configuration.
3. What’s the PHPStan version strategy?
   • Critical: Must pin to ^2.2 to avoid stub drift.
   • Question: Can the team lock to 2.2.4 for stability?
4. Is CI/CD automation feasible?
   • Can stub updates be auto-triggered on PHPStan 2.2.x releases?
5. Are there existing stubs or alternatives?
   • E.g., phpstan/phpstan-src (manual clone) or other generators like vimeo/psalm.

Integration Approach

Stack Fit

• PHP/Laravel Compatibility:

  • Unchanged: Fully compatible with Laravel; dev-only tool.
  • New Constraint: Requires PHPStan 2.2.x (breaking change from prior versions).

• Toolchain Dependencies:

  • Updated:
    • Mandatory: PHPStan ^2.2.0 + this package ^2.2.0.
    • IDE: PHPStorm (native) or VSCode (Intelephense + PHAR stub config).
  • Optional: Custom PHPStan extensions (e.g., phpstan/extension-installer).

Migration Path

1. Pre-Migration Check:
   • Verify PHPStan version (composer show phpstan/phpstan).
   • If <2.2: Upgrade PHPStan to ^2.2.0 (may require rule adjustments).
2. Installation:
   • Update composer.json:

     "require-dev": {
       "phpstan/phpstan": "^2.2",
       "headercat/phpstan-extension-ide-helper": "^2.2"
     }
     

   • Run composer update.
3. IDE Configuration:
   • PHPStorm: Ensure "PHPStan" plugin is enabled and PHAR stubs are auto-detected.
   • VSCode: Add to intelephense.config.json:

     {
       "phpstan": {
         "pharStubPaths": ["vendor/phpstan/phpstan/bin/phpstan.phar"]
       }
     }
     

4. Validation:
   • Test autocompletion in custom PHPStan rules.
   • Run phpstan analyse to confirm no runtime issues.

Compatibility

• PHPStan Versions:

  • Strict: Now only works with PHPStan 2.2.x.
    • Breaking Risk: Upgrading PHPStan to 3.0 will break stubs (no backward compatibility).
  • Mitigation: Pin to 2.2.4 for stability:

    "phpstan/phpstan": "2.2.4",
    "headercat/phpstan-extension-ide-helper": "2.2.4"
    

• IDE Support:

  • PHPStorm: Should work out-of-the-box for PHAR stubs.
  • VSCode: Requires Intelephense and explicit PHAR path configuration.
  • Other IDEs: May need manual setup (e.g., NetBeans with custom include paths).

Sequencing

1. Pre-Extension Development:
   • Install stubs before writing custom PHPStan rules to enable autocompletion.
2. Post-Update Workflow:
   • After PHPStan 2.2.x updates, trigger stub regeneration (manual or automated).
   • Rebuild IDE caches (e.g., PHPStorm: File > Invalidate Caches).
3. CI/CD (Recommended):
   • Add a GitHub Actions workflow to:
     • Monitor PHPStan 2.2.x releases.
     • Auto-trigger stub updates (via GitHub issue or API).
     • Alert the team (e.g., Slack notification).

Operational Impact

Maintenance

• Update Cadence:
  • Manual: Requires GitHub issue comment (slower for 2.2.x updates).
  • Automated: Recommended for teams using PHPStan 2.2.x:
    • Example workflow:

      name: Update PHPStan Stubs
      on:
        schedule:
          - cron: '0 0 * * *' # Daily
        workflow_dispatch:
      jobs:
        update:
          runs-on: ubuntu-latest
          steps:
            - uses: actions/github-script@v6
              with:
                script: |
                  await github.rest.issues.create({
                    owner: 'headercat',
                    repo: 'phpstan-extension-ide-helper',
                    title: 'Trigger stub regeneration',
                    body: 'Please regenerate stubs for PHPStan 2.2.x'
                  })
      

• Dependency Management:
  • Critical: Pin phpstan/phpstan to 2.2.4 to avoid stub drift.
  • Monitor for PHPStan 3.0 (will break compatibility).

Support

• Troubleshooting:

  • Common Issues:
    • Stubs not loading: Verify IDE settings and PHAR path.
    • Outdated stubs: Trigger regeneration (manual/automated).
    • False autocompletion: Stubs are dummies; validate with phpstan analyse.
  • Debugging:
    • Check stub generation logs (GitHub issue comments).
    • Use composer show headercat/phpstan-extension-ide-helper to verify version.

• Documentation:

  • Update team’s PHPStan extension guide with:
    • Version pinning requirements (^2.2.0).
    • IDE-specific configurations (PHPStorm/VSCode).
    • Update workflow (manual/automated).

Scaling

• Team Size:
  • Small Teams: Manual updates suffice.
  • Large Teams: Automate updates to reduce friction (e