PHP filter_var 怎么区分验证失败和合法的 false

使用 filter_var($value, FILTER_VALIDATE_BOOLEAN) 时，合法的假值和验证失败默认都可能得到 false，因此不能只写 === false 判断失败。正确做法是追加 FILTER_NULL_ON_FAILURE：合法假值仍返回 false，无效输入改为返回 null，再用严格比较分别处理三种结果。

PHP 官方文档：https://www.php.net/manual/en/function.filter-var.php

布尔输入要按三态理解：true 表示合法真值，false 表示合法假值，null 表示无法识别。字段根本没有提交，则应在调用过滤器之前单独判断。

我遇到的误判是怎么产生的

我第一次在配置接口里用 filter_var 解析开关时，写的是最直觉的真假值判断。测试 "true" 正常，测试 "false" 却进入了错误分支；换成一段乱文本，结果看起来仍然一样。

问题不只是 if (!$enabled) 使用了宽松真假值。即使改成 $enabled === false，默认返回契约仍然无法区分两种含义：输入 "false" 是合法值，输入 "maybe" 是无法识别的值，但二者都可能返回布尔值 false。

先弄清哪些输入属于合法 false

FILTER_VALIDATE_BOOLEAN（也可写规范名称 FILTER_VALIDATE_BOOL）并不是只识别字符串 "true" 和 "false"。PHP 官方文档定义了多组可识别值，字符串比较不区分大小写。

这里最容易漏掉的是空字符串。对 PHP 的布尔验证过滤器来说，它是合法 false，不是天然的“缺少输入”。如果业务规定空字符串必须报错，就要在进入过滤器前加业务校验，不能期待过滤器替你做这个决定。

用 FILTER_NULL_ON_FAILURE 建立三态结果

修复并不复杂，只需要把第三个参数设为 FILTER_NULL_ON_FAILURE。官方文档规定：过滤失败默认返回 false，使用这个标志后改为返回 null。

同一个标志也可以放进选项数组。两种写法效果相同；当还需要传递过滤器选项时，数组形式更容易扩展。

 FILTER_NULL_ON_FAILURE,
    ]
);

var_dump($value); // 无效文本：NULL

判断时必须使用严格比较

有了三态返回后，下一步是别让 PHP 的类型转换再次把它们合并。false == null 在宽松比较下会产生容易误读的结果，if (!$value) 也会同时命中 false 和 null。最稳妥的做法是显式写出每种状态。

如果后续函数参数已经声明为 bool，也可以在排除 null 后直接返回结果。重点不是一定要写三段分支，而是验证失败必须在进入布尔业务逻辑前被单独移除。

字段缺失不能交给 filter_var 猜

表单和 JSON 接口还有第四种状态：字段根本不存在。它和“用户提交了 false”不是一回事，也不一定等于“用户提交空字符串”。如果直接写 $_POST['enabled'] ?? ''，缺失字段会被替换成空字符串，而空字符串恰好又是合法假值，语义就被抹平了。

是否拒绝空字符串取决于业务。HTML 复选框未勾选时，浏览器常常根本不提交字段；某些前端则会明确提交 "0" 或 "false"。后端应该先定义输入契约，再决定缺失、空值和假值各自代表什么。

为什么只看返回值会踩坑

filter_var 的返回类型是 mixed。验证过滤器成功时返回经过验证或转换的数据，失败时通常返回 false，或在启用标志后返回 null。这意味着通用的“只要是假值就失败”写法不可靠：

• 布尔过滤器的合法结果本来就可能是 false；
• 整数过滤器的合法结果可能是 0；
• 空字符串在布尔过滤器里是合法假值，但在业务协议里可能不合法；
• 默认过滤器 FILTER_DEFAULT 实际是 FILTER_UNSAFE_RAW 的别名，不会自动完成验证。

因此我现在会先确认所选过滤器可能返回哪些合法值，再选择一个不会与合法数据冲突的失败哨兵，并坚持严格比较。对于布尔过滤，null 正好承担这个角色。

用测试矩阵把契约固定下来

布尔解析很适合用表驱动方式覆盖。测试不需要依赖 HTTP 环境，直接给解析函数传入原始值即可。

 ['true', true],
    'yes 文本'   => ['yes', true],
    'false 文本' => ['false', false],
    '零字符串'   => ['0', false],
    '空字符串'   => ['', false],
    '无效文本'   => ['maybe', null],
];

foreach ($cases as $name => [$raw, $expected]) {
    $actual = filter_var(
        $raw,
        FILTER_VALIDATE_BOOLEAN,
        FILTER_NULL_ON_FAILURE
    );

    // 严格比较同时校验值和类型，避免 false 与 null 被认为相同。
    if ($actual !== $expected) {
        throw new RuntimeException($name . ' 的解析结果不符合预期');
    }
}

如果你的业务拒绝空字符串，就不要把它放在过滤器成功用例中，而应单独测试包装函数抛出异常。测试矩阵表达的是业务契约，不能机械照搬过滤器的全部默认语义。

几个常见问题

FILTER_VALIDATE_BOOL 和 FILTER_VALIDATE_BOOLEAN 有区别吗？

没有行为差异。FILTER_VALIDATE_BOOLEAN 是别名；PHP 8.0 引入规范名称 FILTER_VALIDATE_BOOL，旧名称仍可使用。团队可以按最低支持版本和代码风格统一一种写法。

为什么不能直接用 (bool)$raw？

强制类型转换遵循 PHP 自身的真假值规则，字符串 "false" 是非空字符串，会被转成 true。它不是协议文本验证器，不能替代 FILTER_VALIDATE_BOOLEAN。

FILTER_NULL_ON_FAILURE 会把合法 false 变成 null 吗？

不会。它只改变“过滤失败”的返回值。"false"、"0"、"off"、"no" 和空字符串仍返回布尔值 false。

缺失字段应该返回 false 还是报错？

这由接口契约决定。更新接口可能把缺失解释为“不修改”，创建接口可能要求必填。无论采用哪种规则，都应先用 array_key_exists 区分缺失，再决定默认值或错误，不要先替换成空字符串。

结论

区分 filter_var 的验证失败和合法 false，关键是把默认二态返回改成三态：给 FILTER_VALIDATE_BOOLEAN 增加 FILTER_NULL_ON_FAILURE，然后用 === null 判断失败、用 === false 识别合法假值。字段缺失和空字符串是否允许，则应在业务层独立判断。这样布尔开关、表单字段和配置参数就不会因为 PHP 的宽松真假值规则而丢失语义。