Phpstan Safe Rule Laravel Package

Technical Evaluation

Architecture fit

• Pros: Seamlessly integrates with PHPStan, a widely adopted static analysis tool in Laravel ecosystems. Leverages existing CI/CD pipelines without architectural disruption. Aligns with Laravel’s PHP-centric stack (PHP 8.1+) and modern PHPStan (v2+) adoption.
• Cons: Requires prior PHPStan adoption; not a standalone solution. Tight coupling with thecodingmachine/safe may limit flexibility if alternative null-safety strategies (e.g., custom wrappers) are preferred.
• Laravel-specific: Compatible with Laravel’s dependency injection and service container patterns, but rules may conflict with Laravel’s built-in type hints (e.g., Illuminate\Support\Collection methods). Test for false positives in Laravel-specific code (e.g., Eloquent queries, Blade templates).

Integration feasibility

• Low effort: Composer install + phpstan.neon configuration (1–2 lines). No runtime dependencies or Laravel service provider required.
• Dependencies:
  • Hard: PHPStan ≥2.0, PHP ≥8.1 (enforced by package).
  • Soft: thecodingmachine/safe (v1.2+ recommended). If not already used, requires parallel adoption.
• Laravel compatibility: No direct conflicts, but:
  • Rules may flag Laravel’s internal unsafe calls (e.g., str_* functions in helpers). Use ignoreErrors to exclude vendor/Laravel code.
  • Blade templates (compiled to PHP) will be analyzed, potentially surfacing edge cases (e.g., @php $var ?? 'default').

Technical risk

• False positives/negatives:
  • High risk: Rules like preg_match type inference or JSON_THROW_ON_ERROR may misclassify Laravel-specific use cases (e.g., JSON API responses).
  • Mitigation: Start with level: 1 (weak) and whitelist known false positives in phpstan.neon.
• Maintenance:
  • Low: Pure static analysis; no runtime impact. However, requires PHPStan updates (e.g., PHPStan 3.x may break compatibility).
  • Dependency risk: thecodingmachine/safe is actively maintained, but phpstan-safe-rule has low stars (62) and no Laravel-specific tests. Validate against Laravel’s codebase before full adoption.
• Performance: Negligible overhead (~1–5% slower than baseline PHPStan). May impact large codebases (>1M LOC) during CI runs.

Key questions

1. Adoption readiness:
   • Is PHPStan already integrated into CI/CD? If not, what’s the migration path?
   • Does the team use thecodingmachine/safe, or will this require parallel adoption?
2. Laravel-specific risks:
   • Are there false positives in Laravel’s core (e.g., Str::* helpers, Eloquent)?
   • How will Blade templates handle @phpstan-ignore-line annotations?
3. Long-term viability:
   • What’s the fallback if phpstan-safe-rule stagnates (last release: 2026-06-23)?
   • Are there Laravel-specific alternatives (e.g., custom PHPStan rules)?
4. Team buy-in:
   • Will developers accept static analysis as a "blocker" in PRs, or prefer runtime checks (e.g., try-catch)?

Integration Approach

Stack fit

• PHPStan ecosystem: Native support for PHPStan 2.0+ (Laravel’s default is often 1.x; upgrade required).
• Laravel compatibility:
  • Pros: No Laravel-specific changes needed. Works with:
    • Laravel’s PHP 8.1+ baseline.
    • Composer autoloading (no manual classmap tweaks).
  • Cons:
    • May conflict with Laravel’s return_type declarations (e.g., Collection::pluck()).
    • Blade templates require explicit @phpstan-ignore-line for dynamic code.
• Toolchain:
  • CI/CD: Integrates with GitHub Actions/GitLab CI via phpstan analyse (exit code 1 on errors).
  • IDE: Supports PHPStorm/VSCode via PHPStan’s built-in IDE plugins.

Migration path

1. Phase 1: Evaluation
   • Install in a dev container:

     composer require --dev thecodingmachine/phpstan-safe-rule thecodingmachine/safe
     

   • Configure phpstan.neon minimally:

     includes:
         - vendor/thecodingmachine/phpstan-safe-rule/extension.neon
     level: 1  # Start with weak checks
     ignoreErrors:
         - '#.*vendor/laravel.*#'  # Exclude Laravel core
     

   • Run against a subset (e.g., app/Http/Controllers):

     phpstan analyse --memory-limit=1G app/Http
     

2. Phase 2: Pilot
   • Enable for new code only:

     paths:
         - app/Http/NewFeature
     

   • Fix critical errors (e.g., strlen(null)), suppress others with @phpstan-ignore-line.
3. Phase 3: Full adoption
   • Expand to all paths, tighten level to 5 (max).
   • Add to CI as a required check (fail PRs on errors).

Compatibility

• PHPStan versions: Tested with 2.0+ (Laravel’s default may lag; pin version in composer.json).
• Laravel versions: No hard conflicts, but validate with:
  • Laravel 10.x (PHP 8.1+).
  • Custom packages using unsafe functions (e.g., file_get_contents).
• Dependencies:
  • thecodingmachine/safe v1.2+ (required for rule suggestions).
  • PHP 8.1+ (enforced by package).

Sequencing

1. Prerequisite: Upgrade PHPStan to ≥2.0 if using an older version.
2. Parallel: Adopt thecodingmachine/safe incrementally (e.g., replace file_get_contents with Safe\file_get_contents).
3. Post-integration:
   • Audit false positives in Laravel-specific code.
   • Extend rules for custom domain logic (e.g., @phpstan-ignore-next-line for known edge cases).

Operational Impact

Maintenance

• Effort: Low to moderate.
  • Proactive: Update PHPStan and phpstan-safe-rule annually (check changelogs for breaking changes).
  • Reactive: Suppress false positives in phpstan.neon as they arise (e.g., for Laravel’s Str::* helpers).
• Ownership:
  • Assign a tech lead to curate ignoreErrors and rule exclusions.
  • Document suppressed rules in a PHPSTAN_RULES.md file.

Support

• Debugging:
  • Use phpstan debug to isolate rule-specific issues.
  • Check thecodingmachine/safe docs for edge cases (e.g., Safe\json_decode with JSON_THROW_ON_ERROR).
• Team training:
  • Educate developers on:
    • Reading PHPStan error messages (e.g., Unsafe function call: strlen()).
    • Using @phpstan-ignore-line judiciously.
  • Provide a cheat sheet for common fixes (e.g., replacing array_key_exists with Safe\array_key_exists).

Scaling

• Performance:
  • Small/medium projects: Negligible impact (~5–10% slower than baseline PHPStan).
  • Large projects: Optimize with:
    • Parallel analysis (phpstan analyse --parallel).
    • Incremental mode (--generate-baseline).
  • CI: Cache PHPStan results between runs (e.g., GitHub Actions actions/cache).
• Codebase growth:
  • Rules scale linearly with code size. Monitor CI runtime; split analysis by directory if >10s.

Failure modes

Ramp-up

• Onboarding time: 1–2 weeks for team adoption (longer for large teams).
  • Week 1: Install, configure, and run against a subset of code.
  • Week 2: Fix critical errors; document suppression patterns.
• Key metrics:
  • Success: Reduction in runtime null-related bugs (track via Sentry/Error Tracking).
  • Failure: >10% of