Phpstan Shim Laravel Package

Technical Evaluation

Architecture Fit

• Obsolete for Modern Laravel: The phpstan/phpstan-shim package is completely deprecated per the 0.12.0 release notes, which explicitly state it is no longer needed due to PHPStan’s shift to a PHAR-based distribution. This renders the package irrelevant for any Laravel project using PHPStan 0.12+ or modern Composer workflows.
• Static Analysis Redundancy: The shim’s sole purpose (resolving legacy PHPStan v0.x/v1.x dependency conflicts) is obsolete—PHPStan 0.12+ resolves this natively via PHAR files and Composer’s autoloader. Modern Laravel projects (8.x+) should use phpstan/phpstan:^0.12 or later.
• Laravel Integration Gaps: The shim offers zero Laravel-specific value. Modern alternatives like phpstan/phpstan + laravel-shift/phpstan-rules provide:
  • Eloquent query analysis.
  • Facade-aware type checking.
  • Blade template support (via extensions like nunomaduro/phpstan-laravel).

Integration Feasibility

• Composer Conflict Resolution: The shim’s conflict-resolution role is eliminated in PHPStan 0.12+. The PHAR distribution avoids vendor/ dependency hell entirely.
• Legacy Laravel 5.x/6.x: Even for outdated projects, the shim is not a solution—PHPStan 0.12+ requires PHP 7.2+ (Laravel 5.8+). Upgrade paths:
  • Laravel 5.x → Upgrade to Laravel 8.x+ + PHPStan 1.x.
  • Laravel 6.x → Use PHPStan 0.12.99 (last 0.x release) with PHAR.
• Build Tooling: Modern PHPStan integrates seamlessly with:
  • Laravel Mix/Vite (via composer.json scripts).
  • PestPHP (native support).
  • PHPUnit (pre-commit hooks).

Technical Risk

• Deprecation Certainty: The 0.12.0 release explicitly deprecates the shim, with no forward-compatibility path. Using it introduces:
  • Security risks (unmaintained transitive dependencies).
  • Breakage when PHPStan’s PHAR API evolves.
• False Assurance: Projects using the shim may assume static analysis is "working" while missing Laravel-specific issues due to outdated rules.
• Migration Blockers: The shim’s removal of vendor/bin/phpstan may break:
  • Custom scripts.
  • CI/CD pipelines relying on phpstan-shim.

Key Questions

1. Why Persist with the Shim?
   • Is the project blocked by a specific dependency conflict that PHPStan 0.12+ cannot resolve? If so, provide details for triage.
   • Are there undocumented shim features critical to the workflow? (E.g., custom PHAR paths?)
2. Upgrade Path Validation
   • Has the team tested phpstan/phpstan:^0.12 with the Laravel version in use? If not, what’s the blocker?
   • For Laravel 5.x/6.x, is PHPStan 0.12.99 (PHAR-only) a viable stopgap? Or must the project upgrade Laravel first?
3. CI/CD Impact
   • Which pipelines reference phpstan-shim? Example risks:
     • GitHub Actions: phpstan-shim → phpstan/phpstan:0.12.
     • GitLab CI: Replace before_script: composer install with PHAR-specific steps.
4. Laravel-Specific Gaps
   • Are there critical static analysis needs (e.g., Blade templates, Horizon queues) that require extensions beyond phpstan/phpstan?
   • Has laravel-shift/phpstan-rules been evaluated as a drop-in replacement?

Integration Approach

Stack Fit

• Modern Laravel (8.x/9.x/10.x) + PHP 8.0+:
  • Fully compatible with phpstan/phpstan:^1.0 (recommended) or ^0.12 (minimum).
  • PHAR-based: No vendor/ pollution; integrates with Composer’s bin-dir.
  • Laravel Extensions: Pair with:

    composer require --dev laravel-shift/phpstan-rules nunomaduro/phpstan-laravel
    

• Legacy Laravel (5.x/6.x):
  • PHPStan 0.12.99 (PHAR-only) may work but is unsupported. Prioritize Laravel upgrade.
  • Workaround: Use phpstan/phpstan:0.12.99 with:

    composer require phpstan/phpstan:0.12.99 --ignore-platform-reqs
    

Migration Path

1. Audit Current Usage:

   • Search for:

     grep -r "phpstan-shim" . || find . -name "*phpstan-shim*"
     

   • Identify scripts/CI steps using vendor/bin/phpstan-shim.

2. Replace with PHAR:

   • Update composer.json:

     - "phpstan/phpstan-shim": "^0.10"
     + "phpstan/phpstan": "^0.12"
     

   • Remove shim artifacts:

     rm -rf vendor/phpstan vendor/bin/phpstan vendor/bin/phpstan.phar
     composer install
     

   • Verify PHAR is installed:

     vendor/bin/phpstan --version
     

3. Laravel-Specific Setup:

   • Configure phpstan.neon:

     includes:
       - app/
       - config/
       - routes/
       - tests/
     level: max
     extends:
       - phpstan/laravel.neon
       - vendor/laravel-shift/phpstan-rules/laravel-shift.neon
     

   • Add to composer.json scripts:

     "scripts": {
       "phpstan": "vendor/bin/phpstan analyse --level=max"
     }
     

4. CI/CD Update:

   • GitHub Actions:

     - name: PHPStan
       run: composer run phpstan
     

   • GitLab CI:

     phpstan:
       script: composer run phpstan
     

Compatibility

• PHPStan 0.12+:
  • Breaking: PHAR replaces vendor/ dependencies. Ensure no scripts hardcode vendor/bin/phpstan-shim.
  • Fixable: Use composer run phpstan or ./vendor/bin/phpstan (PHAR is symlinked).
• Laravel Extensions:
  • laravel-shift/phpstan-rules: Works with PHPStan 0.12+.
  • nunomaduro/phpstan-laravel: Blade template analysis (PHPStan 1.0+).
• Tooling Conflicts:
  • Avoid mixing PHPStan versions. Use composer why-not to detect conflicts:

    composer why-not phpstan/phpstan:^1.0
    

Sequencing

1. Pre-Migration:
   • Backup composer.lock and vendor/.
   • Test PHPStan 0.12 in a staging environment:

     composer require phpstan/phpstan:0.12.0 --dev --ignore-platform-reqs
     vendor/bin/phpstan analyse --level=5
     

2. Migration:
   • Update composer.json → composer update phpstan/phpstan --with-all-dependencies.
   • Run composer run phpstan --generate-baseline to adapt to new rules.
3. Post-Migration:
   • Remove all shim references from:
     • composer.json.
     • CI/CD scripts.
     • Local development aliases.
   • Add Laravel-specific rulesets incrementally.

Operational Impact

Maintenance

• Zero Maintenance for Shim: The package is abandoned, but this is a false economy—it introduces:
  • Security debt (unpatched dependencies).
  • Technical debt (no Laravel/PHPStan compatibility updates).
• Modern PHPStan:
  • Active development: Monthly releases with Laravel-specific improvements.
  • Maintenance tasks:

    composer require phpstan/phpstan:^1.0 --dev
    composer require laravel-shift/phpstan-rules --dev
    

  • Rule Updates: Extend phpstan.neon as Laravel evolves (e.g., add app/Console/Kernel.php for Horizon).

Support

• No Vendor Support: The shim is archived; issues will not be resolved.
• Modern Support Channels:
  • PHPStan: GitHub Issues, Slack.