Respect\Validation Odd 校验器完全指南:奇数验证原理、模板定制与实战最佳实践
Respect\Validation Odd 校验器完全指南:奇数验证原理、模板定制与实战最佳实践
本篇技术指南聚焦 Respect\Validation(PHP 校验引擎)中的 Odd() 校验器,围绕 Odd.md 文档展开,深入讲解其基本用法、底层实现原理、与 intVal() 组合的最佳实践、模板消息定制以及相关校验器(Even、Multiple)的联动方式。读完本文,你将能熟练运用 Odd() 完成奇数校验,理解其严格的整数判定逻辑,并掌握如何定制失败消息与实现反转语义。
一、Odd 校验器是什么
Odd() 用于验证输入是否为奇数(odd number),是 Respect\Validation 中归类于 Numbers 分类下的基础数值校验器之一(参见 validators.md 的 Numbers 分类列表)。
官方文档给出了最直接的两个示例:
v::odd()->assert(3);
// Validation passes successfully
v::odd()->assert(0);
// → 0 must be an odd number
第一个示例中,3 是奇数,断言通过;第二个示例中,0 不是奇数,assert() 抛出异常并携带默认消息 0 must be an odd number。
二、基本用法:三种调用方式
与 Respect\Validation 的其他校验器一致,Odd() 支持通过 ValidatorBuilder(别名 v)以流式(fluent)方式构建。根据 getting-started.md,主要有三种调用形态:
1. 异常断言模式(assert())
try {
v::odd()->assert($input);
} catch (Throwable $exception) {
echo 'Validation failed: ' . $exception->getMessage();
}
校验失败时抛出异常,消息即模板渲染结果(如 2 must be an odd number)。
2. 结果查询模式(validate())
$result = v::odd()->validate($input);
if ($result->hasFailed()) {
echo 'Validation failed: ' . $result->getMessage();
}
该模式不抛异常,返回 ResultQuery 对象供程序化检查。
3. 布尔模式(isValid())
if (!v::odd()->isValid($input)) {
echo 'The input you gave me is not an odd number';
}
注意:isValid() 是校验器实例直接暴露的底层方法(来自 Validator 接口),而 v::odd() 返回的是校验器实例本身,因此也可以直接调用:
(new Odd())->isValid(3); // true
三、底层实现原理:源码级解析
从源码结构看,Odd 是一个继承了 Simple 抽象基类的无参校验器,位于 src/Validators/Odd.php:
final class Odd extends Simple
{
public function isValid(mixed $input): bool
{
if (!is_numeric($input)) {
return false;
}
if (!filter_var($input, FILTER_VALIDATE_INT)) {
return false;
}
return (int) $input % 2 !== 0;
}
}
其判定逻辑分为三步:
- 数字性检查:通过
is_numeric($input)排除非数字输入。字符串形式的数字(如"11")可以进入下一步,而数组、对象、布尔值等在此被拦截。 - 整数性检查:通过
filter_var($input, FILTER_VALIDATE_INT)排除小数、含非数字字符的字符串等。这一步保证了只对真正的整数做奇偶判断,呼应了 Changelog 中 "2.0.0 起仅验证整数" 的版本变更(详见下文)。 - 奇偶判断:将输入强转为
int后对 2 取模,% 2 !== 0即余数为 1(或 -1)时判定为奇数。
一个值得注意的实现细节是:由于步骤 2 使用了 !filter_var(...) 这一非严格判断,当输入为 0 时,filter_var(0, FILTER_VALIDATE_INT) 返回整数 0,而 !0 为 true,因此 0 会被 Odd 直接判定为无效。这与文档示例 v::odd()->assert(0) 失败完全吻合,也说明该校验器不把 0 视为奇数(数学上 0 是偶数)。
Simple 基类(src/Validators/Core/Simple.php)将 evaluate() 委托给 isValid(),并借助 Result::of() 生成携带输入值和校验器引用的 Result 对象,供异常消息与结果查询使用。
与 Even 的边界差异
对比同类校验器 Even(src/Validators/Even.php)可以发现实现上的微妙差别:Even 使用 filter_var($input, FILTER_VALIDATE_INT) === false 作为严格判断,因此 0 能通过整数检查并被判定为偶数;而 Odd 的 !filter_var(...) 写法使 0 被拒绝。也就是说,Odd 的有效输入集合是正奇数与负奇数,而 Even 接受 0 及一切偶数。
四、最佳实践:先 intVal 再 odd
Odd.md 明确指出:在 odd() 之前使用 intVal() 是一种最佳实践。
v::intVal()->odd()->assert(7); // 通过
v::intVal()->odd()->assert('11'); // 通过(intVal 接受纯数字字符串)
v::intVal()->odd()->assert(2.5); // 失败:2.5 must be an integer
推荐的组合是:
v::intVal()->odd()->assert(3);
之所以推荐这样做,是因为 Odd 虽然内部自带整数检查,但其失败消息(如 2.5 must be an odd number)语义不够精确。加上 intVal() 前置校验后,非整数输入会先触发更明确的类型错误({{subject}} must be an integer),让报错更贴近问题本质。
从 IntVal 文档 可以看出,intVal() 对整数的定义比 PHP 原生强转更严格:它接受原生 int 以及匹配 /^-?\d+$/ 的字符串(如 "10"、"089"、"0b101010" 对应的数值),但拒绝 true、"89a" 这类 PHP 虽可强转却含非整数语义的输入。因此 intVal()->odd() 组合既保证了类型安全,又不排斥常见的字符串数字表单输入。
五、模板定制与消息渲染
5.1 标准模板 Odd::TEMPLATE_STANDARD
Odd 的默认消息由 #<a href="https://link.gitcode.com/i/e2ec765478983ecb2a2dc04f79886a92" target="_blank">Template] 特性定义([src/Validators/Odd.php),标准模板对应两种模式:
| Mode | Template |
|---|---|
default |
{{subject}} must be an odd number |
inverted |
{{subject}} must be an even number |
default模式:校验失败时的消息,如2 must be an odd number。inverted模式:当校验器被Not反转时使用的消息,例如v::not(v::odd())失败时会输出7 must be an even number(参见 feature 场景测试)。
5.2 模板占位符
| Placeholder | Description |
|---|---|
subject |
The validated input or the custom validator name (if specified). |
{{subject}} 会渲染为被校验的实际输入值;若为校验器指定了自定义名称(通过 named() 等机制),则渲染为自定义名称。这使同一模板可复用于不同字段。
5.3 反转语义实战
利用 Not 包裹可实现"必须是偶数"的语义表达,同时自动切换为 inverted 模板:
v::not(v::odd())->assert(2); // 通过
v::not(v::odd())->assert(7); // 失败:7 must be an even number
feature 测试 中的 4 个场景完整覆盖了这两类消息与完整消息(- 2 must be an odd number 这种带前缀的格式)的渲染行为。
六、边界输入行为与测试佐证
单元测试(RuleTestCase 数据驱动)给出了官方的有效/无效输入边界:
有效输入:-5、-1、1、13 —— 即所有正负奇数整数。
无效输入:
- 非数值类型:
[](数组)、new stdClass()(对象)、tmpfile()(资源)、true/false(布尔)、''(空字符串); - 非奇数整数:
-2、-0、0、32。
这些用例印证了源码中的三步判定逻辑:非数字直接拒绝;0 与 -0 因 !filter_var(...) 被拒绝;偶数被取模判断拒绝。
七、相关校验器联动
Odd 文档的 See Also 部分指向两类紧密相关的校验器:
7.1 Even(偶数校验)
Even 文档 与 Odd 互为镜像,官方示例为:
v::intVal()->even()->assert(2);
// Validation passes successfully
在需要"奇数/偶数二选一"的规则(如分单双号的业务场景)中,可结合 OneOf 或 Not 灵活组合:
// 确保输入是整数,且奇偶二选一
v::intVal()->oneOf(v::odd(), v::even())->assert($input);
7.2 Multiple(倍数校验)
Multiple 文档 用于验证输入是否为某数的倍数,签名形如 Multiple(int $multipleOf):
v::intVal()->multiple(3)->assert(9);
// Validation passes successfully
Odd 本质上是"对 2 取模不为 0",与 multiple() 的取模思路一脉相承;在需要"奇数且是 3 的倍数"等复合条件时可链式组合:
v::intVal()->odd()->multiple(3)->assert(9); // 9 是奇数,也是 3 的倍数,通过
v::intVal()->odd()->multiple(3)->assert(15); // 15 是奇数,也是 3 的倍数,通过
v::intVal()->odd()->multiple(3)->assert(6); // 6 不是奇数,失败
八、版本变更历史与兼容性
根据 Odd.md 的 Changelog:
| Version | Description |
|---|---|
| 2.0.0 | Only validates integers |
| 0.3.9 | Created |
- 0.3.9:校验器首次创建。
- 2.0.0:行为收紧为"仅验证整数"。这一变更与当前源码中
is_numeric+FILTER_VALIDATE_INT的双重检查相对应——自该版本起,小数值、含非数字字符的字符串等不再被视为可判定的输入。
在当前仓库(v3 系列)中,Odd 被实现为带 #<a href="https://link.gitcode.com/i/64e72fef091e3daf8b75020b85709b26" target="_blank">Attribute(Attribute::TARGET_PROPERTY | Attribute::IS_REPEATABLE)] 特性的类,意味着它也可直接作为 PHP 8 原生属性(Attribute)应用于类属性上,实现声明式校验。此外,其 #[Composable(with: [Length::class, Max::class, Min::class])] 声明([src/Validators/Odd.php)表明在构建链上它与 Length、Max、Min 等校验器具有可组合性,可安全地与其他数值类校验器链式拼接。
九、小结
Odd() 是 Respect\Validation 中实现简洁、行为明确的数值校验器:
- 只接受整数输入,正负奇数均通过,
0被拒绝; - 推荐与
intVal()组合以获得更精确的类型错误消息; - 通过
#[Template]与Not反转机制,可自动获得"必须是奇数/必须是偶数"两套语义消息; - 与
Even、Multiple等校验器可无缝链式组合,覆盖奇偶与倍数等常见数学规则。
掌握 Odd() 的底层判定细节(尤其是 !filter_var(...) 导致 0 被拒的行为差异),能帮助你在实际业务中准确预判校验结果,写出更严谨的验证规则。