PHP VarDumper怎么为业务对象定义简洁展示

为 VarDumper 里的业务对象定义简洁展示，可以给 VarCloner 注册该类的 caster：只返回需要观察的摘要字段，再让 dumper 输出克隆后的 Data。这比直接展开整个订单对象更容易定位状态，也不要求把调试规则写进领域模型。

官方地址：https://symfony.com/doc/current/components/var_dumper.html

用一个订单摘要 caster 替换完整属性树

下面示例使用 PHP 8.1 及以上语法，以及 Composer 安装的 symfony/var-dumper。订单模型仅保存本地值；没有数据库查询、网络访问或懒加载关联。示例是可复制的写法说明，本文未执行它，也不提供伪造的输出截图。

 $this->orderNo,
            'status' => $this->status,
            'lineCount' => count($this->lines),
        ];
    }
}

$cloner = new VarCloner();
$cloner->addCasters([
    OrderView::class => static function (
        OrderView $order,
        array $properties,
        Stub $stub,
        bool $isNested,
        int $filter
    ): array {
        // 返回新的白名单数组，不把原始属性树合并回来。
        $summary = [];
        foreach ($order->debugSummary() as $name => $value) {
            $summary[Caster::PREFIX_VIRTUAL . $name] = $value;
        }
        return $summary;
    },
]);

// 原创演示数据不包含账号、凭据或个人信息。
$order = new OrderView('DEMO-ORDER', 'draft', [['sku' => 'DEMO-SKU']]);
$data = $cloner->cloneVar($order);
$dumper = new CliDumper();
$dumper->dump($data);

此设计把订单对象 OrderView、摘要 caster 和 VarCloner 分开。orderNo、status、lineCount 是本文定义的三个展示字段，并非 VarDumper 自带的订单能力。读者可以把它们替换为自己模型中已经存在、读取成本明确的标量。

返回数组会不会改动原对象

返回数组是在定义调试表示，不是在给订单赋值。例子没有修改对象或传入的 Stub。为了保持这种性质，摘要方法也必须只读；如果 getter 会触发加载、更新缓存或发请求，换一个名字并不会让它变得无副作用。

不用手写包含空字节的属性前缀，直接使用组件常量即可。参数 $isNested 和 $filter 可以用于更复杂的上下文策略，本例不使用它们；不要在没有实现策略时宣称它会自动按场景脱敏。

为什么全局 dump 没有使用这个 caster

本例显式使用自己创建的 cloner 和 dumper。随后在别处调用全局 dump($order)，不会因为这里注册过 caster 就自动共享该实例配置。先区分两条入口：本文的自定义 VarCloner 配置，与全局 dump 的默认处理器。

为了减少隐藏行为，项目中可以把这段显式配置封装为仅在开发环境使用的展示服务，再让调用方明确使用它。若决定接管全局处理器，必须把作用范围、输出目的地以及原配置恢复责任一起设计；不应仅为一个对象把所有调试输出改向不可见位置。

简洁展示不等于敏感数据已经安全

只对订单这一类注册白名单 caster，不能覆盖请求对象、异常上下文、其他日志或原始数组。尤其不要把凭据塞进另一个字段后认为折叠或截断就足够。本文的摘要模型不持有敏感数据，实际项目也应从收集源头减少不必要的内容。

展示服务不要保存每次传入的对象，也不要把调试结果当成持久业务事件。长驻 worker 中的配置应在明确的启动阶段建立，避免每处理一条消息就追加 caster。摘要字段数应有上限，返回整个关联集合会重新引入想要消除的噪声。

常见问题

什么时候用 __debugInfo()？PHP 的这个魔术方法允许类自身定义供调试使用的属性数组。你拥有该类且愿意把通用调试语义放进模型时可以考虑它；需要独立于业务类、只针对某个展示入口配置时使用 caster 更合适。

它和 __serialize() 是同一个接口吗？不是。__serialize() 服务于 PHP 序列化表示，__debugInfo() 服务于调试观察。不要为了让 dump 好看去更改持久化或传输契约。

把对象转成 JSON 能替代 caster 吗？可以专门生成一个摘要数组用于日志，但那是另一个数据契约。不能假定 JSON 输出、序列化输出与 VarDumper 展示永远包含同样字段。

最小原则是：让摘要字段少、读取动作只读、配置范围明确。调试展示服务负责“看什么”，领域模型仍负责“是什么”，二者不要混为一套业务数据接口。

参考：Symfony VarDumper 文档 https://symfony.com/doc/current/components/var_dumper.html；PHP 魔术方法手册 https://www.php.net/manual/en/language.oop5.magic.php。