Phpstan Banned Code Laravel Package

Technical Evaluation

Architecture Fit

• Seamless PHPStan Integration: Designed as a PHPStan extension, it leverages the existing static analysis pipeline without disrupting Laravel’s architecture. Works alongside other PHPStan rules (e.g., phpstan/laravel, phpstan/phpunit) via NEON configuration, enabling modular rule composition.
• AST-Based Detection: Uses PHPStan’s Abstract Syntax Tree (AST) to identify banned constructs (e.g., Expr_FuncCall, Stmt_Echo), aligning with Laravel’s compiler-first approach (e.g., Blade templates, service containers).
• Laravel-Specific Synergy:
  • Blocks debug helpers (dd(), dump()) that plague Laravel’s debug mode and Tinker.
  • Detects unsafe patterns like file_get_contents on sensitive paths (e.g., /config/, /storage/) via custom function lists.
  • Supports namespace-based rules (e.g., ban use Tests\* in non-test files) to enforce Laravel’s separation of concerns.
• Compliance Alignment: Maps to Laravel’s security best practices (e.g., Laravel Security Checklist) and OWASP Top 10 (e.g., injection prevention via shell_exec bans).

Integration Feasibility

• Low Friction Setup:
  • Option 1: Auto-install via phpstan/extension-installer (recommended for Laravel projects using PHPStan).
  • Option 2: Manual NEON config inclusion (2 lines in phpstan.neon).
  • No Laravel-Specific Hooks: Works at the PHP level, avoiding Laravel’s service provider or facade dependencies.
• Dependency Compatibility:
  • PHP 8.1+ Required: Aligns with Laravel’s PHP 8.1+ support (LTS since v9.x). No conflicts with Laravel’s core dependencies.
  • PHPStan 2.x+: Compatible with Laravel’s PHPStan integration (e.g., phpstan/laravel package).
  • Composer Dev Dependency: Isolates to CI/dev environments, avoiding runtime overhead.
• Configuration Override: Supports project-specific bans (e.g., add Artisan::call() to banned functions for CLI-only projects).

Technical Risk

Key Questions for the TPM

1. Rule Prioritization:

   • Should we start with security-critical bans (e.g., eval, shell_exec) or debug-related bans (e.g., dd(), var_dump)?
   • Example: Ban exec, passthru, and system in Phase 1, then add dd()/dump() in Phase 2.

2. CI/CD Strategy:

   • Should banned code fail builds immediately, or warn first with a baseline?
   • Example: Use non_ignorable: true for security bans, false for debug bans.

3. Laravel-Specific Extensions:

   • Should we customize banned functions for Laravel (e.g., Artisan::call(), Blade @debug)?
   • Example: Add Artisan::call('migrate') to banned functions for production builds.

4. Team Adoption:

   • How will we educate developers on the new rules (e.g., training, IDE plugins like PHPStan’s VS Code extension)?
   • Example: Create a Slack channel for banned-code exceptions and a wiki page with allowed alternatives (e.g., Log::debug() instead of var_dump).

5. Scaling:

   • How will we handle large codebases (e.g., 100K+ LOC) or monorepos?
   • Example: Run PHPStan in parallel using phpstan --parallel and cache results with phpstan --cache-results.

6. False Positive Handling:

   • What’s the process for whitelisting exceptions (e.g., var_dump in a debug-only CLI command)?
   • Example: Use // @phpstan-ignore-next-line sparingly, with code review approval for each case.

7. Auditability:

   • Should we track banned-code violations in a dashboard (e.g., GitHub Insights, custom script)?
   • Example: Parse PHPStan output to generate a monthly report of debug/function bans.

8. Dependency Updates:

   • How will we keep banned lists updated (e.g., new PHP functions, OWASP recommendations)?
   • Example: Schedule quarterly reviews of banned functions using composer why-not and phpstan diagnose.

Integration Approach

Stack Fit

• PHPStan Ecosystem: Native integration with PHPStan 2.x+, which Laravel projects using phpstan/laravel or phpstan/phpunit already leverage. No conflicts with:
  • Laravel’s PHPStan presets (e.g., phpstan/laravel for framework-specific rules).
  • Other PHPStan extensions (e.g., phpstan/doctrine, phpstan/symfony).
• Laravel-Specific Synergies:
  • Debug Mode: Blocks dd(), dump(), and exit() in production builds, aligning with Laravel’s APP_DEBUG=false best practice.
  • Artisan Commands: Can ban Artisan::call() in non-CLI contexts (e.g., web routes).
  • Blade Templates: Detects {{ dd($var) }} or @debug directives via custom rules (if extended).
• CI/CD Tools:
  • GitHub Actions/GitLab CI: Integrates via phpstan/extension-installer or custom scripts.
  • Composer Scripts: Add to composer.json:

    "scripts": {
      "test": "phpstan analyze --level=max --memory-limit=1G"
    }
    

  • Parallel Testing: Use phpstan --parallel for large codebases (e.g., 50K+ LOC).

Migration Path