PHP SensitiveParameter 怎么隐藏堆栈中的敏感值

PHP 应用把密码、访问令牌或签名密钥作为函数参数时，异常堆栈可能把调用参数一起记录下来。PHP 8.2 提供的 #[\\SensitiveParameter] 适合处理这一类泄露：被标记的参数在 stack trace 中会显示为 SensitiveParameterValue 对象，而不是原始字符串。

先给结论：把属性写在真正接收敏感值的参数前面，只能保护异常堆栈中的参数展示；它不会加密变量，也不会自动清理你主动写入日志、响应体或调试输出的原始值。

先复现未标记参数为什么会出现在异常堆栈

下面的示例故意抛出异常，重点不是业务逻辑，而是观察函数调用参数在异常文本中的表现。代码中的注释说明了异常入口和清理边界。

当异常处理器输出完整调用栈时，未标记的 token-demo-123 可能随着调用参数暴露。即使当前日志格式没有显示它，也不要把安全性建立在某个 formatter 的偶然行为上。

在接收参数的位置添加 SensitiveParameter

属性放在参数声明之前即可。命名空间完整写法是 \\SensitiveParameter；如果当前文件已经导入对应属性，也可以按项目规范使用短名称。

官方示例的关键现象是：堆栈中的参数位置仍然存在，但值变为 Object(SensitiveParameterValue)。这让开发者知道参数参与了调用，同时避免把原始值直接写进异常文本。

理解自动包装与手动包装的边界

SensitiveParameterValue 是 PHP 用于保护敏感值的对象。属性标记的是参数位置，不是把函数内部的变量变成不可读取的密文；因此业务逻辑仍能用 $token 调用下游服务。只有在异常堆栈等调试展示路径中，PHP 才会替换它的可见形式。

getValue();
sendToProfileService($token);

// 不要这样记录：这会主动绕过堆栈保护，把原始值写入日志。
// error_log($token);

上线前按边界检查，而不是只搜索属性

• 确认生产 CLI、FPM 和队列 worker 都运行 PHP 8.2 或更高版本。
• 在密码、令牌、签名密钥进入控制器、客户端或服务层的第一处参数声明上加属性。
• 检查异常消息、var_dump、请求日志和 APM 参数采集是否仍主动记录原值。
• 对第三方库调用保留脱敏边界，不能假设库内部会继承你的参数属性。
• 用测试异常确认堆栈显示对象占位，而不是把真实凭证提交到测试日志。

常见问题

这个属性会把密码加密吗？

不会。它主要改变敏感参数在异常堆栈中的展示方式，加密、存储和传输仍要由密码哈希、密钥管理和 TLS 等方案负责。

给变量加属性能保护所有日志吗？

不能。属性针对参数和堆栈展示；如果代码把原值写入日志、异常消息、响应或调试输出，仍会暴露。

为什么堆栈里看到的是对象而不是星号？

这是 PHP 用 SensitiveParameterValue 表达“这里有敏感参数”的方式，既保留调用结构，又避免直接展示原始内容。

把 #[\\SensitiveParameter] 当作异常堆栈的最后一道防线更合适：先标记参数入口，再收紧日志和 APM 的采集范围。这样既能保留排查所需的调用关系，也不会把一次异常变成凭证泄露点。