Phpstan Enum Laravel Package

Getting Started

Minimal Setup

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

   composer require --dev timeweb/phpstan-enum
   

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

   includes:
       - vendor/timeweb/phpstan-enum/extension.neon
   

3. First Use Case Define an enum in PHP 8.1+ (or backported via myclabs/php-enum):

   enum UserRole: string
   {
       case ADMIN = 'admin';
       case EDITOR = 'editor';
       case VIEWER = 'viewer';
   }
   

   Run PHPStan to validate enum usage:

   vendor/bin/phpstan analyse app
   

Implementation Patterns

Workflows

1. Strict Enum Validation Use ::class to enforce type safety in method parameters/returns:

   function setRole(UserRole $role): void { ... }
   

   PHPStan will flag invalid assignments like setRole('hacker').

2. Dynamic Enum Handling Leverage array_key_exists() checks with PHPStan’s @var:

   /** @var array<UserRole> */
   $roles = [UserRole::ADMIN, UserRole::EDITOR];
   if (array_key_exists('VIEWER', $roles)) { ... } // No warning
   

3. Backward Compatibility For PHP < 8.1, install myclabs/php-enum and configure PHPStan to recognize it:

   services:
       - Timeweb\PhpStanEnum\EnumExtension
   

Integration Tips

• Laravel Policies/Authorizers Validate enum-based permissions:

  public function authorize(User $user, UserRole $requiredRole): bool
  {
      return $user->role === $requiredRole;
  }
  

  PHPStan will catch mismatched roles.

• API Request Validation Use with spatie/laravel-data or symfony/validator:

  use Timeweb\PhpStanEnum\EnumValidator;
  
  $validator = new EnumValidator(UserRole::class);
  $validator->validate('invalid'); // Throws exception
  

• Database Migrations Enforce enum constraints in schema:

  Schema::table('users', function (Blueprint $table) {
      $table->string('role')->comment('UserRole enum');
  });
  

Gotchas and Tips

Pitfalls

1. False Positives with Dynamic Values PHPStan may flag valid dynamic enum assignments (e.g., from config). Suppress with:

   // @phpstan-ignore-next-line
   $role = config('app.role');
   

2. Backported Enum Limitations myclabs/php-enum lacks PHP 8.1’s reflection features. Use native enums where possible.

3. Case Sensitivity The extension treats enum names as case-sensitive. Avoid:

   UserRole::Admin // ❌ Fails (should be UserRole::ADMIN)
   

Debugging

• Extension Not Loading? Verify extension.neon is included in phpstan.neon and the package is in dev dependencies.

• Custom Enums Not Recognized Ensure enums extend BackedEnum (PHP 8.1) or myclabs/php-enum\Enum.

Tips

1. Custom Error Messages Configure PHPStan’s error format for enums:

   errorLevel: 5
   checkEnumUsage: true
   

2. Performance The extension adds minimal overhead. Disable for CI if speed is critical:

   vendor/bin/phpstan analyse --no-enum-checks
   

3. Extending Functionality Override the extension for custom logic:

   class CustomEnumExtension extends \Timeweb\PhpStanEnum\EnumExtension
   {
       public function getEnumValues(string $enumClass): array { ... }
   }
   

   Register in phpstan.neon:

   services:
       - CustomEnumExtension