laravel-enums

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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

Enums提供类型安全的有限值集合。

相关指南：

状态机 - 用于复杂状态转换
模型 - 模型转换为枚举
DTO - 包含枚举属性的DTO
form-requests.md - 枚举验证

Always Use Backed Enums

始终使用Backed枚举

Always use backed enums (string or int):

php

<?php

declare(strict_types=1);

namespace App\Enums;

enum OrderStatus: string
{
    case Pending = 'pending';
    case Processing = 'processing';
    case Completed = 'completed';
    case Cancelled = 'cancelled';
}

始终使用Backed枚举（字符串或整数类型）：

php

<?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

使用Trait的枚举

Add functionality with traits:

php

<?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';
}

通过Trait添加功能：

php

<?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

<?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';
}

php

<?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

<?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) {}
}

php

<?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

枚举Concerns

php

<?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;
    }
}

php

<?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:

php

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,
        };
    }
}

枚举可以包含行为：

php

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

在模型中的使用

php

protected function casts(): array
{
    return [
        'status' => OrderStatus::class,
        'payment_method' => PaymentMethod::class,
    ];
}

php

protected function casts(): array
{
    return [
        'status' => OrderStatus::class,
        'payment_method' => PaymentMethod::class,
    ];
}

Usage in DTOs

在DTO中的使用

php

public function __construct(
    public OrderStatus $status,
    public PaymentMethod $paymentMethod,
) {}

php

public function __construct(
    public OrderStatus $status,
    public PaymentMethod $paymentMethod,
) {}

Usage in Validation

在验证中的使用

php

use Illuminate\Validation\Rules\Enum;

'status' => [
    'required',
    'string',
    'bail',
    new Enum(OrderStatus::class),
],

php

use Illuminate\Validation\Rules\Enum;

'status' => [
    'required',
    'string',
    'bail',
    new Enum(OrderStatus::class),
],

Common Patterns

常见模式

Comparison

比较

php

if ($order->status->is(OrderStatus::Completed)) {
    // ...
}

// With enumhancer Comparison trait
if ($order->status->isCompleted()) {
    // ...
}

php

if ($order->status->is(OrderStatus::Completed)) {
    // ...
}

// 使用enumhancer的Comparison trait
if ($order->status->isCompleted()) {
    // ...
}

UI Attributes

UI属性

php

$status->getLabel();  // 'Completed'
PaymentMethod::dropdown();  // For select inputs
OrderStatus::labels();  // All labels as array

php

$status->getLabel();  // 'Completed'
PaymentMethod::dropdown();  // 用于选择输入框
OrderStatus::labels();  // 所有标签的数组形式

Match Expressions

Match表达式

php

$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',
};

php

$message = match ($order->status) {
    OrderStatus::Pending => '您的订单待处理',
    OrderStatus::Processing => '我们正在处理您的订单',
    OrderStatus::Completed => '您的订单已完成',
    OrderStatus::Cancelled => '您的订单已取消',
};

Queue Enum Example

队列枚举示例

php

<?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:

php

public function __construct(public Order $order)
{
    $this->onQueue(Queue::Emails->value);
}

php

<?php

declare(strict_types=1);

namespace App\Enums;

enum Queue: string
{
    case Default = 'default';
    case Processing = 'processing';
    case Emails = 'emails';
    case Notifications = 'notifications';
}

在任务中的使用：

php

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

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

何时使用枚举vs状态机

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.

枚举提供：

类型安全
有限值集合
业务逻辑封装
UI辅助工具（标签、颜色、图标）
IDE自动补全

始终使用带字符串或整数值的Backed枚举。