Phpstan Laravel Package

Technical Evaluation

Architecture Fit

• Laravel Synergy: The package’s PHPStan extensions are designed to enhance static analysis for PHP-centric frameworks, making it a natural fit for Laravel’s type-heavy ecosystem (e.g., Eloquent models, service containers, and Blade templates). It complements Laravel’s existing tooling (e.g., pint, php-cs-fixer) by focusing on type safety and code quality rather than formatting.
• Opinionated but Extensible: While opinionated, the rules are modular and can be selectively enabled/disabled via phpstan.neon, allowing alignment with Laravel’s conventions (e.g., dynamic properties, magic methods).
• DevOps Alignment: Integrates seamlessly into CI/CD pipelines (e.g., GitHub Actions, GitLab CI) as a pre-merge or pre-deploy gate, reducing runtime errors and technical debt.

Integration Feasibility

• Minimal Coupling: Integrates via configuration (e.g., includes in phpstan.neon) without modifying Laravel’s core or third-party packages, reducing risk.
• Dependency Lightweight: Only requires PHPStan (already a common dependency in modern Laravel projects) and PHP 8.2+, which aligns with Laravel’s supported versions.
• Customization: Rules can be overridden or excluded per-file/directory, accommodating Laravel’s dynamic patterns (e.g., __get(), __callStatic()).

Technical Risk

• Rule Conflicts: Opinionated rules may clash with Laravel’s dynamic features (e.g., magic methods, dynamic properties) or existing PHPStan configurations. Requires validation against the project’s codebase.
• Maintenance Overhead: Low activity (1 star, last release Jan 2026) raises concerns about long-term viability. May need forking or custom rule maintenance.
• False Positives: Strict rules (e.g., type mismatches) could flag Laravel’s idiomatic patterns as errors, requiring exclusions or annotations (@phpstan-ignore).
• Performance: Static analysis may slow down CI pipelines, especially for large codebases. Mitigation: Incremental analysis or parallel execution.

Key Questions

1. Rule Relevance: Do the package’s rules address Laravel-specific pain points (e.g., Eloquent queries, Blade templates, service container bindings)?
2. Team Readiness: Is the team experienced with PHPStan, or will adoption require training?
3. Customization Needs: Are there Laravel-specific gaps (e.g., rule sets for Laravel Scout, Nova, or Forge) that this package doesn’t cover?
4. Long-Term Support: Given the low adoption, is the maintainer (f3l1x) responsive? Are there alternatives (e.g., phpstan/extension-installer + custom rules)?
5. CI Impact: Will the analysis time exceed thresholds (e.g., GitHub’s 6-minute limit) for large projects?
6. False Positive Rate: How many exclusions (@phpstan-ignore) will be needed to avoid developer frustration?

Integration Approach

Stack Fit

• PHPStan Ecosystem: Designed for PHPStan, which is already integrated into Laravel projects for static analysis. No additional stack changes are required.
• Toolchain Synergy: Works alongside:
  • Laravel Tools: pint (formatting), php-cs-fixer, pest (testing), laravel-telescope (debugging).
  • CI/CD: Can be added to existing workflows (e.g., phpstan analyse in GitHub Actions or GitLab CI).
  • IDE: Integrates with PHPStorm, VSCode (via PHPStan extension) for real-time feedback.
• Laravel-Specific Use Cases: Potential extensions for:
  • Eloquent model validation.
  • Blade template type safety.
  • Service container binding analysis.

Migration Path

1. Assessment Phase:
   • Audit current PHPStan configuration (phpstan.neon) for conflicts or overlaps.
   • Document existing exclusions (e.g., for legacy code or third-party packages).
2. Pilot Installation:
   • Add contributte/phpstan to composer.json under require-dev:

     composer require --dev contributte/phpstan
     

   • Extend phpstan.neon to include Contributte’s rules:

     includes:
         - vendor/contributte/phpstan/extension.neon
     

