Phpstan Generic Rules Laravel Package

Technical Evaluation

Architecture Fit

• Static Analysis Tooling: The korbeil/phpstan-generic-rules package extends PHPStan’s static analysis capabilities, introducing custom rules for generic type hints, collections, and other PHP patterns. This aligns well with Laravel’s PHP-centric architecture, where type safety and maintainability are critical.
• Complementary to Laravel’s Ecosystem: Laravel already leverages PHPStan (via nunomaduro/phpstan-laravel) for static analysis. This package can enhance Laravel’s existing tooling by adding domain-specific rules (e.g., for collections, generics, or Laravel-specific patterns like Eloquent relationships).
• Non-Invasive: Since it’s a PHPStan extension, it integrates via configuration rather than modifying core Laravel logic, reducing architectural risk.

Integration Feasibility

• Low Coupling: The package doesn’t require Laravel-specific dependencies; it works at the PHPStan layer. Integration is as simple as adding it to PHPStan’s enabledRules in phpstan.neon.
• Laravel-Specific Rules: If the package includes Laravel-aware rules (e.g., for Eloquent, Blade, or service container patterns), it could be a high-value add. Otherwise, its utility may be limited to generic PHP improvements.
• Version Compatibility: PHPStan’s versioning is strict. The package must support the PHPStan version used in Laravel’s ecosystem (e.g., PHPStan 1.x for Laravel 10/11). Check for explicit Laravel compatibility or generic PHP 8.1+ support.

Technical Risk

• Rule Overlap: Potential conflicts with existing PHPStan rules (e.g., nunomaduro/phpstan-laravel) or custom in-house rules. Test for false positives/negatives early.
• Performance Impact: Custom rules may slow down analysis. Benchmark with a large Laravel codebase (e.g., 50K+ LOC) to ensure acceptable runtime.
• Maintenance Burden: If the package evolves rapidly or lacks backward compatibility, it may require frequent updates. Assess the maintainer’s activity (e.g., GitHub commits, issue responses).
• False Positives/Negatives: Generic rules may not account for Laravel’s dynamic features (e.g., magic methods, dynamic properties). Validate with real-world Laravel code.

Key Questions

1. Rule Relevance: Does the package include Laravel-specific rules (e.g., for Eloquent, Blade, or service container patterns), or is it purely generic PHP-focused?
2. PHPStan Version Support: Is it compatible with the PHPStan version used in your Laravel project (e.g., phpstan/phpstan:^1.10)?
3. Customization: Can rules be selectively enabled/disabled in phpstan.neon to avoid noise?
4. Performance: How does analysis time scale with Laravel’s codebase size? Are there optimizations for CI/CD pipelines?
5. Testing: Are there examples or tests demonstrating its effectiveness in a Laravel context?
6. Maintenance: What’s the package’s release cadence and deprecation policy?
7. Alternatives: Could existing tools (e.g., phpstan/extension-installer, vimeo/psalm) achieve similar goals with less risk?

Integration Approach

Stack Fit

• PHPStan Integration: The package is designed to work with PHPStan, which Laravel already uses (via nunomaduro/phpstan-laravel). No additional stack changes are needed.
• CI/CD Pipeline: Ideal for pre-commit hooks (e.g., via phpstan CLI) or CI pipelines (GitHub Actions, GitLab CI) to enforce rules early.
• IDE Support: Works with PHPStorm, VSCode (via PHPStan extension), or other IDEs that support PHPStan.

Migration Path

1. Add Dependency:

   composer require --dev korbeil/phpstan-generic-rules
   

2. Update PHPStan Config (phpstan.neon):

   includes:
       - vendor/korbeil/phpstan-generic-rules/extension.neon
   services:
       phpstan.genericRules:
           enabled: true
   

3. Selective Enforcement:
   • Start with a subset of rules (e.g., GenericCollectionRule) to avoid overwhelming the team.
   • Use level: 5 (or custom levels) to prioritize critical rules.
4. Validation:
   • Run locally: ./vendor/bin/phpstan analyse app
   • Integrate into CI to block failures.

Compatibility

• PHP Version: Ensure compatibility with Laravel’s PHP version (e.g., 8.1+ for Laravel 10/11).
• PHPStan Version: Verify the package supports the installed PHPStan version (e.g., phpstan/phpstan:^1.10).
• Laravel-Specific Edge Cases: Test with:
  • Dynamic properties (e.g., $model->{$relation}).
  • Magic methods (e.g., __call, __get).
  • Blade templates (if rules apply to compiled views).

Sequencing

1. Phase 1: Add package and enable non-breaking rules (e.g., generic type hints).
2. Phase 2: Introduce stricter rules (e.g., collection validation) and update code incrementally.
3. Phase 3: Integrate into CI/CD with gradual enforcement (e.g., warn → fail).
4. Phase 4: Customize rules or suppress false positives via phpstan.neon:

   rules:
       GenericCollectionRule:
           ignorePaths:
               - app/Helpers/legacy-helpers.php
   

Operational Impact

Maintenance

• Configuration Drift: Rules may need tuning over time (e.g., suppressing false positives). Document exceptions in phpstan.neon.
• Dependency Updates: Monitor for PHPStan major versions that break compatibility. Use composer require with --update-with-dependencies cautiously.
• Rule Deprecation: If the package drops rules, assess impact and migrate to alternatives (e.g., custom PHPStan rules).

Support

• Onboarding: Team members must understand PHPStan’s output and the new rules. Provide:
  • A CONTRIBUTING.md section on rule expectations.
  • Example fixes for common violations.
• Debugging: False positives may require:
  • Custom suppressions (@phpstan-ignore-next-line).
  • Reporting issues to the package maintainer.
• Tooling: Ensure IDEs are configured to show PHPStan errors inline (e.g., PHPStorm’s "Inspect Code" action).

Scaling

• Analysis Time: For large codebases (>100K LOC), consider:
  • Parallel analysis (PHPStan supports --parallel).
  • Incremental mode (if supported by the package).
  • CI caching (e.g., GitHub Actions actions/cache).
• Rule Performance: Complex rules (e.g., deep collection traversal) may slow down analysis. Profile with phpstan analyse --profile.

Failure Modes

• False Positives: Rules misfiring on Laravel-specific patterns (e.g., dynamic Eloquent accessors). Mitigate with:
  • Selective rule disabling.
  • Custom suppressions.
• CI Pipeline Failures: Blocking builds on legitimate but non-critical issues. Use:
  • Gradual enforcement (warn → fail).
  • Custom exit codes or --error-format=json for programmatic handling.
• Package Abandonment: If the package is unmaintained, migrate to:
  • Custom PHPStan rules.
  • Alternatives like psalm/plugin-laravel.

Ramp-Up

• Training:
  • 1-hour workshop on PHPStan basics and new rules.
  • Cheat sheet for common violations (e.g., "How to fix GenericCollectionRule errors").
• Pilot Group: Start with a small team/module (e.g., a single feature flag) to refine rules before full adoption.
• Metrics:
  • Track time to resolve violations (aim for <10 mins per fix).
  • Monitor CI pass rates post-integration.
• Feedback Loop: Gather input from developers to adjust rule severity or suppressions.