Phpstan Banned Code Laravel Package

Getting Started

Minimal Setup

1. Install the package in your Laravel project:

   composer require --dev ekino/phpstan-banned-code
   

2. Enable the extension via PHPStan’s extension-installer (recommended):

   composer require --dev phpstan/extension-installer
   

   Or manually include the config in your phpstan.neon:

   includes:
       - vendor/ekino/phpstan-banned-code/extension.neon
   

3. Run PHPStan to detect banned code:

   vendor/bin/phpstan analyse
   

First Use Case: Block Debug Leaks

Configure phpstan.neon to ban common debug functions:

parameters:
    banned_code:
        nodes:
            - type: Expr_FuncCall
              functions:
                  - var_dump
                  - dd
                  - dump
                  - exit
                  - die

Implementation Patterns

Workflow: CI/CD Integration

1. Add to CI Pipeline (GitHub Actions example):

   - name: PHPStan Banned Code Check
     run: vendor/bin/phpstan analyse --level=max --error-format=github
   

2. Fail builds on banned code detection (default behavior with non_ignorable: true).

Pattern: Team-Wide Enforcement

• Standardize rules in a shared phpstan.neon config (e.g., config/phpstan.neon).
• Extend for custom functions:

  parameters:
      banned_code:
          nodes:
              - type: Expr_FuncCall
                functions:
                    - customDebugHelper
                    - internalDebugTool
  

Pattern: Test-Specific Rules

• Prevent use Tests\* in non-test files:

  parameters:
      banned_code:
          use_from_tests: true
  

Pattern: Gradual Adoption

1. Start with non-ignorable mode (non_ignorable: true) to catch critical issues.
2. Gradually whitelist exceptions for legacy code:

   parameters:
       banned_code:
           nodes:
               - type: Expr_FuncCall
                 functions:
                     - var_dump  # Temporarily allowed
   

Gotchas and Tips

Pitfalls

1. False Positives in Legacy Code:
   • Use non_ignorable: false temporarily to baseline existing issues.
   • Example: Legacy mysql_* functions may trigger false alarms.
2. Closure/Anonymous Function Edge Cases:
   • The package skips banned checks in closures by default (avoids Variable node conflicts).
3. NEON Syntax Errors:
   • Validate config with vendor/bin/phpstan analyse --generate-baseline before enforcing.

Debugging Tips

• Inspect AST Nodes: Use phpstan debug:container to verify node types (e.g., Stmt_Echo).
• Isolate Rules: Test one banned function at a time to narrow down issues.
• Check for Typos: Function names in functions: are case-sensitive (e.g., VarDump ≠ var_dump).

Extension Points

1. Custom AST Nodes: Extend BannedNodesRule to support new node types (e.g., Stmt_Throw for banned exceptions).
2. Dynamic Bans: Use PHPStan’s parameters to load banned functions from a config file or environment variable.
3. Integration with Laravel:
   • Hook into booted event to auto-configure PHPStan for banned code checks.
   • Example:

     // app/Providers/AppServiceProvider.php
     public function boot()
     {
         if (app()->environment('production')) {
             $this->configureBannedCodeRules();
         }
     }
     

Performance Quirks

• Large Codebases: Disable use_from_tests if test files are excluded from analysis.
• Parallel Analysis: Use --parallel flag to speed up scans in monorepos.

Laravel-Specific Tips

• Debug Mode Integration: Combine with APP_DEBUG=false in production to enforce zero-debug rules.
• Service Provider Bans: Ban dd() in AppServiceProvider constructors to prevent accidental debug leaks:

  parameters:
      banned_code:
          nodes:
              - type: Expr_FuncCall
                functions:
                    - dd
                file_patterns:
                    - "app/Providers/AppServiceProvider.php"