PHP 8.1 枚举（Enums）的高级用法：结合数据类型与数据库存储的最佳实践

PHP 8.1 枚举（Enums）的高级用法：结合数据类型与数据库存储的最佳实践

大家好，今天我们来深入探讨 PHP 8.1 中引入的枚举 (Enums)，并重点关注它们与数据类型结合以及在数据库存储中的最佳实践。枚举作为一种强大的类型系统工具，可以显著提高代码的可读性、可维护性和安全性。我们将从基础概念开始，逐步过渡到高级用法，并通过实际示例演示如何在真实项目中有效利用枚举。

1. 枚举的基础概念

枚举是一种特殊的类，它定义了一组命名的常量值。这些常量值被称为枚举成员或枚举案例 (cases)。与传统的常量定义方式相比，枚举提供了更强的类型安全性和代码组织性。

1.1 简单枚举

最简单的枚举定义如下：

enum Status
{
    case Pending;
    case Active;
    case Inactive;
}

在这个例子中，Status 枚举定义了三个可能的状态：Pending、Active 和 Inactive。

1.2 枚举的使用

我们可以像使用对象一样使用枚举：

$currentStatus = Status::Active;

if ($currentStatus === Status::Active) {
    echo "当前状态是激活状态";
}

1.3 枚举的优势

• 类型安全： 枚举可以防止使用未定义的常量值。如果尝试将一个非 Status 枚举的值赋给 $currentStatus，PHP 会抛出一个类型错误。
• 可读性： 枚举成员的命名清晰易懂，提高了代码的可读性。
• 代码组织： 枚举将相关的常量值组织在一起，方便管理和维护。

2. 关联数据类型的枚举

PHP 8.1 允许枚举关联数据类型，这使得我们可以将额外的信息与每个枚举成员关联起来。这极大地扩展了枚举的用途，使其能够表示更复杂的数据结构。

2.1 关联字符串的枚举

enum UserRole: string
{
    case Admin = 'admin';
    case Editor = 'editor';
    case Subscriber = 'subscriber';

    public function getDisplayName(): string
    {
        return match($this) {
            self::Admin => '管理员',
            self::Editor => '编辑',
            self::Subscriber => '订阅者',
        };
    }
}

在这个例子中，UserRole 枚举关联了字符串类型。每个枚举成员都与一个字符串值相关联。Admin 成员的值是 'admin'，Editor 成员的值是 'editor'，以此类推。 此外，还定义了一个getDisplayName方法，用于获取用户角色更友好的显示名称。

2.2 关联整型的枚举

enum ErrorCode: int
{
    case Success = 0;
    case NotFound = 404;
    case InternalServerError = 500;
}

类似地，ErrorCode 枚举关联了整型。

2.3 访问关联值

可以通过 value 属性访问枚举成员的关联值：

$role = UserRole::Admin;
echo $role->value; // 输出 "admin"

$errorCode = ErrorCode::NotFound;
echo $errorCode->value; // 输出 404

3. 枚举的方法

枚举可以像类一样定义方法。这使得我们可以为枚举成员添加行为，从而进一步提高代码的表达力。

3.1 定义枚举方法

在上面的 UserRole 枚举示例中，我们已经定义了一个 getDisplayName 方法。这个方法根据枚举成员的值返回一个更友好的显示名称。

3.2 使用枚举方法

$role = UserRole::Editor;
echo $role->getDisplayName(); // 输出 "编辑"

4. 枚举与数据库存储

将枚举与数据库存储结合使用可以确保数据的一致性和有效性。以下是一些最佳实践：

4.1 将枚举值存储为字符串或整数

最常见的做法是将枚举值存储为数据库表中的字符串或整数。如果枚举关联了字符串或整数类型，则可以直接将这些值存储到数据库中。

例如，对于 UserRole 枚举，可以将 role 列定义为 VARCHAR 类型，并将枚举成员的 value 属性存储到该列中。

对于 ErrorCode 枚举，可以将 error_code 列定义为 INT 类型，并将枚举成员的 value 属性存储到该列中。

4.2 使用数据库约束确保数据有效性

为了确保数据库中的枚举值始终有效，可以使用数据库约束。例如，可以使用 ENUM 类型或 CHECK 约束来限制 role 列的值只能是 admin、editor 和 subscriber。

4.3 使用 ORM 框架简化枚举的存储和检索

ORM (Object-Relational Mapping) 框架可以简化枚举的存储和检索。许多 ORM 框架（如 Doctrine 和 Eloquent）都提供了对枚举的支持。

4.3.1 Doctrine 的枚举类型

Doctrine 允许你自定义数据库类型，以便将 PHP 枚举映射到数据库列。

首先，创建一个自定义的 Doctrine 类型：

// src/DBAL/Types/UserRoleType.php
namespace AppDBALTypes;

use AppEnumsUserRole;
use DoctrineDBALPlatformsAbstractPlatform;
use DoctrineDBALTypesType;

