Enum Helper Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require oskarstark/enum-helper
   

2. First Use Case: Create an enum with the Comparable and ToArray traits:

   // app/Enums/UserRole.php
   namespace App\Enums;
   
   use OskarStark\Enum\Trait\Comparable;
   use OskarStark\Enum\Trait\ToArray;
   
   enum UserRole: string
   {
       use Comparable, ToArray;
   
       case ADMIN = 'admin';
       case EDITOR = 'editor';
       case VIEWER = 'viewer';
   }
   

3. Basic Usage:

   // Compare enums
   UserRole::ADMIN->equals(UserRole::EDITOR); // false
   
   // Convert to array
   UserRole::toArray(); // ['ADMIN' => 'admin', 'EDITOR' => 'editor', ...]
   

Where to Look First

• Traits: Focus on Comparable (for comparisons) and ToArray (for serialization).
• Test Case: Use OskarStark\Enum\Test\EnumTestCase for consistent enum testing.
• Documentation: Review the README for trait methods and examples.

Implementation Patterns

Common Workflows

1. Enum Comparison

• Direct Equality:

  if ($role->equals(UserRole::ADMIN)) {
      // Grant admin access
  }
  

• Negated Equality:

  if ($role->notEquals(UserRole::VIEWER)) {
      // Allow editing
  }
  

• Membership Checks:

  if ($role->equalsOneOf([UserRole::ADMIN, UserRole::EDITOR])) {
      // Allow privileged actions
  }
  

2. Enum Serialization

• Backed Enums:

  $rolesArray = UserRole::toArray();
  // ['ADMIN' => 'admin', 'EDITOR' => 'editor', ...]
  

• Non-Backed Enums:

  enum Status { ACTIVE, INACTIVE }
  Status::toArray(); // ['ACTIVE' => 'ACTIVE', 'INACTIVE' => 'INACTIVE']
  

3. Domain-Specific Methods

Combine traits with custom logic:

enum UserRole: string
{
    use Comparable, ToArray;

    case ADMIN = 'admin';
    case EDITOR = 'editor';

    public function canManageUsers(): bool
    {
        return $this->equals(self::ADMIN);
    }
}

4. Testing Enums

Extend EnumTestCase for consistent tests:

use OskarStark\Enum\Test\EnumTestCase;

class UserRoleTest extends EnumTestCase
{
    protected function getEnum(): string
    {
        return UserRole::class;
    }

    public function testCanManageUsers()
    {
        $this->assertTrue(UserRole::ADMIN->canManageUsers());
        $this->assertFalse(UserRole::EDITOR->canManageUsers());
    }
}

Integration Tips

Laravel-Specific Patterns

1. Form Request Validation:

   public function rules()
   {
       return [
           'role' => ['required', Rule::in(array_column(UserRole::toArray(), 'value'))],
       ];
   }
   

2. API Responses:

   return response()->json([
       'roles' => UserRole::toArray(),
   ]);
   

3. Authorization:

   public function authorize()
   {
       return $this->user()->role()->equalsOneOf([
           UserRole::ADMIN,
           UserRole::EDITOR,
       ]);
   }
   

4. Database Seeders:

   UserRole::cases(); // Get all enum cases
   

Performance Considerations

• Caching: Cache toArray() results if called frequently in performance-critical paths.
• Early Returns: Use equalsOneOf() for bulk checks to avoid nested conditionals.

Gotchas and Tips

Pitfalls

1. Backed vs. Non-Backed Enums:

   • toArray() behaves differently for backed (UserRole::toArray() returns ['ADMIN' => 'admin']) vs. non-backed enums (Status::toArray() returns ['ACTIVE' => 'ACTIVE']).
   • Fix: Explicitly handle both cases or document expected behavior.

2. Type Safety:

   • equalsOneOf() accepts an array but may cause type errors if passed non-enum values.
   • Fix: Use array_map(fn($case) => UserRole::from($case), $array) to ensure type safety.

3. PHP 8.1+ Requirement:

   • The package requires PHP 8.1+. Ensure your Laravel project meets this requirement.
   • Fix: Update config.php in Laravel if using older versions.

4. Trait Conflicts:

   • Avoid mixing with other enum traits (e.g., Spatie\Enum\Enum).
   • Fix: Test for method conflicts or use composition over inheritance.

Debugging Tips

1. Static Analysis:

   • Use PHPStan to catch type-related issues with equalsOneOf().
   • Example config:

     // phpstan.neon
     parameters:
         level: max
     

2. IDE Support:

   • Enable PHP 8.1+ features in your IDE (e.g., PHPStorm) for autocomplete on enum methods.

3. Testing Edge Cases:

   • Test equalsOneOf() with empty arrays or null values:

     $role->equalsOneOf([]); // Should return false
     

Extension Points

1. Custom Comparison Logic: Extend the Comparable trait for custom rules:

   use OskarStark\Enum\Trait\Comparable;
   
   trait CustomComparable
   {
       public function isPremium(): bool
       {
           return $this->equals(self::PREMIUM);
       }
   }
   

2. Dynamic Array Conversion: Override toArray() for custom serialization:

   public function toArray(): array
   {
       return array_map(
           fn($case) => ['value' => $case->value, 'label' => ucfirst($case->value)],
           self::cases()
       );
   }
   

3. Rector Integration: Use the included Rector rules to automate trait adoption:

   vendor/bin/rector process src --dry-run
   

Configuration Quirks

1. Autoloading: Ensure OskarStark\Enum\* is autoloaded in composer.json:

   "autoload": {
       "psr-4": {
           "OskarStark\\Enum\\": "vendor/oskarstark/enum-helper/src"
       }
   }
   

2. Testing Setup: If using EnumTestCase, ensure your test suite includes:

   use OskarStark\Enum\Test\EnumTestCase;
   

3. PHPUnit Version: The package drops support for PHPUnit 9. Ensure compatibility with your Laravel version:

   composer require --dev phpunit/phpunit:^10