Phpstan Git Files Laravel Package

Getting Started

Minimal Setup

1. Install the package in your Laravel project:

   composer require --dev andersundsehr/phpstan-git-files
   

2. Include the extension in your phpstan.neon config:

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

3. Run PHPStan to verify all Git-tracked .php files are included:

   ./vendor/bin/phpstan analyse
   

First Use Case

Problem: You have a Laravel project with PHP files scattered across app/, src/, and tests/ directories, and manually maintaining includePaths in phpstan.neon is tedious.

Solution: Use phpstan-git-files to automatically include all Git-tracked .php files, reducing config drift and ensuring consistent coverage.

Implementation Patterns

Workflow Integration

1. Daily Development:

   • Add new .php files to Git (git add).
   • PHPStan automatically includes them in analysis without config updates.
   • Example:

     git add app/Services/NewService.php
     ./vendor/bin/phpstan analyse  # NewService.php is now checked
     

2. CI/CD Pipeline:

   • Add the extension to your PHPStan step in GitHub Actions/GitLab CI:

     - name: Run PHPStan
       run: ./vendor/bin/phpstan analyse
     

   • No need to manually update file paths when new files are added.

3. Hybrid Configuration:

   • Combine with explicit paths for critical files:

     includes:
         - vendor/andersundsehr/phpstan-git-files/extension.php
         - app/Providers/
         - src/Contracts/
     

Laravel-Specific Patterns

1. Artisan Command Wrapper:

   • Extend Laravel’s Artisan to auto-include the extension:

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

2. Pint/CS Fixer Integration:

   • Ensure PHPStan runs after code formatting to avoid false positives:

     # .github/workflows/ci.yml
     - run: ./vendor/bin/pint
     - run: ./vendor/bin/phpstan analyse
     

3. Monorepo Handling:

   • Use Git submodules or .gitignore to scope analysis to Laravel-specific files:

     excludePaths:
         - vendor/
         - node_modules/
         - storage/
     

Gotchas and Tips

Pitfalls

1. Path Resolution Issues:

   • Problem: The extension uses getcwd() (fixed in v10.2.7), which may not match the repo root in CI/CD or multi-repo setups.
   • Fix: Ensure getcwd() aligns with the repo root. Debug with:

     echo $(getcwd)
     git rev-parse --show-toplevel
     

2. Untracked Files:

   • Problem: Only Git-tracked files are included. Untracked files (e.g., vendor/, generated code) are excluded.
   • Fix: Manually include directories or use PHPStan’s includePaths:

     includePaths:
         - vendor/autoload.php
     

3. Performance Overhead:

   • Problem: Scanning all Git files can slow down analysis in large repos.
   • Fix: Exclude directories or use PHPStan’s --parallel flag:

     ./vendor/bin/phpstan analyse --parallel
     

4. Git-Specific Quirks:

   • Problem: Sparse checkouts or submodules may cause missing files.
   • Fix: Test in your Git environment. For submodules, ensure paths are resolved correctly.

Debugging Tips

1. Verify Included Files:

   • Run PHPStan with debug output to see included files:

     ./vendor/bin/phpstan analyse --debug
     

2. Check Git Tracking:

   • Ensure files are tracked:

     git check-ignore -v path/to/file.php
     

3. Fallback Config:

   • Maintain a hybrid config to debug issues:

     includes:
         - vendor/andersundsehr/phpstan-git-files/extension.php
         - app/  # Fallback for critical paths
     

Extension Points

1. Custom Exclusions:

   • Use PHPStan’s excludePaths to filter files:

     excludePaths:
         - tests/
         - storage/logs/
     

2. Post-Install Hooks:

   • Add a Git hook to validate PHPStan coverage:

     # .git/hooks/post-commit
     ./vendor/bin/phpstan analyse --no-progress-bar
     

3. CI/CD Validation:

   • Fail the pipeline if Git-tracked files are missed:

     - name: Check PHPStan Coverage
       run: |
         git ls-files "*.php" | while read file; do
           if ! ./vendor/bin/phpstan analyse --paths="$file" --no-progress-bar; then
             exit 1
           fi
         done