class UserRoleType extends Type
{
    public const NAME = 'user_role';

    public function getSQLDeclaration(array $fieldDeclaration, AbstractPlatform $platform): string
    {
        return $platform->getStringTypeDeclarationSQL($fieldDeclaration); // Or use enum type if your DB supports it
    }

    public function convertToPHPValue($value, AbstractPlatform $platform): ?UserRole
    {
        if ($value === null) {
            return null;
        }

        return UserRole::tryFrom($value); // Using tryFrom to handle potential invalid values
    }

    public function convertToDatabaseValue($value, AbstractPlatform $platform): ?string
    {
        if ($value instanceof UserRole) {
            return $value->value;
        }

        return null;
    }

    public function getName(): string
    {
        return self::NAME;
    }

    public function requiresSQLCommentHint(AbstractPlatform $platform): bool
    {
        return true;
    }
}

然后，在 Doctrine 中注册这个类型：

// config/packages/doctrine.yaml
doctrine:
    dbal:
        types:
            user_role: AppDBALTypesUserRoleType

最后，在你的 Doctrine 实体中使用这个类型：

// src/Entity/User.php
namespace AppEntity;

use DoctrineORMMapping as ORM;
use AppEnumsUserRole;
use AppDBALTypesUserRoleType;

/**
 * @ORMEntity
 */
class User
{
    /**
     * @ORMId
     * @ORMGeneratedValue
     * @ORMColumn(type="integer")
     */
    private ?int $id = null;

    /**
     * @ORMColumn(type="user_role", nullable=true)
     */
    private ?UserRole $role = null;

    public function getId(): ?int
    {
        return $this->id;
    }

    public function getRole(): ?UserRole
    {
        return $this->role;
    }

    public function setRole(?UserRole $role): self
    {
        $this->role = $role;

        return $this;
    }
}

4.3.2 Eloquent 的属性转换 (Casting)

在 Laravel 中，Eloquent 提供了属性转换功能，可以方便地将数据库中的值转换为枚举类型。

在你的 Eloquent 模型中，定义 $casts 属性：

// app/Models/User.php
namespace AppModels;

use IlluminateDatabaseEloquentModel;
use AppEnumsUserRole;

class User extends Model
{
    /**
     * The attributes that should be cast.
     *
     * @var array
     */
    protected $casts = [
        'role' => UserRole::class,
    ];
}

现在，当你从数据库中检索 User 模型时，role 属性会自动转换为 UserRole 枚举类型。

5. 枚举的高级用法

5.1 from() 和 tryFrom() 方法

PHP 8.1 提供了 from() 和 tryFrom() 方法，用于从关联值创建枚举实例。

• from() 方法：如果关联值存在，则返回相应的枚举实例；否则，抛出一个 ValueError 异常。
• tryFrom() 方法：如果关联值存在，则返回相应的枚举实例；否则，返回 null。

$role = UserRole::from('admin'); // 返回 UserRole::Admin
$role = UserRole::tryFrom('unknown'); // 返回 null

try {
    $role = UserRole::from('unknown'); // 抛出 ValueError 异常
} catch (ValueError $e) {
    echo "无效的用户角色";
}

5.2 cases() 方法

cases() 方法返回一个包含所有枚举成员的数组。

$roles = UserRole::cases();

foreach ($roles as $role) {
    echo $role->name . " => " . $role->value . "n";
}

输出:

Admin => admin
Editor => editor
Subscriber => subscriber

5.3 使用枚举作为数组键

由于枚举本质上是对象，不能直接用作数组的键。但可以通过name属性或value属性来实现类似的功能。

$permissions = [
    UserRole::Admin->name => ['create', 'update', 'delete'],
    UserRole::Editor->name => ['create', 'update'],
    UserRole::Subscriber->name => ['read'],
];

echo $permissions[UserRole::Editor->name][0]; // 输出 "create"

$permissionsWithValue = [
    UserRole::Admin->value => ['create', 'update', 'delete'],
    UserRole::Editor->value => ['create', 'update'],
    UserRole::Subscriber->value => ['read'],
];

echo $permissionsWithValue[UserRole::Editor->value][0]; // 输出 "create"

5.4 枚举与接口

枚举可以实现接口，这使得我们可以定义枚举的行为规范。

interface PermissionInterface
{
    public function canCreate(): bool;
    public function canUpdate(): bool;
    public function canDelete(): bool;
}

enum UserRole: string implements PermissionInterface
{
    case Admin = 'admin';
    case Editor = 'editor';
    case Subscriber = 'subscriber';

    public function getDisplayName(): string
    {
        return match($this) {
            self::Admin => '管理员',
            self::Editor => '编辑',
            self::Subscriber => '订阅者',
        };
    }

    public function canCreate(): bool
    {
        return match($this) {
            self::Admin, self::Editor => true,
            self::Subscriber => false,
        };
    }

