PHP PDO整型映射Enum属性的解决方法

1. 问题背景：PDO直接映射Enum属性的困境

自PHP 8.1引入枚举（Enum）特性以来，开发者在构建类型安全的应用程序时有了新的利器。然而，当涉及到将数据库中存储的整型值（通常代表枚举的原始值）映射到PHP对象中具有Enum类型提示的属性时，PDO的默认fetchObject()方法会遇到挑战。

考虑以下枚举和类定义：

// 枚举定义
enum UserType: int
{
    case Master = 1;
    case Admin = 2;
    case Manager = 3;
}

// 用户类定义
class User
{
    private int $id;
    private string $name;
    private UserType $userType; // Enum类型属性
}

当数据库中user表的userType字段存储的是整型值（例如1、2、3）时，如果直接使用fetchObject()尝试将数据填充到User类的实例中，例如：

// 假设这是你的fetchObject方法
public function fetchObject($sql, array $args = array(), string $class_name = "stdClass"): mixed
{
    $stmt = self::$instance->prepare($sql);
    if(empty($args)){
        $stmt->execute();
    } else{
        $stmt->execute($args);
    }
    $object = $stmt->fetchObject($class_name); // 问题所在
    $stmt->closeCursor();
    return $object;
}

// 调用示例
$user = Database::getInstance()->fetchObject(sql: "SELECT id, name, userType FROM user WHERE id = 1", class_name: User::class);

这段代码将抛出类似 Cannot assign int to property User::$userType of type UserType 的错误。这是因为PDO在尝试直接将数据库中的整型值赋给$userType属性时，发现其类型是UserType枚举，而不是int，导致类型不匹配。PDO的fetchObject方法并不具备自动将整型值转换为对应的Enum实例的能力。

2. 解决方案一：利用__set魔术方法和PDO::FETCH_PROPS_LATE

一种解决方案是结合使用PHP的__set魔术方法和PDO的PDO::FETCH_CLASS | PDO::FETCH_PROPS_LATE模式。这种方法允许你在属性被赋值时进行拦截和自定义处理。

工作原理：

1. PDO::FETCH_CLASS | PDO::FETCH_PROPS_LATE: 告诉PDO先调用类的构造函数，然后再尝试设置属性。
2. unset($this->userType): 在构造函数中，我们将userType属性取消设置。这样做的目的是为了让PDO在尝试设置userType时，由于该属性不存在，从而触发__set魔术方法。
3. __set($key, $value): 当userType属性被赋值时，__set方法会被调用。在这里，我们可以捕获到数据库传来的整型值，并使用UserType::from($value)将其转换为正确的Enum实例。

示例代码：

首先，确保你的Enum定义是带有底层值的：

// Enum定义
enum UserType: int // 必须指定底层类型
{
    case Master = 1;
    case Admin = 2;
    case Manager = 3;
}

// 修改后的User类
class User
{
    private int $id;
    private string $name;
    private UserType $userType; // 声明类型

    public function __construct()
    {
        // 在构造函数中取消设置userType属性，以便PDO调用__set方法
        unset($this->userType);
    }

    // __set魔术方法用于拦截属性赋值
    public function __set($key, $value)
    {
        if ($key === 'userType') {
            // 将整型值转换为UserType枚举实例
            $this->userType = UserType::from($value);
        } else {
            // 处理其他未声明的属性，或抛出错误
            // 最佳实践是避免这种情况，确保所有属性都已声明
            throw new \RuntimeException("Attempt to set unknown or unhandled property: $key");
        }
    }

    // 可以添加getter方法来访问属性
    public function getId(): int { return $this->id; }
    public function getName(): string { return $this->name; }
    public function getUserType(): UserType { return $this->userType; }
}

然后，修改你的PDO数据获取逻辑：

// 假设你已经有了PDOStatement对象 $stmt
// $stmt = self::$instance->prepare("SELECT id, name, userType FROM user WHERE id = 1");
// $stmt->execute();

// 设置PDO的fetch模式
// PDO::FETCH_CLASS: 创建类的实例
// PDO::FETCH_PROPS_LATE: 先调用构造函数，再设置属性（如果属性不存在，则调用__set）
$stmt->setFetchMode(PDO::FETCH_CLASS | PDO::FETCH_PROPS_LATE, User::class);
$user = $stmt->fetch();

