Phpstan Disallowed Calls Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer in your Laravel project:

   composer require --dev spaze/phpstan-disallowed-calls
   

2. Configure PHPStan Extend your phpstan.neon configuration to include the extension:

   includes:
       - vendor/spaze/phpstan-disallowed-calls/extension.neon
   

3. Define Disallowed Rules Create a disallowed-calls.neon file in your project root (or extend the config):

   parameters:
       disallowedCalls:
           functions:
               - 'dd'
               - 'dump'
               - 'abort'
           methods:
               - 'App\Models\User!methodThatShouldNotBeUsed()'
           constants:
               - 'App\Constants!SENSITIVE_CONSTANT'
   

4. First Use Case Run PHPStan to catch violations:

   vendor/bin/phpstan analyse
   

   The tool will flag disallowed calls (e.g., dd() or deprecated methods) in your Laravel app.

Implementation Patterns

Workflow Integration

1. Team Onboarding

   • Document disallowed rules in README.md or CONTRIBUTING.md (e.g., "Never use dd() in production").
   • Use disallowed-calls.neon as a living standard for code quality.

2. Laravel-Specific Rules

   • Disallow dd() in Controllers/Commands:

     parameters:
         disallowedCalls:
             functions:
                 - 'dd'
             allowIn:
                 - 'tests/**'
     

   • Block Deprecated Eloquent Methods:

     parameters:
         disallowedCalls:
             methods:
                 - 'App\Models\Model!fireModelEvent(string $event)'
     

3. Conditional Allowances

   • Whitelist calls in tests or specific files:

     parameters:
         disallowedCalls:
             functions:
                 - 'dd'
             allowIn:
                 - 'tests/Feature/**'
     

4. Dynamic Rules via Environment

   • Use PHPStan’s parameters to toggle rules per environment (e.g., allow dd() in local but not production):

     parameters:
         disallowedCalls:
             functions:
                 - 'dd'
             allowIn:
                 - '%env(APP_ENV) == "local" ? "app/Http/Controllers/**" : null'
     

5. Integration with CI

   • Fail builds on disallowed calls:

     # .github/workflows/phpstan.yml
     - name: PHPStan
       run: vendor/bin/phpstan analyse --level=max --error-format=github
     

Gotchas and Tips

Pitfalls

1. Overly Broad Rules

   • Avoid banning entire namespaces (e.g., Illuminate\Support\Facades\Log). Instead, target specific methods:

     # Bad: Blocks all Log facade calls
     parameters:
         disallowedCalls:
             namespaces:
                 - 'Illuminate\Support\Facades\Log'
     
     # Good: Blocks only emergency()
     parameters:
         disallowedCalls:
             methods:
                 - 'Illuminate\Support\Facades\Log!emergency(string $message)'
     

2. False Positives in Generics

   • PHPStan may flag generic method calls (e.g., Model::find()). Use ! to exclude:

     parameters:
         disallowedCalls:
             methods:
                 - '!App\Models\Model!find(int|string $id)'  # Allows find()
     

3. Performance Impact

   • Disabling PHPStan’s level: max for large codebases may reduce runtime but miss violations. Use selectively:

     vendor/bin/phpstan analyse app/Http --level=5
     

4. Dynamic Class Names

   • Rules like App\Models\User!method() fail if the class is loaded dynamically (e.g., via new $className). Use regex or avoid dynamic disallowances.

5. Attribute/Keyword Conflicts

   • Disallowing keywords (e.g., global) may break legacy code. Test thoroughly:

     parameters:
         disallowedKeywords:
             - 'global'
     

Debugging Tips

1. Inspect Violations Use --error-format=json to parse violations programmatically:

   vendor/bin/phpstan analyse --error-format=json > violations.json
   

2. Temporarily Disable Rules Comment out rules in disallowed-calls.neon to isolate issues:

   # parameters:
   #     disallowedCalls:
   #         functions:
   #             - 'dd'
   

3. Leverage PHPStan’s CLI Help List available rules:

   vendor/bin/phpstan diagnose
   

Extension Points

1. Custom Rules Extend the package by creating a custom PHPStan rule (e.g., for Laravel-specific disallowances):

   // app/Rules/DisallowFactoryCallsRule.php
   use PHPStan\Rules\Rule;
   use Spaze\DisallowedCalls\DisallowedCallsChecker;
   
   class DisallowFactoryCallsRule implements Rule {
       public function getNodeTypeNames(): array {
           return [MethodCall::class];
       }
   
       public function processNode(Node $node, Scope $scope): array {
           if ($node instanceof MethodCall && $node->getMethodName() === 'factory') {
               return [new Error('Factory calls are disallowed.', $node)];
           }
           return [];
       }
   }
   

2. Combine with Other Tools

   • Use alongside phpstan/extension-installer for zero-config setups:

     composer require --dev phpstan/extension-installer
     

   • Integrate with roave/security-advisories to block vulnerable calls.

3. Visual Studio Code Integration Add to .vscode/settings.json for real-time feedback:

   {
       "phpstan.executablePath": "vendor/bin/phpstan",
       "phpstan.neon": "./phpstan.neon",
       "phpstan.enable": true
   }
   

4. Git Hooks Auto-fix or block commits with disallowed calls:

   composer require --dev laravel/git-hooks
   

   Then configure in git-hooks.php:

   $hook->add('pre-commit', 'vendor/bin/phpstan analyse --no-progress-bar --error-format=checkstyle | grep -q "ERROR" && exit 1');