Phpstan Rules Laravel Package

Technical Evaluation

Architecture Fit

• Pros:

  • Symfony/Doctrine/PHPUnit Focus: Aligns perfectly with Laravel’s core dependencies (Symfony components, Doctrine DBAL/ORM, PHPUnit for testing). Many rules (e.g., NoEntityOutsideEntityNamespaceRule, ForbiddenNewArgumentRule) directly address Laravel’s common anti-patterns (e.g., manual service instantiation, misplaced Doctrine entities).
  • Clean Architecture Enforcement: Rules like ClassNameRespectsParentSuffixRule, ExplicitClassPrefixSuffixRule, and CheckRequiredInterfaceInContractNamespaceRule enforce Laravel’s PSR-4 and Domain-Driven Design patterns, reducing technical debt.
  • Static Analysis Synergy: Integrates seamlessly with Laravel’s existing tooling (PHPStan, Pest/PHPUnit) without requiring major architectural shifts. Complements Laravel’s built-in phpstan.neon configurations.
  • Configurability: Rules like ForbiddenFuncCallRule or PreferredClassRule allow granular control, aligning with Laravel’s principle of convention over configuration while permitting exceptions.

• Cons:

  • Laravel-Specific Gaps: Some rules (e.g., Symfony’s SingleRequiredMethodRule) may not directly apply to Laravel’s dependency injection (Laravel’s container vs. Symfony’s autowiring). Requires customization or exclusion.
  • Overlap with Laravel’s Rules: Some checks (e.g., NoGlobalConstRule) may conflict with Laravel’s existing conventions (e.g., config('app.name')). Requires careful tuning.
  • Performance Overhead: Adding 80+ rules may slow down CI/CD pipelines initially, though this is mitigated by PHPStan’s incremental analysis.

Integration Feasibility

• Low Risk:
  • Composer Integration: Simple composer require with no breaking changes to Laravel’s core.
  • PHPStan Extension Installer: Laravel’s phpstan/extension-installer (commonly used via phpstan:install Artisan command) supports this package out-of-the-box.
  • Neon Configuration: Minimal changes to phpstan.neon (e.g., including rule sets) with no impact on Laravel’s routing, service container, or Blade templates.
• Potential Challenges:
  • Rule Conflicts: Some rules (e.g., NoTestMocksRule) may clash with Laravel’s testing conventions (e.g., Mockery or PHPUnit mocks). Requires explicit exclusion in phpstan.neon.
  • Custom Rules: Laravel-specific rules (e.g., for Illuminate\Contracts or Laravel\Nova) would need to be added via custom PHPStan extensions.

Technical Risk

• Minimal:
  • Backward Compatibility: MIT-licensed, no dependencies on Laravel internals. Safe to adopt incrementally.
  • False Positives/Negatives: Most rules are well-documented with examples, reducing risk of misconfiguration. Laravel’s type hints (e.g., array<int, string>) align well with PHPStan’s expectations.
• Mitigable Risks:
  • Rule Overload: Start with a subset (e.g., naming-rules.neon, doctrine-rules.neon) to avoid overwhelming developers.
  • CI/CD Impact: Gradually enable rules to avoid blocking builds. Use PHPStan’s --error-format=github for actionable feedback.

Key Questions

1. Prioritization:
   • Which Laravel-specific anti-patterns (e.g., manual Eloquent model instantiation, Blade template logic) should be targeted first?
   • Should rules like ForbiddenNewArgumentRule be configured to exclude Laravel’s AppServiceProvider or Bootstrap classes?
2. Customization:
   • Are there Laravel-specific rules (e.g., for Illuminate\Foundation\Application) that should be contributed upstream?
   • How to handle conflicts with Laravel’s built-in phpstan.neon (e.g., level: 5 vs. custom rule levels)?
3. Adoption Strategy:
   • Should rules be enabled in CI first (e.g., level: 3) or in PR checks (e.g., level: 5)?
   • How to communicate rule changes to developers (e.g., via Laravel’s upgrade guide)?
