Phpstan Banned Code Laravel Package

Technical Evaluation

Architecture Fit

• Seamless PHPStan Integration: Designed as a PHPStan extension, it leverages the existing static analysis infrastructure in Laravel projects already using PHPStan (common in modern Laravel ecosystems). No architectural disruption; fits into the phpstan.neon configuration paradigm.
• AST-Based Detection: Uses Abstract Syntax Tree (AST) analysis to identify banned nodes/functions, aligning with PHPStan’s core methodology. Avoids runtime overhead by operating at compile-time.
• Laravel Synergy: Targets Laravel-specific pain points (e.g., dd(), dump(), exit() in controllers/middleware) and integrates with Laravel’s debug mode (APP_DEBUG) for context-aware enforcement.
• Modular Configuration: Supports granular rule customization (e.g., banning echo in loops but allowing print in CLI scripts), enabling alignment with team-specific coding standards.

Integration Feasibility

• Low Friction: Requires zero Laravel core changes; works as a dev dependency with minimal setup (Composer + PHPStan config).
• CI/CD Ready: Designed for GitHub Actions/GitLab CI with fail-fast capabilities (e.g., blocking merges if banned code is detected).
• Backward Compatibility: Supports PHP 8.0–8.4 and PHPStan 1.x/2.x, ensuring compatibility with modern Laravel (v9+) and legacy systems.
• Toolchain Alignment: Works alongside Laravel Forge, Envoyer, and Laravel Vapor for production-grade enforcement.

Technical Risk

Key Questions for TPM

1. PHPStan Adoption: Is PHPStan already used in the project, or will this require new tooling investment? If not, assess ROI vs. alternatives (e.g., custom scripts, Psalm).
2. Banned Code Scope: Should rules be project-wide or environment-specific (e.g., stricter in production vs. staging)? Requires .neon configuration per environment.
3. Exception Handling: How will legitimate use cases (e.g., dd() in CLI tools) be handled? Options:
   • File-level whitelisting (e.g., /* @phpstan-ignore-next-line */).
   • Directory-based rules (e.g., allow dd() in tests/ but ban in app/).
4. CI/CD Integration: Where in the pipeline should this run? Options:
   • Pre-merge (strict, blocks PRs).
   • Post-merge, pre-deploy (less disruptive but risks production leaks).
5. Legacy Code: How will existing banned code (e.g., var_dump in 10K+ LOC) be handled? Options:
   • Gradual enforcement with non_ignorable: false + baseline.
   • Automated refactoring (e.g., sed/Rector to replace echo with response()->json()).
6. Team Buy-In: Will developers resist static analysis? Mitigate with:
   • Onboarding workshops on PHPStan/AST concepts.
   • Gamification (e.g., leaderboards for "cleanest PRs").
7. Maintenance: Who will update banned lists (e.g., adding laravel-debugbar functions)? Assign a tech lead or use community-maintained configs (e.g., phpstan-preset).

Integration Approach

Stack Fit

• PHPStan-Centric: Ideal for projects using PHPStan (or planning to adopt it). If not, evaluate:
  • Psalm: Alternative static analyzer with similar extensibility.
  • PHP-CS-Fixer: For code style (not AST-based detection).
  • Custom Scripts: Using nikic/PHP-Parser for bespoke rules (higher maintenance).
• Laravel Ecosystem: Optimized for Laravel’s debug helpers (dd(), dump()), middleware, and CLI tools. Works alongside:
  • Laravel Pint (for code style).
  • Laravel Telescope (for runtime debugging, not banned by default).
• CI/CD Tools: Native support for:
  • GitHub Actions (via phpstan/extension-installer).
  • GitLab CI (custom script to run PHPStan).
  • CircleCI/Bitbucket Pipelines (Composer-based execution).

Migration Path

1. Assessment Phase (1–2 weeks):
   • Audit existing code for banned patterns (e.g., grep -r "var_dump\|dd\|exec").
   • Identify high-risk areas (e.g., legacy controllers, CLI scripts).
2. Pilot Phase (2–4 weeks):
   • Add to a single repository (e.g., monorepo or high-risk service).
   • Configure .neon with minimal rules (e.g., ban var_dump, exit).
   • Run in CI as a "soft fail" (warnings only) to gather data.
3. Rollout Phase (4–8 weeks):
   • Expand to all repositories with strict mode (non_ignorable: true).
   • Integrate with code owners to resolve violations.
   • Add to onboarding docs for new developers.
4. Optimization Phase (Ongoing):
   • Refine .neon based on false positives.
   • Automate whitelisting for CLI/tools.
   • Monitor incident reduction (e.g., fewer dd()-related bugs).

Compatibility

Sequencing

1. Prerequisite: Ensure PHPStan is installed (composer require --dev phpstan/phpstan).
2. Install Package:

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

3. Configure PHPStan:
   • Option A (Recommended): Use phpstan/extension-installer (auto-configures).
   • Option B: Add to phpstan.neon:

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

4. Customize Rules:
   • Edit extension.neon or override in project’s phpstan.neon:

     parameters:
       banned_code:
         nodes:
           - { type: Expr_FuncCall, functions: ["dd", "