Phpstan Git Files Laravel Package

Technical Evaluation

Architecture Fit

• Pros:

  • Backward Compatibility: Backport of PR #112 to 10.x ensures stability for Laravel projects still using PHPStan 10.x (common in legacy Laravel 8/9 apps).
  • Minimal Risk: No breaking changes implied; PR #112 likely addressed edge cases (e.g., path resolution, Git submodules) without altering core functionality.
  • CI/CD Resilience: If PR #112 fixed getcwd() issues in CI, this backport mitigates the Technical Risk noted for multi-repo or non-standard working directories.
  • Git Awareness: Continued alignment with Git workflows, reducing manual excludePaths in phpstan.neon.

• Cons:

  • No Explicit Features: Release notes lack details on PR #112’s scope (e.g., did it fix symlinks, submodules, or CI path issues?). Assumptions remain speculative.
  • Version Fragmentation: Maintaining 10.x may delay adoption of PHPStan 11.x features (e.g., new rules) in Laravel projects.
  • Copilot Contribution: Unclear if PR #112 was thoroughly tested; bot-generated changes may introduce subtle bugs (e.g., regex edge cases in file discovery).

Integration Feasibility

• Laravel Compatibility:

  • Unchanged: No conflicts with Laravel core or PHPStan 10.x extensions (e.g., phpstan/laravel).
  • Artisan Integration: Custom commands (e.g., php artisan phpstan:git) remain viable for path resolution.

• Dependencies:

  • Stable: Only PHPStan 10.x and Git. No new OS/PHP extensions required.
  • Conflict Risk: None with Laravel’s Illuminate/Foundation/Console or PHPStan’s extension system.

Technical Risk

• Low (Previously Medium):
  • Path Resolution:
    • Mitigated: If PR #112 addressed getcwd() issues, CI/CD robustness improves. Validate in pipelines with:

      # Test in GitHub Actions
      - run: pwd && git rev-parse --show-toplevel
      

  • Performance: Unchanged; benchmarking still required for large repos.
  • Version Lock:
    • Risk: PHPStan 11.x support remains untested. Prioritize testing if upgrading.
  • Edge Cases:
    • Unclear: PR #112’s scope unknown. Test with:
      • Symlinked directories (e.g., ln -s vendor/ app/vendor).
      • Sparse checkouts (git read-tree --partial).
      • Submodules (git submodule update --init).

Key Questions

1. PR #112 Details:
   • What specific issues did PR #112 resolve? (e.g., CI paths, symlinks, submodules).
   • Were there breaking changes in the backport process?
2. Testing Coverage:
   • Was PR #112 manually tested, or was it auto-merged via Copilot?
   • Are there known regressions in PHPStan 10.x after the backport?
3. Upgrade Path:
   • Should Laravel projects on PHPStan 10.x migrate to 11.x post-backport, or wait for native 11.x support?
4. Generated Files:
   • Does this release handle Laravel-specific files (e.g., storage/framework/views) better? If not, how?
5. Maintenance:
   • Will future 10.x releases include more Git/PHPStan integration, or is this a one-time fix?

Integration Approach

Stack Fit

• PHPStan Ecosystem:

  • Backward Compatibility: Safe for PHPStan 10.x users. No changes to NEON include syntax.
  • Laravel Tools:
    • Artisan: Custom commands (e.g., php artisan phpstan:git) can now rely on the backported fixes for path resolution.
    • CI/CD: Updated pipelines should test the backport’s CI robustness (see Technical Risk).

• Laravel-Specific:

  • Path Resolution: If PR #112 fixed getcwd(), replace getcwd() with base_path() in custom commands for consistency.
  • Generated Files: Explicitly exclude Laravel-specific paths in phpstan.neon:

    excludePaths:
      - storage/framework/views/
      - bootstrap/cache/
    

Migration Path

1. Validation Phase:

   • Test Environment: Upgrade to 10.2.8 and verify:

     composer require andersundsehr/phpstan-git-files:10.2.8
     

   • CI/CD Check: Run in pipelines with non-standard pwd (e.g., GitHub Actions working-directory).
   • Regression Test: Compare output with git ls-files for missed files.

2. Artisan Integration (Updated):

   • Modify custom commands to leverage the backport’s fixes:

     public function handle() {
         $this->call('phpstan', [
             '--config' => 'phpstan.neon',
             '--include-extension' => base_path('vendor/andersundsehr/phpstan-git-files/extension.php'),
         ]);
     }
     

3. Full Adoption:

   • Replace manual includePaths with the extension in phpstan.neon.
   • Monitor for:
     • False positives/negatives in Laravel-specific files (e.g., Blade stubs).
     • Performance changes (compare with pre-10.2.8 benchmarks).

Compatibility

• PHPStan Versions:

  • Supported: 10.x (now with PR #112 fixes). Test PHPStan 11.x separately.
  • Downgrade: Safe to revert to 10.2.7 if issues arise.

• Git Environments:

  • Assumptions: PR #112 likely improved:
    • CI path resolution (e.g., GitHub Actions working-directory).
    • Submodule support (if PR #112 addressed symlinks).
  • Validation Required:
    • Sparse checkouts: git read-tree --partial.
    • Symlinks: git config --global core.symlinks true.

• Laravel-Specific:

  • No Conflicts: Compatible with:
    • Laravel 8/9 (PHPStan 10.x).
    • Packages like spatie/laravel-package-tools.
  • Docker: Works if getcwd() aligns with base_path() (standard in Laravel Dockerfiles).

Sequencing

1. Prerequisites:

   • PHPStan 10.x installed (composer require phpstan/phpstan:^1.0).
   • Git configured (git init).

2. Installation:

   composer require andersundsehr/phpstan-git-files:10.2.8
   

3. Configuration:

   • Update phpstan.neon:

     includes:
       - vendor/andersundsehr/phpstan-git-files/extension.php
     excludePaths:
       - storage/
       - tests/
     

   • For Laravel, add a custom command (see above).

4. Post-Deployment:

   • Update CI/CD to use 10.2.8 and test edge cases:

     - run: ./vendor/bin/phpstan analyse --include-extension=vendor/andersundsehr/phpstan-git-files/extension.php
     

   • Benchmark performance and compare with git ls-files.

Operational Impact

Maintenance

• Reduced Overhead:
  • Backport reduces manual excludePaths maintenance (e.g., for CI or submodules).
  • Risk: If PR #112 introduced bugs, rollback to 10.2.7 is straightforward.
• Dependency Updates:
  • Monitor for PHPStan 10.x EOL (deprecate if 11.x becomes mandatory).
  • Watch for Git behavior changes (e.g., new file types, sparse checkout improvements).

Support

• Troubleshooting:
  • Common Issues:
    • Missing files: Compare phpstan analyse --generate-baseline with git ls-files.
    • CI failures: Log pwd and git rev-parse --show-toplevel in pipelines.
  • Laravel-Specific:
    • Blade stubs: Exclude storage/framework/views/ unless analyzing compiled code.
    • API clients: Manually include stubs (e.g., vendor/guzzlehttp/psr7/src/) if needed.
• Documentation:
  • Update runbooks for:
    • Path resolution in CI.
    • Excluding Laravel-generated files.

Scaling

• Performance:
  • No Changes: Backport doesn’t alter file discovery logic. Benchmark in large repos (>50K files).
  • Optimizations:
    • Use PHPStan’s --parallel for multi-core analysis.
    • Exclude node_modules/ and `vendor