    public function canUpdate(): bool
    {
        return match($this) {
            self::Admin, self::Editor => true,
            self::Subscriber => false,
        };
    }

    public function canDelete(): bool
    {
        return $this === self::Admin;
    }
}

$role = UserRole::Editor;
echo $role->canCreate() ? '可以创建' : '不能创建'; // 输出 "可以创建"
echo $role->canDelete() ? '可以删除' : '不能删除'; // 输出 "不能删除"

6. 实际示例：订单状态管理

我们来看一个更完整的实际示例，演示如何使用枚举来管理订单状态。

enum OrderStatus: string
{
    case Pending = 'pending';
    case Processing = 'processing';
    case Shipped = 'shipped';
    case Delivered = 'delivered';
    case Cancelled = 'cancelled';

    public function getDisplayName(): string
    {
        return match ($this) {
            self::Pending => '待处理',
            self::Processing => '处理中',
            self::Shipped => '已发货',
            self::Delivered => '已送达',
            self::Cancelled => '已取消',
        };
    }

    public function canCancel(): bool
    {
        return in_array($this, [self::Pending, self::Processing]);
    }

    public function canShip(): bool
    {
        return $this === self::Processing;
    }

    public function canDeliver(): bool
    {
        return $this === self::Shipped;
    }
}

class Order
{
    private OrderStatus $status;

    public function __construct(OrderStatus $status = OrderStatus::Pending)
    {
        $this->status = $status;
    }

    public function getStatus(): OrderStatus
    {
        return $this->status;
    }

    public function setStatus(OrderStatus $status): void
    {
        $this->status = $status;
    }

    public function cancel(): void
    {
        if ($this->status->canCancel()) {
            $this->setStatus(OrderStatus::Cancelled);
            echo "订单已取消n";
        } else {
            echo "订单无法取消n";
        }
    }

    public function ship(): void
    {
        if ($this->status->canShip()) {
            $this->setStatus(OrderStatus::Shipped);
            echo "订单已发货n";
        } else {
            echo "订单无法发货n";
        }
    }

    public function deliver(): void
    {
        if ($this->status->canDeliver()) {
            $this->setStatus(OrderStatus::Delivered);
            echo "订单已送达n";
        } else {
            echo "订单无法送达n";
        }
    }
}

$order = new Order();
echo "订单状态: " . $order->getStatus()->getDisplayName() . "n"; // 输出 "订单状态: 待处理"

$order->ship(); // 输出 "订单无法发货"
$order->setStatus(OrderStatus::Processing);
$order->ship(); // 输出 "订单已发货"
echo "订单状态: " . $order->getStatus()->getDisplayName() . "n"; // 输出 "订单状态: 已发货"
$order->deliver(); // 输出 "订单已送达"
echo "订单状态: " . $order->getStatus()->getDisplayName() . "n"; // 输出 "订单状态: 已送达"
$order->cancel(); // 输出 "订单无法取消"

7. 枚举的优势总结

特性	描述
类型安全	防止使用未定义的常量值，提高代码的健壮性。
可读性	枚举成员的命名清晰易懂，提高了代码的可读性和可维护性。
代码组织	枚举将相关的常量值组织在一起，方便管理和维护。
关联数据	可以将额外的信息与每个枚举成员关联起来，使其能够表示更复杂的数据结构。
方法	可以为枚举成员添加行为，从而进一步提高代码的表达力。
数据库集成	可以方便地将枚举值存储到数据库中，并使用数据库约束确保数据有效性。
ORM 支持	许多 ORM 框架都提供了对枚举的支持，可以简化枚举的存储和检索。

8. 如何更好地使用枚举

• 明确枚举的用途： 在定义枚举之前，仔细考虑其用途。枚举应该用于表示一组相关的常量值，这些常量值具有清晰的语义。
• 选择合适的关联数据类型： 如果枚举需要关联数据，选择最适合的数据类型。字符串类型适合表示文本值，整型适合表示数值。
• 定义枚举方法： 为枚举成员添加行为，以提高代码的表达力。例如，可以定义方法来获取枚举成员的显示名称、验证枚举成员的有效性等。
• 使用数据库约束： 为了确保数据库中的枚举值始终有效，可以使用数据库约束。
• 利用 ORM 框架： 如果使用 ORM 框架，利用其提供的枚举支持来简化枚举的存储和检索。
• 避免过度使用： 不要为了使用枚举而使用枚举。如果一个常量值不需要类型安全或代码组织，则可以使用传统的常量定义方式。

9. 提升代码质量和可维护性的实践

总而言之，PHP 8.1 的枚举为我们提供了一种强大的类型系统工具。通过合理地使用枚举，我们可以显著提高代码的可读性、可维护性和安全性，并简化与数据库的集成。希望今天的分享能帮助大家更好地理解和应用枚举，写出更高质量的 PHP 代码。