4. Performance:
   • Should PHPStan’s parallel mode be enabled to offset the rule overhead?
   • Are there Laravel-specific optimizations (e.g., caching vendor/ paths) to reduce analysis time?

Integration Approach

Stack Fit

• Native Compatibility:
  • PHPStan: Fully compatible with Laravel’s default PHPStan setup (version ^1.0). No conflicts with Laravel’s phpstan.neon or rector.php.
  • Symfony Components: Rules for Symfony\Component\HttpKernel, Symfony\Component\Routing, etc., align with Laravel’s Symfony-based foundations (e.g., Illuminate\Routing, Illuminate\Http).
  • Doctrine ORM/DBAL: Rules like NoEntityOutsideEntityNamespaceRule and ForbiddenNewArgumentRule directly address Laravel Eloquent’s common pitfalls.
  • PHPUnit/Pest: Rules like NoTestMocksRule and NoArrayMapWithArrayCallableRule improve test quality, complementing Laravel’s testing tools.
• Non-Native Considerations:
  • Laravel-Specific Tools: Rules for Laravel\Nova, Laravel\Fortify, or Laravel\Vapor would require custom extensions.
  • Blade Templates: PHPStan rules don’t analyze Blade files natively (use nunomaduro/collision or [barryvdh/laravel-ide-helper] for static analysis).

Migration Path

1. Phase 1: Setup and Validation

   • Add to composer.json:

     composer require --dev symplify/phpstan-rules ^8.0
     

   • Install via PHPStan extension installer (Laravel’s phpstan:install command handles this automatically).
   • Update phpstan.neon to include core rule sets:

     includes:
         - vendor/symplify/phpstan-rules/config/naming-rules.neon
         - vendor/symplify/phpstan-rules/config/static-rules.neon
         - vendor/symplify/phpstan-rules/config/doctrine-rules.neon
     

   • Run locally and validate no false positives:

     vendor/bin/phpstan analyse --level=5
     

2. Phase 2: Incremental Enforcement

   • Enable rules in CI first (e.g., GitHub Actions) with --level=3 to avoid build breaks.
   • Gradually add rule sets (e.g., symfony-rules.neon, complexity-rules.neon) based on team feedback.
   • Example CI configuration:

     - name: PHPStan (Symplify Rules)
       run: vendor/bin/phpstan analyse --level=3 --error-format=github
     

3. Phase 3: Customization

   • Configure Laravel-specific exclusions in phpstan.neon:

     parameters:
         maximumIgnoredErrorCount: 100
     services:
         - Symplify\PHPStanRules\Rules\ForbiddenNewArgumentRule:
             arguments:
                 forbiddenTypes:
                     - Illuminate\Foundation\Application # Exclude Laravel container
     

   • Add custom rules for Laravel patterns (e.g., ForbiddenRouteAnnotationRule for Route::get()).

4. Phase 4: Documentation and Training

   • Document enabled rules in CONTRIBUTING.md or a DEVELOPMENT.md file.
   • Provide a phpstan-fixes.md guide with examples of how to resolve common rule violations (e.g., converting new App\Models\User to dependency injection).

Compatibility

• Laravel Versions:
  • Compatible with Laravel 8+ (PHP 8.0+) due to PHPStan’s PHP 8.0+ requirements. Laravel 7.x would need PHPStan ^0.12 (deprecated).
  • Tested with Symfony ^5.4|^6.0, which aligns with Laravel’s Symfony 5/6 components.
• Tooling Conflicts:
  • Rector: No conflicts, but ensure Rector runs before PHPStan to avoid analyzing auto-fixed code.
  • Pint/PHP-CS-Fixer: Rules like NoArrayMapWithArrayCallableRule may suggest refactors that conflict with code style tools. Prioritize PHPStan’s suggestions.
  • Laravel Mix/Vite: No impact, as rules target PHP/Neon files only.

Sequencing

1. Pre-requisites:
   • Ensure PHPStan is already configured in Laravel (