Phpstan Git Files Laravel Package

Product Decisions This Supports

• Automated Static Analysis at Scale: Eliminates manual path configuration for PHPStan in Laravel projects, enabling seamless adoption across large codebases (e.g., monorepos, multi-package repositories). Reduces technical debt by aligning analysis scope with Git-tracked files, ensuring consistency in CI/CD pipelines.
• Developer Experience (DX) Optimization: Aligns with Laravel’s philosophy of reducing boilerplate. Developers no longer need to maintain phpstan.neon file lists, accelerating onboarding and reducing context-switching between Git and PHPStan configurations.
• Shift-Left Quality Initiatives: Supports a phased rollout of static analysis by dynamically expanding PHPStan’s scope to include all Git-tracked .php files. Future-proofs for extensions like phpstan-git-files:exclude to handle edge cases (e.g., generated code, vendor files).
• Build vs. Buy Decision: Justifies adopting this lightweight, open-source package over custom scripting (e.g., Bash/Python) to avoid maintenance overhead. The package’s Git-aware design and PHPStan-native integration reduce risk compared to in-house solutions.
• Use Cases:
  • Legacy Laravel Applications: Gradually introduce PHPStan without upfront path mapping, reducing migration friction.
  • Multi-Package Repositories: Standardize analysis across fragmented Laravel packages (e.g., packages/, modules/).
  • Generated Code Inclusion: Automatically include dynamically generated .php files (e.g., from Blade templates, API clients) without manual updates.
  • CI/CD Efficiency: Reduce flaky PHPStan runs in pipelines by ensuring all tracked files are analyzed, improving reliability of quality gates.

When to Consider This Package

• Adopt When:

  • Your Laravel project uses PHPStan and has >50 .php files distributed across multiple directories (e.g., app/, src/, packages/).
  • You lack a centralized or maintainable PHPStan configuration (e.g., no phpstan.neon with exhaustive includes or wildcards).
  • Your team prioritizes CI/CD efficiency and wants to avoid manual path exclusions/inclusions that break over time.
  • You’re using Git for version control and want to leverage its file tracking to define PHPStan’s analysis scope dynamically.
  • You’re adopting PHPStan in a monorepo or multi-package Laravel setup where manual path management is unsustainable.

• Look Elsewhere If:

  • Your codebase is not Git-managed (e.g., SVN, custom VCS) or relies on non-PHP files (e.g., .php.twig, .blade.php).
  • You need fine-grained control over excluded files (e.g., ignoring tests/, node_modules/, or specific file patterns). Consider PHPStan’s native excludePaths or custom scripts.
  • Your project already has a mature PHPStan config with explicit, well-maintained paths (risk of duplication or conflicts).
  • You’re constrained by PHPStan’s memory limits (this package includes all Git-tracked files, which may bloat analysis for large repos).
  • Your Laravel project uses non-standard Git setups (e.g., sparse checkouts, bare repos, or complex submodule hierarchies) that could break path resolution.

How to Pitch It (Stakeholders)

For Executives:

*"This package solves a hidden technical debt drain in our Laravel codebase. Today, ensuring PHPStan analyzes all critical .php files requires manual path configuration—a process that’s error-prone, time-consuming, and breaks as our codebase grows. By adopting phpstan-git-files, we automate this entirely: all Git-tracked PHP files are included in analysis with a single Composer install. This isn’t just a tool—it’s a force multiplier for our quality initiatives:

• Saves 10+ hours/week in manual config maintenance (based on similar projects).
• Future-proofs our CI/CD pipelines by eliminating flaky path exclusions.
• Lowers onboarding friction for new devs by reducing PHPStan setup complexity. The cost? Zero upfront investment—just a 5-minute Composer command. The ROI? Fewer bugs slipping into production and a more scalable static analysis strategy."*

For Engineering Teams:

*"Problem: PHPStan’s static analysis is only as good as its file coverage. Today, we either:

1. Manually list every .php file in phpstan.neon (error-prone, unscalable), or
2. Use wildcards (risk of false positives/negatives or missing critical files).

Solution: phpstan-git-files dynamically includes all Git-tracked .php files in analysis. Here’s why it’s a no-brainer for Laravel:

• Zero Maintenance: Updates automatically when you git add new files.
• PHPStan-Native: Just add one line to your phpstan.neon—no hacks.
• CI/CD Ready: Works out-of-the-box in GitHub Actions, GitLab CI, etc.
• Laravel-Friendly: No conflicts with Artisan, Forge, or Valet.

Proposal: Let’s pilot this in [Project X] for 2 sprints. If it: ✅ Reduces our PHPStan false negatives by >20%, ✅ Cuts config updates by >50%, ✅ Doesn’t break our CI pipelines, …we’ll roll it out to all Laravel projects. Worst case? We remove it in 5 minutes.

Next Steps:

1. Install in a dev environment: composer require --dev andersundsehr/phpstan-git-files.
2. Add to phpstan.neon:

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

3. Run ./vendor/bin/phpstan analyse and validate coverage.
4. Monitor performance in CI/CD.

Key Metric: Track “% of Git-tracked .php files covered by PHPStan” before/after adoption."*

For Architects/Tech Leads: *"This package addresses a critical gap in Laravel’s static analysis tooling. By tying PHPStan’s file inclusion to Git’s tracking system, we:

• Eliminate config drift: No more stale includePaths in phpstan.neon.
• Align with Git workflows: Changes to tracked files are auto-reflected in analysis.
• Reduce cognitive load: Developers focus on code, not path management.

Trade-offs:

• Exclusion Granularity: Lacks .gitignore-style patterns (mitigate with PHPStan’s excludePaths).
• Path Resolution: Relies on getcwd() (tested in 10.2.7+; validate in CI/CD).
• Performance: May slow analysis in monorepos (benchmark with --debug).

Recommendation: Adopt as a default inclusion for new Laravel projects, with opt-outs for edge cases. Pair with a runbook for debugging path issues and hybrid configs."*