Phpstan No Safe Laravel Package

Getting Started

Minimal Steps

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

   composer require --dev wyrihaximus/phpstan-no-safe
   

2. Configure PHPStan Ensure your phpstan.neon (or phpstan.neon.dist) includes the extension:

   includes:
       - vendor/wyrihaximus/phpstan-no-safe/extension.neon
   

3. First Use Case Run PHPStan with the extension to detect thecodingmachine/safe usage:

   vendor/bin/phpstan analyse app
   

   The tool will flag any classes or methods from thecodingmachine/safe (e.g., Safe\*, Safe::*), enforcing a strict "no-safe" policy.

Implementation Patterns

Workflows

1. Enforcing Zero-Tolerance for Safe Use this package to block thecodingmachine/safe entirely, aligning with projects where defensive programming via Safe is discouraged (e.g., strict type safety, performance-critical code, or teams preferring manual null checks).

2. Integration with CI/CD Add PHPStan with this extension to your CI pipeline to fail builds on Safe usage:

   # Example GitHub Actions step
   - name: PHPStan (No-Safe)
     run: vendor/bin/phpstan analyse --level=max app
   

3. Customizing Exceptions Override the extension’s rules in phpstan.neon to allow specific Safe usages (if needed):

   parameters:
       wyrihaximus/phpstan-no-safe:
           allowedClasses: ['Safe\Exceptions\SafeException']
           allowedFunctions: ['Safe\someFunction']
   

4. Pairing with Other Extensions Combine with phpstan/extension-installer for seamless dependency management:

   extends: phpstan/extension-installer.neon
   

Laravel-Specific Tips

• Service Container Checks Scan config/app.php or AppServiceProvider for Safe registrations:

  // Flagged: Avoid this
  $this->app->bind('Safe\Foo', function () { ... });
  

• Eloquent/Query Builder Use this to enforce no Safe wrappers around database operations (e.g., Safe\Db::select()).

Gotchas and Tips

Pitfalls

1. False Positives

   • The extension may flag third-party libraries using Safe internally (e.g., Safe\Arrays, Safe\Strings).
   • Fix: Whitelist them in phpstan.neon under allowedClasses or exclude vendor directories:

     excludeFiles: ['vendor/*/Safe/*']
     

2. Dynamic Class Loading

   • If Safe classes are loaded dynamically (e.g., via class_alias or eval), PHPStan may miss them.
   • Fix: Run PHPStan with --generate-report=html to debug missed cases.

3. IDE Integration

   • Some IDEs (e.g., PHPStorm) may not highlight Safe violations until PHPStan is fully configured.
   • Fix: Ensure your IDE uses the same phpstan.neon as your CLI.

Debugging

• Verbose Output Use --debug to trace rule application:

  vendor/bin/phpstan analyse --debug app
  

• Isolated Testing Test the extension on a single file:

  vendor/bin/phpstan analyse app/Http/Controllers/SomeController.php
  

Extension Points

1. Custom Rules Extend the extension by creating a custom PHPStan rule to handle edge cases:

   // Example: Allow Safe in tests only
   class AllowSafeInTestsRule extends Rule
   {
       public function getNodeType(): string { return 'Php\Node\Stmt\Namespace_'; }
       public function process(Node $node): array { ... }
   }
   

2. Configuration Inheritance Use extends in phpstan.neon to inherit rules from other configs:

   extends: ['vendor/wyrihaximus/phpstan-no-safe/extension.neon', 'custom-rules.neon']
   

3. Performance

   • For large codebases, cache PHPStan results to avoid reprocessing:

     vendor/bin/phpstan analyse --memory-limit=1G --cache-result