Phpstan Disallowed Calls Laravel Package

Technical Evaluation

Architecture Fit

• Static Analysis Tooling: The package integrates seamlessly with PHPStan, a widely adopted static analysis tool for PHP. It extends PHPStan’s rule engine to enforce custom disallowed patterns (e.g., deprecated APIs, internal methods, or security-sensitive functions) without modifying runtime behavior.
• Decoupled Enforcement: Rules are declarative (via neon/php config) and non-intrusive, making them ideal for enforcing coding standards, security policies, or legacy migration constraints in Laravel applications.
• Laravel-Specific Use Cases:
  • Blocking deprecated Laravel core methods (e.g., Request::oldInput() → Request::old()).
  • Restricting direct database calls (e.g., DB::select()) in favor of Eloquent.
  • Enforcing service container best practices (e.g., disallowing new for bound dependencies).

Integration Feasibility

• Low Friction: PHPStan is already a dependency in many Laravel projects (via phpstan/extension-installer). This package adds no new runtime overhead.
• Configuration Override: Rules can be scoped to specific namespaces (e.g., App\Services\*) or files, allowing granular control.
• CI/CD Readiness: Outputs are compatible with PHPStan’s error formats (e.g., GitHub Actions, SonarQube).

Technical Risk

• False Positives/Negatives: Custom rules may require tuning to avoid over-restrictive or permissive configurations. Example: Disallowing str_replace() globally might break legacy code.
• PHPStan Version Lock: The package may lag behind PHPStan’s latest features (e.g., PHP 8.3+ attributes). Test compatibility with your PHPStan version.
• Toolchain Dependency: Requires PHPStan to be configured and maintained as part of the project’s static analysis pipeline.

Key Questions

1. Rule Granularity: How will disallowed patterns be defined (e.g., project-wide vs. team-specific)?
2. Migration Path: Are there deprecated APIs in the codebase that need phased removal?
3. CI/CD Integration: Will violations block merges, or are they treated as warnings?
4. Performance Impact: Will running PHPStan with these rules add significant build time?
5. Team Adoption: How will developers handle exceptions (e.g., @allow-disallowed-call annotations)?

Integration Approach

Stack Fit

• PHPStan Ecosystem: Works natively with:
  • phpstan/extension-installer (auto-loads rules).
  • phpstan/phpstan (core static analysis).
  • phpstan/phpstan-laravel (Laravel-specific rules).
• Laravel-Specific Synergies:
  • Pair with laravel-pint for consistent code formatting alongside rule enforcement.
  • Combine with roave/security-advisories to block vulnerable dependencies.
• Tooling Compatibility:
  • IDE plugins (PHPStorm, VSCode) support PHPStan’s error output.
  • Integrates with rector/rector for automated refactoring of disallowed calls.

Migration Path

1. Pilot Phase:
   • Start with a small subset of rules (e.g., disallow new for service container bindings).
   • Use --level=max in PHPStan to identify existing violations.
2. Incremental Rollout:
   • Add rules in phases (e.g., security-sensitive functions first).
   • Use @allow-disallowed-call sparingly for legacy code.
3. Automated Fixes:
   • Leverage Rector to auto-refactor simple violations (e.g., Request::oldInput() → Request::old()).
4. Configuration Management:
   • Store rules in phpstan.neon with clear comments:

     includes:
       - vendor/spaze/phpstan-disallowed-calls/extension.neon
     disallowedCalls:
       'Illuminate\Support\Facades\DB::select':
         message: 'Use Eloquent queries instead.'
     

Compatibility

• PHPStan Version: Test with your project’s PHPStan version (e.g., ^1.10.0). Check the package’s upgrade notes if available.
• Laravel Version: No direct dependency, but rules may reference Laravel classes (e.g., Illuminate\*). Ensure rules align with your Laravel version’s APIs.
• Custom Code: Rules can target third-party libraries (e.g., disallow Carbon::parse() in favor of Carbon::createFromFormat()).

Sequencing

1. Setup:
   • Install via Composer: composer require --dev spaze/phpstan-disallowed-calls.
   • Configure PHPStan to include the extension.
2. Validation:
   • Run PHPStan locally and in CI to baseline violations.
3. Refinement:
   • Adjust rules based on false positives/negatives.
4. Enforcement:
   • Integrate with PR checks (e.g., GitHub Actions) to block violations.

Operational Impact

Maintenance

• Rule Updates: Monitor the package for new rule additions (e.g., Laravel 11 deprecations). Update rules proactively.
• Configuration Drift: Document allowed exceptions (e.g., @allow-disallowed-call) in a RULES.md file.
• Dependency Management: Pin PHPStan and this package to specific versions to avoid breaking changes.

Support

• Developer Onboarding:
  • Provide a cheat sheet for common @allow-disallowed-call use cases.
  • Example:

    // Allowed in tests only
    #[\Spaze\DisallowedCalls\AllowedInTests]
    public function testDeprecatedMethod() { ... }
    

• Troubleshooting:
  • Teach teams to use --error-format=github for actionable PR feedback.
  • Example GitHub Actions step:

    - name: PHPStan
      run: vendor/bin/phpstan analyse --level=max
    

Scaling

• Performance:
  • PHPStan’s static analysis is CPU-intensive. Cache results in CI (e.g., phpstan --generate-baseline).
  • For large codebases, parallelize analysis with phpstan --parallel.
• Rule Scoping:
  • Use path: or namespace: filters to limit rule application to critical paths (e.g., App\*).
  • Example:

    disallowedCalls:
      'App\Services\*':
        'Symfony\Component\HttpFoundation\Request::getClientIp':
          message: 'Use $request->ip() instead.'
    

Failure Modes

• False Positives:
  • Mitigation: Start with permissive rules and tighten iteratively. Use @allow-disallowed-call for edge cases.
• Toolchain Breakage:
  • Risk: PHPStan major version updates may break rule syntax.
  • Mitigation: Test upgrades in a staging environment.
• Developer Resistance:
  • Risk: Overly restrictive rules may slow development.
  • Mitigation: Frame rules as "guidelines" with opt-outs for critical paths.

Ramp-Up

• Training:
  • Conduct a workshop on PHPStan’s error output and rule customization.
  • Highlight success stories (e.g., "We removed 500 DB::select() calls in 2 weeks").
• Metrics:
  • Track violations over time to demonstrate impact (e.g., "Reduced deprecated API usage by 30%").
• Phased Enforcement:
  • Start with warnings, then transition to errors after a grace period (e.g., 3 months).