Fakerstan Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require --dev calebdw/fakerstan --with-all-dependencies
   

   Ensure phpstan/extension-installer is also installed to auto-load the extension.

2. Configuration: Add to your phpstan.neon:

   includes:
       - vendor/calebdw/fakerstan/extension.neon
   

3. First Use Case: Run PHPStan on a file using Faker (e.g., tests/Unit/UserFactoryTest.php):

   phpstan analyse tests/Unit --level=5
   

   The extension will now validate Faker method calls (e.g., fake()->name()) for type correctness.

Implementation Patterns

Workflows

1. Type-Safe Faker Usage: Use Faker methods with IDE autocompletion and PHPStan validation:

   $user = User::factory()->create([
       'name' => fake()->name(), // Validated as string
       'email' => fake()->unique()->email(), // Validated as string
   ]);
   

2. Custom Faker Rules: Extend Faker’s rules in phpstan.neon:

   parameters:
       fakerstan:
           rules:
               - method: 'fake()->safeEmail()'
                 returnType: 'string'
   

3. Integration with Factories: Validate factory traits or custom factories:

   // tests/Unit/UserFactory.php
   use FakerStan\FakerStan;
   
   class UserFactory extends Factory
   {
       use FakerStan; // Auto-validates Faker calls
   }
   

4. Dynamic Rules: Use phpstan.neon to override return types for dynamic Faker calls:

   parameters:
       fakerstan:
           dynamicRules:
               - pattern: 'fake()->creditCardNumber()'
                 returnType: 'string'
   

Integration Tips

• Laravel Testing: Pair with pestphp/pest or phpunit/phpunit for seamless validation in test suites.
• CI/CD: Add PHPStan with FakerStan to your CI pipeline to catch type issues early.
• Custom Providers: Extend Faker’s providers and update phpstan.neon to reflect new methods:

  parameters:
      fakerstan:
          providers:
              - 'App\Providers\CustomFakerProvider'
  

Gotchas and Tips

Pitfalls

1. False Positives:

   • FakerStan may flag dynamic Faker calls (e.g., fake()->method($arg)) as untyped. Use dynamicRules to whitelist them.
   • Fix: Add to phpstan.neon:

     parameters:
         fakerstan:
             ignoreDynamicMethods: true
     

2. Provider Conflicts:

   • If Faker providers are loaded after FakerStan, rules may not apply. Ensure providers are registered early (e.g., in AppServiceProvider).
   • Fix: Use Faker::extend() before running PHPStan.

3. Nested Faker Calls:

   • Chained methods (e.g., fake()->domainName()->email()) may not resolve types correctly.
   • Fix: Break into separate lines or use dynamicRules:

     parameters:
         fakerstan:
             dynamicRules:
                 - pattern: 'fake()->domainName()->email()'
                   returnType: 'string'
     

Debugging

• Verbose Output: Run PHPStan with --verbose to see FakerStan’s parsed rules.
• Rule Overrides: Temporarily disable FakerStan to isolate issues:

  includes:
      - vendor/calebdw/fakerstan/extension.neon
  # Disable for testing:
  # includes: []
  

Extension Points

1. Custom Return Types: Override return types for non-standard Faker methods via phpstan.neon:

   parameters:
       fakerstan:
           rules:
               - method: 'fake()->customMethod()'
                 returnType: 'App\Models\User'
   

2. Plugin System: Use FakerStan\Extension\ExtensionInterface to create custom extensions for organization-specific Faker logic.

3. Performance: Exclude large test files from FakerStan checks if performance is critical:

   excludes:
       - tests/Feature/LargeTestSuite.php