laravel-enums
Backed enums with labels and business logic. Use when working with enums, status values, fixed sets of options, or when user mentions enums, backed enums, enum cases, status enums.
When & Why to Use This Skill
This Claude skill provides a comprehensive framework for implementing robust, type-safe backed enums in Laravel applications. It streamlines the creation of finite value sets by integrating business logic, UI labels, and custom attributes directly into PHP enums, ensuring code maintainability and reducing boilerplate in models, DTOs, and validation logic.
Use Cases
- Defining standardized application states like OrderStatus or PaymentMethod with human-readable labels for frontend dropdowns and UI components.
- Encapsulating domain-specific business logic, such as calculating processing fees or checking feature support, directly within enum cases to eliminate messy switch statements.
- Enhancing data integrity by utilizing enums in Laravel Eloquent model casts and form request validation rules to ensure only valid cases are persisted.
- Improving developer productivity and code quality through IDE autocomplete and type-safe comparisons using specialized traits for enum handling.
| name | laravel-enums |
|---|---|
| description | Backed enums with labels and business logic. Use when working with enums, status values, fixed sets of options, or when user mentions enums, backed enums, enum cases, status enums. |
Laravel Enums
Enums provide type-safe, finite sets of values.
Related guides:
- State Machines - For complex state transitions
- Models - Model casts to enums
- DTOs - DTOs with enum properties
- form-requests.md - Enum validation
Always Use Backed Enums
Always use backed enums (string or int):
<?php
declare(strict_types=1);
namespace App\Enums;
enum OrderStatus: string
{
case Pending = 'pending';
case Processing = 'processing';
case Completed = 'completed';
case Cancelled = 'cancelled';
}
Enum with Traits
Add functionality with traits:
<?php
declare(strict_types=1);
namespace App\Enums;
use Henzeb\Enumhancer\Concerns\Comparison;
use Henzeb\Enumhancer\Concerns\Dropdown;
enum OrderStatus: string
{
use Comparison, Dropdown;
case Pending = 'pending';
case Processing = 'processing';
case Completed = 'completed';
case Cancelled = 'cancelled';
}
Enum with Labels
<?php
declare(strict_types=1);
namespace App\Enums;
use App\Enums\Attributes\Label;
use App\Enums\Concerns\HasLabel;
enum PaymentMethod: string
{
use HasLabel;
#[Label('Credit Card')]
case CreditCard = 'credit-card';
#[Label('Bank Transfer')]
case BankTransfer = 'bank-transfer';
#[Label('PayPal')]
case PayPal = 'paypal';
}
Custom Enum Attributes
<?php
declare(strict_types=1);
namespace App\Enums\Attributes;
use Attribute;
#[Attribute(Attribute::TARGET_CLASS_CONSTANT)]
class Label
{
public function __construct(public string $value) {}
}
#[Attribute(Attribute::TARGET_CLASS_CONSTANT)]
class Color
{
public function __construct(public string $value) {}
}
#[Attribute(Attribute::TARGET_CLASS_CONSTANT)]
class Icon
{
public function __construct(public string $value) {}
}
Enum Concerns
<?php
declare(strict_types=1);
namespace App\Enums\Concerns;
use App\Enums\Attributes\Label;
use Henzeb\Enumhancer\Concerns\Attributes;
use Henzeb\Enumhancer\Concerns\Dropdown;
use Henzeb\Enumhancer\Concerns\Labels;
trait HasLabel
{
use Attributes, Dropdown, Labels;
public static function labels(): array
{
return collect(self::cases())->mapWithKeys(fn ($enum) => [
$enum->name => $enum->getLabel(),
])->toArray();
}
public function getLabel(): ?string
{
return $this->getAttribute(Label::class)?->value;
}
}
Business Logic in Enums
Enums can contain behavior:
enum PaymentProvider: string
{
case Stripe = 'stripe';
case PayPal = 'paypal';
case Square = 'square';
public function processingFee(int $amount): int
{
return match ($this) {
self::Stripe => (int) ($amount * 0.029 + 30),
self::PayPal => (int) ($amount * 0.034 + 30),
self::Square => (int) ($amount * 0.026 + 10),
};
}
public function supportsRefunds(): bool
{
return match ($this) {
self::Stripe, self::PayPal => true,
self::Square => false,
};
}
}
Usage in Models
protected function casts(): array
{
return [
'status' => OrderStatus::class,
'payment_method' => PaymentMethod::class,
];
}
Usage in DTOs
public function __construct(
public OrderStatus $status,
public PaymentMethod $paymentMethod,
) {}
Usage in Validation
use Illuminate\Validation\Rules\Enum;
'status' => [
'required',
'string',
'bail',
new Enum(OrderStatus::class),
],
Common Patterns
Comparison
if ($order->status->is(OrderStatus::Completed)) {
// ...
}
// With enumhancer Comparison trait
if ($order->status->isCompleted()) {
// ...
}
UI Attributes
$status->getLabel(); // 'Completed'
PaymentMethod::dropdown(); // For select inputs
OrderStatus::labels(); // All labels as array
Match Expressions
$message = match ($order->status) {
OrderStatus::Pending => 'Your order is pending',
OrderStatus::Processing => 'We are processing your order',
OrderStatus::Completed => 'Your order is complete',
OrderStatus::Cancelled => 'Your order was cancelled',
};
Queue Enum Example
<?php
declare(strict_types=1);
namespace App\Enums;
enum Queue: string
{
case Default = 'default';
case Processing = 'processing';
case Emails = 'emails';
case Notifications = 'notifications';
}
Usage in jobs:
public function __construct(public Order $order)
{
$this->onQueue(Queue::Emails->value);
}
Directory Structure
app/Enums/
├── OrderStatus.php
├── PaymentMethod.php
├── Queue.php
├── Attributes/
│ ├── Label.php
│ ├── Color.php
│ └── Icon.php
└── Concerns/
└── HasLabel.php
When to Use Enums vs State Machines
Use Enums:
- Simple status fields
- No transition logic
- No side effects
Use State Machines:
- Complex state transitions with rules
- State-specific behavior
- Transition side effects
See State Machines for state machines.
Summary
Enums provide:
- Type safety
- Finite value sets
- Business logic encapsulation
- UI helpers (labels, colors, icons)
- IDE autocomplete
Always use backed enums with string or int values.