3. Gradual Rollout:
   • Start with --level=5 (strict) in CI but enable rules incrementally via phpstan.neon:

     extends:
         - phpstan/recommended
         - contributte/phpstan/level5.neon
     

   • Focus on non-breaking rules first (e.g., DeprecatedFunctionRule), then stricter ones (e.g., TypeMismatchRule).
4. Validation:
   • Run phpstan analyse locally and in CI to identify issues.
   • Address false positives with:
     • Exclusions in phpstan.neon:

       excludes:
           - app/OldLegacyCode/
       

     • Annotations in code:

       // @phpstan-ignore-next-line
       $result = $this->dynamicMethod();
       

Compatibility

• Laravel Versions: Compatible with Laravel 8+ (PHP 8.0+) due to PHPStan’s requirements. Test with the project’s specific Laravel version.
• PHPStan Version: Pin to a compatible PHPStan version (e.g., phpstan/phpstan:^1.0) to avoid breaking changes.
• Rule Conflicts: Use phpstan diagnose to detect configuration overlaps and resolve them via excludes or includeRules.

Sequencing

1. Pre-Integration:
   • Backup existing phpstan.neon and CI configurations.
   • Identify critical paths (e.g., API routes, core services) for initial testing.
2. Phased Adoption:
   • Week 1: Install and configure the package. Run locally to identify issues.
   • Week 2: Enable rules in CI for a subset of developers. Monitor feedback.
   • Week 3: Expand to the full team and adjust rules based on false positives.
3. Post-Integration:
   • Update CI to fail builds on new rule violations (start with warnings, then errors).
   • Train developers on interpreting PHPStan output and resolving issues.
   • Schedule periodic reviews of phpstan.neon to update rules or exclusions.

Operational Impact

Maintenance

• Configuration Management:
  • Requires periodic review of phpstan.neon to ensure rules remain relevant as Laravel or PHPStan evolves.
  • Document changes to rules or exclusions for future maintainers.
• Dependency Updates:
  • Monitor Contributte’s releases for breaking changes (though low activity suggests stability).
  • Consider forking the package if long-term maintenance becomes an issue.
• Rule Customization:
  • May need to extend or override rules for Laravel-specific use cases (e.g., custom Eloquent behaviors).
  • Example: Create a custom phpstan.neon extension for Laravel:

    extends:
        - contributte/phpstan/level5.neon
        - vendor/your-team/laravel-phpstan-rules.neon
    

Support

• Learning Curve:
  • Developers unfamiliar with PHPStan may require onboarding (e.g., documentation, pair sessions, or workshops).
  • Provide templates for common annotations (e.g., @phpstan-ignore, @var).
• Debugging:
  • False positives/negatives may require community support (e.g., Contributte’s Gitter forum or GitHub issues).
  • Leverage existing resources:
    • PHPStan Documentation
    • Laravel + PHPStan Guides
• Tooling:
  • Use IDE plugins (e.g., PHPStorm’s PHPStan integration) to reduce manual analysis.

Scaling

• Performance:
  • Static analysis scales with codebase size. For large projects:
    • Use incremental analysis (e.g., focus on changed files in CI).
    • Enable parallel execution:

      phpstan analyse --parallel
      

    • Cache results where possible (e.g., GitHub Actions artifact caching).
  • Monitor CI runtime and adjust thresholds (e.g., GitHub’s 6-minute limit).
• Team Growth:
  • Rules help onboard new developers by enforcing consistency and catching errors early.
  • Reduces "it works on my machine" issues by standardizing type safety.
• Legacy Code:
  • May require gradual enablement or exclusion of older modules.
  • Use excludes in phpstan.neon to phase out legacy code:

    excludes:
        - app/Legacy/
    

Failure Modes

• CI Blockages:
  • Overly strict rules could halt merges. Mitigate with:
    • Phased rollout (start with warnings, then errors).
    • Allow-lists for critical paths (e.g., /app/Http/Controllers/).
    • Gradual increase in rule severity.