PHP 8.5 FILTER_THROW_ON_FAILURE 怎样把校验失败转成异常

PHP 8.5 的 FILTER_THROW_ON_FAILURE 解决的是一个很具体的输入校验问题：以前 filter_var() 校验失败通常返回 false，配合 FILTER_NULL_ON_FAILURE 时还可能返回 null；现在可以让失败直接进入异常路径。它不会改变邮箱、整数或 URL 等过滤器的判断规则，只改变失败结果的表达方式。

官方地址：https://www.php.net/

如果项目已经使用 PHP 8.5，可以把 FILTER_THROW_ON_FAILURE 放到 filter_var() 的第三个参数中，并在输入适配层捕获 Filter\\FilterException。成功仍返回过滤后的值，失败才抛异常；不要把它误解成“所有错误都自动变成业务异常”。

这个标志到底改变了什么

filter_var() 仍然接收值、过滤器和选项三个核心参数。比如 FILTER_VALIDATE_EMAIL 负责判断邮箱格式，FILTER_THROW_ON_FAILURE 只负责规定“判断失败后怎么通知调用方”。这样可以把格式判断和错误处理分开。

把标志放在正确的参数位置

下面用整数校验演示完整调用。第三个参数可以直接传整数标志，也可以传带有 flags 键的选项数组；两种写法表达的是同一类控制。示例把异常捕获限制在输入适配函数中，调用方只接收一个明确结果。

这个例子里，'3' 会得到整数 3；像 '3.5' 这样的输入会触发过滤器异常，再被转换成调用方更容易理解的参数异常。注意，正数检查仍然属于业务边界，所以不能只依赖过滤器。

直接传标志和传 options 数组有什么区别

当过滤器只需要一个异常标志时，第三个参数直接传 FILTER_THROW_ON_FAILURE 最短；当同时需要过滤器自己的选项或其他标志时，使用数组更清晰。不要把标志误放到第二个参数，也不要把 FILTER_THROW_ON_FAILURE 和 FILTER_NULL_ON_FAILURE 当成同一条路径。

 [
            'min_range' => 1,
            'max_range' => 65535,
        ],
        'flags' => FILTER_THROW_ON_FAILURE,
    ];

    try {
        // 端口越界或格式错误都会进入同一个过滤器异常入口。
        return filter_var($raw, FILTER_VALIDATE_INT, $options);
    } catch (\\Filter\\FilterException $e) {
        // 保留前一个异常作为原因，便于上层统一记录。
        throw new InvalidArgumentException('端口必须是 1 到 65535 的整数', 0, $e);
    }
}

数组的价值不在于“更强”，而在于把范围选项和异常策略放在同一份配置里。若项目还要兼容 PHP 8.4 或更早版本，应先确认运行环境，不要只在代码里写入新常量。

成功、异常和 null 返回要分开判断

旧代码常见的写法是用严格比较判断 false，或者用 FILTER_NULL_ON_FAILURE 把“失败”表达成 null。启用 FILTER_THROW_ON_FAILURE 后，失败不再返回这两个值，而是抛出过滤器异常；因此迁移时要删除会遮住异常的错误分支，或明确保留一套旧兼容路径。

这里的默认值是业务决定，不是 FILTER_THROW_ON_FAILURE 自动提供的。若“缺失”和“格式错误”在业务上意义不同，不要在一个 catch 里无条件吞掉两者。

把异常边界放在输入适配层

更稳妥的组织方式是：HTTP、命令行或配置文件入口负责把字符串变成类型化值；领域服务只接收已经完成格式校验的数据。这样既能使用 PHP 8.5 的异常模式，也不会让每个业务方法都重复理解过滤器标志。

迁移前后的最小检查清单

1. 确认运行环境确实是 PHP 8.5，并检查部署机、CLI 和 FPM 使用的版本是否一致。
2. 确认 FILTER_THROW_ON_FAILURE 放在 filter_var() 的第三个参数，或放在 options 数组的 flags 中。
3. 确认捕获的是 Filter\\FilterException，并在捕获后保留原因链而不是静默吞错。
4. 确认代码没有再把新模式当成 false 或 null 返回模式处理。
5. 确认过滤器通过后仍然执行业务范围检查，例如正数、长度或允许值集合。

PHP 官方资料：

• https://www.php.net/manual/en/migration85.new-features.php
• https://www.php.net/manual/en/function.filter-var.php
• https://www.php.net/manual/en/filter.constants.php

常见问题

FILTER_THROW_ON_FAILURE 会改变 FILTER_VALIDATE_INT 的判断规则吗？

不会。它只改变失败时的通知方式，过滤器本身仍按原有规则判断输入。

还能同时使用 FILTER_NULL_ON_FAILURE 吗？

不应把两种失败策略叠加成一条含义不清的路径。需要异常时使用 FILTER_THROW_ON_FAILURE；需要返回 null 的旧接口则保留旧策略，并在边界处明确区分。

过滤器抛异常后还需要做业务校验吗？

需要。过滤器通常负责格式或基础类型，正数、权限、状态和业务范围仍应由输入适配层或领域规则单独处理。

总结来看，PHP 8.5 的 FILTER_THROW_ON_FAILURE 适合用来收紧输入适配层的错误信号：成功返回值，失败进入异常，业务层再根据需要映射成参数错误或接口响应。迁移时最重要的不是机械替换常量，而是把旧的 false/null 分支、异常捕获和后续业务约束重新放回清晰的边界中。