if ($user instanceof User) {
    echo "User ID: " . $user->getId() . "\n";
    echo "User Name: " . $user->getName() . "\n";
    echo "User Type: " . $user->getUserType()->name . " (Value: " . $user->getUserType()->value . ")\n";
} else {
    echo "User not found or fetch failed.\n";
}

注意事项：

• 这种方法相对复杂，引入了魔术方法，可能会降低代码的可读性。
• 需要确保所有可能被PDO直接填充的属性都在__set中得到妥善处理，否则可能导致意外行为。
• 如果类中没有unset($this->userType)，__set方法将不会被触发，仍然会抛出类型错误。

3. 解决方案二：构造函数映射（推荐）

更推荐且通常更清晰的实现方式是，将数据作为关联数组获取，然后在类的构造函数中手动处理整型到Enum的转换。这种方法避免了魔术方法带来的复杂性，使数据流向更加明确。

工作原理：

1. PDO::FETCH_ASSOC: 告诉PDO将数据库行作为关联数组返回。
2. 构造函数处理: 在类的构造函数中，接收所有属性值（包括作为整型的userType），然后手动使用UserType::from($userType)将其转换为Enum实例。
3. 对象实例化: 使用关联数组解包 (...$row) 将数据传递给构造函数来创建对象实例。

示例代码：

首先，修改你的User类，使其构造函数能够接收原始数据并进行转换：

// Enum定义保持不变
enum UserType: int
{
    case Master = 1;
    case Admin = 2;
    case Manager = 3;
}

// 修改后的User类（使用构造函数属性提升，PHP 8.0+）
class User
{
    private UserType $userType; // 声明类型

    public function __construct(
        private int $id,
        private string $name,
        int $userType // 构造函数接收整型值
    ) {
        // 在构造函数中将整型值转换为UserType枚举实例
        $this->userType = UserType::from($userType);
    }

    // Getter方法
    public function getId(): int { return $this->id; }
    public function getName(): string { return $this->name; }
    public function getUserType(): UserType { return $this->userType; }
}

接下来，修改你的fetchObject方法（或任何数据获取逻辑），使其先获取关联数组，然后手动实例化对象：

// 修改后的fetchObject方法
public function fetchObject($sql, array $args = [], string $class_name = "stdClass"): ?object
{
    $stmt = self::$instance->prepare($sql);
    $stmt->execute($args ?: null); // $args ?: null 处理空数组情况
    $row = $stmt->fetch(PDO::FETCH_ASSOC); // 获取关联数组
    $stmt->closeCursor();

    if ($row) {
        // 使用关联数组解包创建类实例，将数组键值作为命名参数传递给构造函数
        // 要求PHP 8.0+支持命名参数和构造函数属性提升
        return new $class_name(...$row);
    }
    return null;
}

// 调用示例
$user = Database::getInstance()->fetchObject(sql: "SELECT id, name, userType FROM user WHERE id = 1", class_name: User::class);

if ($user instanceof User) {
    echo "User ID: " . $user->getId() . "\n";
    echo "User Name: " . $user->getName() . "\n";
    echo "User Type: " . $user->getUserType()->name . " (Value: " . $user->getUserType()->value . ")\n";
} else {
    echo "User not found or fetch failed.\n";
}

注意事项：

• 此方法要求PHP 8.0+才能使用new $class_name(...$row)这种通过数组解包传递命名参数给构造函数的语法。
• 如果你的PHP版本低于8.0，你需要手动将数组元素映射到构造函数的参数中。
• 确保数据库查询返回的列名与构造函数参数名（或属性名）一致，以便数组解包能够正确匹配。

4. 总结与最佳实践

在将数据库整型值映射到PHP Enum属性时，直接使用PDO的fetchObject()方法会因类型不匹配而失败。我们探讨了两种有效的解决方案：

1. __set魔术方法与PDO::FETCH_PROPS_LATE: 这种方法利用PHP的反射机制和魔术方法，在属性赋值时进行拦截和转换。它功能强大，但代码可读性相对较低，且引入了额外的复杂性。
2. 构造函数映射: 这种方法通过PDO::FETCH_ASSOC获取关联数组，然后在类的构造函数中显式地进行整型到Enum的转换。它更直观、更易于理解和维护，是处理此类场景的推荐方式。

在大多数情况下，构造函数映射是更优的选择。它使数据转换逻辑清晰地封装在类的构造函数中，符合面向对象的设计原则，并减少了对PHP魔术方法的依赖，从而提高了代码的可读性和可维护性。确保你的Enum定义了底层类型（例如enum UserType: int），这是使用Enum::from($value)进行转换的前提。