Enums Laravel Package

## Getting Started

### Minimal Steps
1. **Installation**
   ```bash
   composer require prinsfrank/enums

No additional configuration is required—works as a drop-in enhancement for PHP 8.1+ enums (including BackedEnum).

2. First Use Case Define a basic enum (supports both regular and BackedEnum):

   // Regular enum
   enum Status: string
   {
       case PENDING = 'pending';
       case APPROVED = 'approved';
   }
   
   // BackedEnum (now with optimized `toArray()` in v1.4.1)
   enum Priority: int
   {
       case LOW = 1;
       case MEDIUM = 2;
       case HIGH = 3;
   }
   

   Use the package’s methods directly:

   // Get all values as an array (works for both enum types)
   $priorities = Priority::values(); // [1, 2, 3]
   $statuses = Status::values();     // ['pending', 'approved']
   
   // Simplified BackedEnum `toArray()` (v1.4.1 change)
   $priorityArray = Priority::HIGH->toArray(); // ['name' => 'HIGH', 'value' => 3]
   

3. Where to Look First

   • Package Source (check the v1.4.1 changelog for toArray() simplification).
   • PHP 8.1+ Enum Docs.
   • Run php artisan tinker to test:

     use App\Enums\Priority;
     Priority::HIGH->toArray(); // Verify simplified output
     

Implementation Patterns

Usage Patterns

1. BackedEnum Integration (Simplified toArray()) Leverage the simplified toArray() for serialization (v1.4.1):

   $priorityData = Priority::HIGH->toArray();
   // Returns: ['name' => 'HIGH', 'value' => 3] (no custom overrides needed)
   

   Use in API responses or JSON:

   return response()->json([
       'priority' => Priority::HIGH->toArray(),
   ]);
   

2. Validation with Enums Validate against enum values (works for both types):

   use Illuminate\Validation\Rule;
   
   $request->validate([
       'priority' => ['required', Rule::in(Priority::values())],
       'status'   => ['required', Rule::in(Status::values())],
   ]);
   

3. Database and Eloquent (BackedEnum Support) Cast BackedEnum values in models:

   protected $casts = [
       'priority' => Priority::class, // Works for BackedEnum
       'status'   => Status::class,
   ];
   

   Query scopes for BackedEnum:

   public function scopeHighPriority($query)
   {
       return $query->where('priority', Priority::HIGH->value);
   }
   

4. Dynamic Enum Handling Convert between enums and arrays dynamically:

   $enumCases = collect(Status::cases())
       ->map(fn($case) => $case->toArray())
       ->all();
   

Workflows

1. Enum-Driven Forms (BackedEnum) Use toArray() for form options (simplified in v1.4.1):

   <select wire:model="priority">
       @foreach (Priority::cases() as $priority)
           <option value="{{ $priority->value }}">
               {{ $priority->name }} ({{ $priority->value }})
           </option>
       @endforeach
   </select>
   

2. Testing BackedEnum Assert toArray() behavior (now standardized):

   $this->assertEquals(
       ['name' => 'HIGH', 'value' => 3],
       Priority::HIGH->toArray()
   );
   

3. Legacy Migration (BackedEnum) Replace manual arrays with BackedEnum:

   // Before
   $oldPriorities = [1, 2, 3];
   
   // After (v1.4.1)
   $newPriorities = Priority::values();
   

Integration Tips

• API Resources Serialize BackedEnum cases with simplified toArray():

  public function toArray($request)
  {
      return [
          'priorities' => Priority::cases()->map(fn($case) => $case->toArray()),
      ];
  }
  

• Livewire/Alpine Bind BackedEnum values (no custom toArray() needed):

  <select x-model="priority" wire:model="priority">
      @foreach (Priority::cases() as $priority)
          <option value="{{ $priority->value }}">
              {{ $priority->name }}
          </option>
      @endforeach
  </select>
  

• Caching Cache BackedEnum values for performance:

  $priorities = cache()->remember('priorities', now()->addHours(1), fn() => Priority::values());
  

Gotchas and Tips

Pitfalls

1. BackedEnum toArray() Simplification (v1.4.1)

   • Issue: The toArray() method was simplified in v1.4.1. If your code relied on a custom implementation (e.g., overriding toArray()), ensure compatibility.
   • Fix: Remove custom overrides unless extending functionality:

     // Old custom implementation (no longer needed)
     public function toArray(): array { ... }
     
     // New: Use the simplified default
     Priority::HIGH->toArray(); // ['name' => 'HIGH', 'value' => 3]
     

2. Case Sensitivity in BackedEnum

   • Issue: hasValue() remains case-sensitive for string-backed enums.
   • Fix: Normalize input:

     Status::hasValue(strtolower($input)); // For string enums
     

3. Performance with Large BackedEnum

   • Issue: toArray() on every case in loops may impact performance.
   • Fix: Cache results or preload:

     $cachedCases = Priority::cases()->map(fn($case) => $case->toArray())->all();
     

Debugging

1. BackedEnum toArray() Output

   • Verify the new output format (v1.4.1):

     var_dump(Priority::HIGH->toArray());
     // Expected: ['name' => 'HIGH', 'value' => 3] (no custom fields)
     

   • If unexpected, check for method overrides or package updates.

2. Type Safety for BackedEnum

   • Error: Priority::from(4) throws ValueError.
   • Debug: Use hasValue() first:

     if (!Priority::hasValue($value)) {
         throw new \RuntimeException("Invalid priority");
     }
     

3. IDE Autocomplete

   • Ensure your IDE recognizes toArray() for BackedEnum:

     /** @var \PrinsFrank\Enums\BackedEnum<int, string> $enum */
     $enum->toArray(); // Should autocomplete with ['name', 'value']
     

Config Quirks

• No Configuration: The package remains zero-config. All methods are static and attached to enum classes at runtime.
• Extension Points:
  • Custom toArray(): Extend BackedEnum for additional fields (not replacements):

    enum Priority extends \PrinsFrank\Enums\BackedEnum
    {
        case HIGH = 3;
        public function toArray(): array
        {
            return array_merge(
                parent::toArray(), // Include simplified default
                ['label' => ucfirst($this->name)]
            );
        }
    }
    

Tips

1. BackedEnum Best Practices (v1.4.1)

   • Use the simplified toArray() for consistent serialization.
   • Avoid overriding toArray() unless adding fields (not replacing logic).

2. Localization with BackedEnum Combine with Laravel localization:

   $priorityLabels = collect(Priority::cases())
       ->map(fn($case) => __("enum.priorities.{$case->name}"))
       ->all();
   

3. Testing Edge Cases for BackedEnum

   • Test toArray() with:
     • All enum cases.
     • Edge values (e.g., Priority::LOW).
     • Invalid values (expect ValueError).

4. Performance Optimization

   • For large BackedEnum, preload all cases:

     $allPrior