Enums Laravel Package

Getting Started

1. Install the package via Composer:

   composer require archtechx/enums
   

2. Define your first enum using native PHP 8.1+ syntax, and apply the provided trait:

   use ArchTech\Enums\Attributes\Case;
   use ArchTech\Enums\Attributes\Label;
   use ArchTech\Enums\Enum;
   
   enum Status: string implements Enum
   {
       use Enum;
   
       #[Label('Draft')]
       case DRAFT = 'draft';
   
       #[Label('Published')]
       case PUBLISHED = 'published';
   
       #[Label('Archived')]
       case ARCHIVED = 'archived';
   }
   

3. First use case: Build a form select dropdown with minimal code:

   // In a form or Blade template
   <select name="status">
       @foreach (Status::selectArray() as $value => $label)
           <option value="{{ $value }}" {{ request('status') == $value ? 'selected' : '' }}>
               {{ $label }}
           </option>
       @endforeach
   </select>
   

   No manual array building needed.

Implementation Patterns

• Model Casting: Use the provided EnumCaster for seamless database serialization/deserialization. Register in AppServiceProvider:

  use ArchTech\Enums\Casters\EnumCaster;
  use Illuminate\Database\Eloquent\Casts\Attribute;
  
  Attribute::castUsing('enum', EnumCaster::class);
  

  Then in your model:

  protected $casts = [
      'status' => 'enum:App\Enums\Status',
  ];
  

• Validation Rules: Use the built-in EnumRule:

  use ArchTech\Enums\Rules\Enum;
  
  'status' => ['required', new Enum(Status::class)],
  

• Label Display in Views: Inject labels directly in Blade:

  <span class="badge badge-{{ $order->status->colorClass() }}">{{ $order->status->label() }}</span>
  

• Dynamic Dropdowns: Generate JSON for frontend frameworks:

  return Status::map(fn ($case) => [
      'value' => $case->value,
      'label' => $case->label(),
  ]);
  

• Case Discovery: Iterate cases programmatically:

  Status::cases()->filter(fn ($case) => $case->is($status)); // precise comparison
  

Gotchas and Tips

• Case sensitivity & labels: label() uses the #[Label] attribute — if missing, it falls back to humanized case name (DRAFT → Draft). Always annotate labels for production UI consistency.

• Enum classes must implement Enum: The package extends native enums via traits. Forgetting use Enum in your enum will cause silent failures or missing methods.

• Array conversion gotcha: Status::selectArray() returns [value => label], while Status::toArray() returns ['DRAFT' => 'Draft', ...]. Use the correct one for dropdowns vs. JS mappings.

• Testing tip: Use Status::tryFrom('draft') instead of Status::from() to avoid exceptions in seeders/tests:

  $status = Status::tryFrom($value) ?? Status::DRAFT;
  

• Extensibility: Extend enum behavior with custom methods — the trait is non-intrusive:

  public function colorClass(): string
  {
      return match ($this) {
          self::DRAFT => 'secondary',
          self::PUBLISHED => 'success',
          self::ARCHIVED => 'muted',
      };
  }
  

• Framework agnostic: Though Laravel-optimized, all helpers work in Symfony or plain PHP — use Enum::label(), Enum::cases(), etc. without Lumen/Laravel dependencies.