当前位置：首页 > news >正文

PHP 值对象实战指南：避免原始类型偏执

news 2026/5/11 18:11:21

PHP 值对象实战指南：避免原始类型偏执

上一篇文章里，我们聊了原始类型偏执（Primitive Obsession）在 PHP 里为什么这么常见：邮箱、金额、日期、ID……统统用 string/int/float/array 传来传去。领域含义被抹平，校验逻辑散落在各处，代码越写越难改。

这一篇我们继续往下走：值对象（Value Object）不仅能让代码更清晰，还能让协作、测试和后续演进都更省心。不管你用的是 Laravel、Symfony 还是别的框架，只要项目里有明确的领域概念，值对象都能派上用场。

原文链接 PHP 值对象实战指南：避免原始类型偏执

1. 重复出现的模式：不只是代码味道

在 PHP 项目里，某些规则会反复出现。日期就是典型例子：

public function registerEvent(string $eventDate, string $timeZone): void
{if (!preg_match('/^\d{4}-\d{2}-\d{2}$/', $eventDate)) {throw new InvalidArgumentException('Invalid date format.');}if (!in_array($timeZone, DateTimeZone::listIdentifiers())) {throw new InvalidArgumentException('Invalid time zone.');}// More logic here...
}

这里的日期和时区都用 string 表示。问题在于：一旦日期格式要改、或者时区规则有变化，你就会开始在各个角落复制粘贴同样的验证逻辑——漏一处就出事故。

2. 值对象登场：Date 和 TimeZone

与其在每个入口都手写校验，不如把“日期”“时区”做成值对象，让它们自己保证合法性。

2.1 Date 值对象

final class Date
{private string $value;private function __construct(string $date){if (!preg_match('/^\d{4}-\d{2}-\d{2}$/', $date)) {throw new InvalidArgumentException('Invalid date format.');}$this->value = $date;}public static function fromString(string $date): self{return new self($date);}public function value(): string{return $this->value;}public function __toString(): string{return $this->value;}
}

2.2 TimeZone 值对象

final class TimeZone
{private string $value;private function __construct(string $timeZone){if (!in_array($timeZone, DateTimeZone::listIdentifiers())) {throw new InvalidArgumentException('Invalid time zone.');}$this->value = $timeZone;}public static function fromString(string $timeZone): self{return new self($timeZone);}public function value(): string{return $this->value;}public function __toString(): string{return $this->value;}
}

2.3 在业务里怎么用

public function registerEvent(Date $eventDate, TimeZone $timeZone): void
{// No need for repetitive validation// Logic continues...
}

参数一眼就能看懂，而且验证逻辑只存在一份：在值对象里。

3. 给值对象加上行为

值对象不只是“更强的类型”。它还能承载和这个概念紧密相关的行为。

比如你需要判断活动日期是否在未来，可以把逻辑放进 Date：

final class Date
{// ..public function isInTheFuture(): bool{$now = new DateTime();$eventDate = new DateTime($this->value);return $eventDate > $now;}
}

这样就不用在每个用到日期的地方都重复写一遍比较逻辑，也更符合领域表达：判断未来与否，本来就是“日期”这个概念的一部分。

4. 金额：用值对象守住精度

处理金额是原始类型偏执最容易踩坑的地方之一。用 float 表示钱，舍入误差迟早会找上门；再加上币种、汇率，复杂度会迅速拉高。

把金额做成值对象，通常的做法是：

用最小单位（比如分）把金额存成 int
币种作为字段和金额绑定在一起

下面这个 Money 示例进一步加上了换汇的行为：

final class Money
{private int $amount; // Stored in minor units (e.g., cents)private string $currency;// Constructor and other methods...public function convertToCurrency(string $targetCurrency, float $exchangeRate): self{$convertedAmount = (int) round($this->amount * $exchangeRate);return new self($convertedAmount, $targetCurrency);}
}

把规则关在 Money 里，你的业务代码就不用到处关心“这里是分还是元”“币种对不对”“舍入怎么做”。

5. 在框架里落地

一旦你开始用值对象，Laravel / Symfony 反而会更好用：你能把“原始数据 ↔ 值对象”的转换放到框架扩展点里，业务层拿到的就都是领域类型。

5.1 Laravel 示例

Laravel 里可以用自定义 cast，把数据库字段自动转成值对象：

use Illuminate\Contracts\Database\Eloquent\CastsAttributes;class MoneyCast implements CastsAttributes
{public function get($model, string $key, $value, array $attributes){return Money::fromInt($value, 'USD');}public function set($model, string $key, $value, array $attributes){return $value instanceof Money ? $value->amount() : $value;}
}

把这个 cast 挂到 Eloquent 模型上后，取出来的就是 Money，而不是裸值，代码会干净很多。

5.2 Symfony 示例

Symfony 里可以用 Doctrine 的 embeddables 或自定义 DBAL type，把 Money / EmailAddress 这类复杂类型映射到数据库：

class MoneyType extends \Doctrine\DBAL\Types\Type
{const MONEY = 'money'; // Custom type namepublic function convertToPHPValue($value, \Doctrine\DBAL\Platforms\AbstractPlatform $platform){return Money::fromInt($value, 'USD');}public function convertToDatabaseValue($value, \Doctrine\DBAL\Platforms\AbstractPlatform $platform){return $value instanceof Money ? $value->amount() : $value;}
}

这样做的好处是：从数据库到领域层，你始终在用“领域类型”，而不是一堆无意义的 string/int/float。