Respect\Validation Odd 校验器完全指南:奇数验证原理、模板定制与实战最佳实践

原创2026-10-09 13:22:361,819 阅读
文章标签:后端开发工具

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;
    }
}

其判定逻辑分为三步:

  1. 数字性检查:通过 is_numeric($input) 排除非数字输入。字符串形式的数字(如 "11")可以进入下一步,而数组、对象、布尔值等在此被拦截。
  2. 整数性检查:通过 filter_var($input, FILTER_VALIDATE_INT) 排除小数、含非数字字符的字符串等。这一步保证了只对真正的整数做奇偶判断,呼应了 Changelog 中 "2.0.0 起仅验证整数" 的版本变更(详见下文)。
  3. 奇偶判断:将输入强转为 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 被拒的行为差异),能帮助你在实际业务中准确预判校验结果,写出更严谨的验证规则。

登录后查看全文
Validation