Phpstan Extensions Laravel Package

Technical Evaluation

Architecture Fit

• Static Analysis Alignment: The package extends PHPStan, a mature static analysis tool, making it a natural fit for Laravel/PHP projects where type safety and code quality are priorities. The rules target anti-patterns, type safety, and framework-specific best practices (Symfony/Yii), aligning with Laravel’s emphasis on clean, maintainable code.
• Rule Granularity: Rules are modular (e.g., UnusedVariableRule, StringToClassRule) and framework-agnostic (with Symfony/Yii-specific configs), allowing selective adoption. This avoids overhead in non-relevant contexts (e.g., Yii rules in a Symfony project).
• PHPStan Ecosystem: Leverages PHPStan’s extension system, ensuring seamless integration with existing workflows (e.g., phpstan/extension-installer). Compatible with PHPStan 2.0+, which is widely adopted in modern Laravel projects.

Integration Feasibility

• Low Friction: Installation via Composer (--dev) and zero runtime overhead (static analysis only). Config inclusion is explicit (phpstan.neon), avoiding silent behavior.
• Framework-Specific Rules: Symfony/Yii configs provide out-of-the-box compliance checks for framework-specific anti-patterns (e.g., raw filesystem calls in Symfony). Laravel-specific rules are absent but extensible (e.g., could add Illuminate-specific checks).
• Customization: Rules can be enabled/disabled per file/directory in phpstan.neon, allowing gradual adoption.

Technical Risk

• False Positives/Negatives:
  • Rules like UnusedVariableRule or MissingClosureParameterTypehintRule may flag legitimate patterns (e.g., unused variables in compact() calls or dynamic closures). Requires tuning via phpstan.neon or rule exceptions.
  • not-now-rules.neon (time/date restrictions) is not foolproof (per README) and may break valid use cases (e.g., legacy code).
• PHPStan Version Lock: Requires PHPStan 2.0+ (dropped PHP 8.2 support in v6.7.0). Risk if project uses older PHPStan (e.g., v1.x).
• Performance: Static analysis adds CPU/memory overhead, but negligible for typical Laravel projects (unless analyzing millions of lines).
• Dependency Bloat: Adds ~50KB (minified) to vendor/, but justified for static analysis.

Key Questions

1. Adoption Scope:
   • Should rules be enforced globally or opt-in per team?
   • Which rules are critical (e.g., StringToClassRule) vs. optional (e.g., not-now-rules)?
2. Framework Alignment:
   • Are there Laravel-specific anti-patterns missing (e.g., Illuminate\Container misuse, Eloquent static calls)?
   • Should a Laravel-specific config (e.g., laravel-rules.neon) be proposed upstream?
3. CI/CD Impact:
   • How will false positives be handled in CI (e.g., allowlist exceptions)?
   • Should rules be gradually enabled (e.g., start with ClassNotationRule)?
4. Maintenance:
   • Who will tune rules as the codebase evolves (e.g., updating phpstan.neon)?
   • How will new PHPStan versions be tested before upgrading?

Integration Approach

Stack Fit

• PHPStan Integration:
  • Primary Use Case: Enhance type safety and code quality in Laravel/PHP projects.
  • Secondary Use Case: Enforce framework-specific best practices (Symfony/Yii) if used.
• Toolchain Compatibility:
  • Works with PHP 8.4+ (Laravel 10+), PHPStan 2.0+, and Composer.
  • No Laravel-specific dependencies, but rules like AccessStaticPropertyWithinModelContextRule could conflict with Laravel’s Service Container patterns.
• IDE Support:
  • Integrates with PHPStorm, VSCode (PHP Intelephense), and other IDEs via PHPStan’s language server protocol (LSP).

Migration Path

1. Assessment Phase:
   • Run PHPStan without extensions to establish a baseline.
   • Identify high-priority rules (e.g., ClassNotationRule, StringToClassRule) for initial adoption.
2. Incremental Rollout:
   • Phase 1: Add slam-rules.neon to phpstan.neon and disable all rules initially.
   • Phase 2: Enable non-breaking rules (e.g., GotoRule, UnusedVariableRule) and fix violations.
   • Phase 3: Enable framework-specific rules (e.g., Symfony/Yii) if applicable.
   • Phase 4: Enable strict rules (e.g., not-now-rules, MissingClosureParameterTypehintRule) with exceptions.
3. CI/CD Integration:
   • Add PHPStan to pre-commit hooks (e.g., via php-cs-fixer) or CI pipelines (GitHub Actions/GitLab CI).
   • Configure fail-on-error for critical rules only.

Compatibility

• PHPStan Version:
  • Minimum: PHPStan 2.0 (v6.6.0+ of the extension).
  • Recommendation: Use latest PHPStan (e.g., 1.x for legacy projects, 2.x+ for new projects).
• Laravel Version:
  • No direct conflicts, but rules like AccessStaticPropertyWithinModelContextRule may flag Laravel’s app() helper if misconfigured.
  • Workaround: Exclude Laravel’s core files (e.g., vendor/laravel/framework) from analysis.
• Existing PHPStan Configs:
  • Merge with existing phpstan.neon without conflicts (rules are additive).
  • Example:

    includes:
      - vendor/phpstan/phpstan/src/Rules/basic.neon
      - vendor/slam/phpstan-extensions/conf/slam-rules.neon
    

Sequencing

1. Pre-Integration:
   • Audit current PHPStan usage (if any) and document existing rules.
   • Backup phpstan.neon before modifications.
2. Installation:

   composer require --dev slam/phpstan-extensions
   

3. Configuration:
   • Add to phpstan.neon:

     includes:
       - vendor/slam/phpstan-extensions/conf/slam-rules.neon
     

   • For Symfony/Yii:

     includes:
       - vendor/slam/phpstan-extensions/conf/symfony-rules.neon
     

4. Testing:
   • Run PHPStan on a small subset of files first to validate rule behavior.
   • Tune false positives via phpstan.neon:

     arguments:
       level: 5
       excludeFiles: ['tests/**', 'vendor/**']
     rules:
       SlamPhpStan\UnusedVariableRule: false  # Disable if problematic
     

Operational Impact

Maintenance

• Rule Updates:
  • Low Effort: Rules are passive (no runtime changes). Updates via Composer (composer update).
  • Breaking Changes: Rare, but PHPStan major versions may require reconfiguration (e.g., PHPStan 1.x → 2.x).
• Configuration Drift:
  • Risk of outdated phpstan.neon if rules are added/removed without documentation.
  • Mitigation: Document enabled/disabled rules in a STATIC_ANALYSIS.md file.
• Dependency Management:
  • No runtime dependencies, but dev dependency adds to composer.json.
  • Renovate/Botkeeper: Can auto-update dependencies (as seen in release history).

Support

• Debugging:
  • Clear Error Messages: Rules use PHPStan’s error format (e.g., SlamPhpStan\UnusedVariableRule).
  • Error Identifiers: Added in v6.4.0 for easier tracking (e.g., unused-variable).
• Community:
  • GitHub Issues: 71 stars but low activity (last release: 2026-05-19). Risk if critical bugs arise.
  • Workarounds: Most issues are configurable (e.g., disable rules via phpstan.neon).
• Onboarding:
  • Documentation: README is clear but sparse on Laravel-specific use cases.
  • **Training