使用 Respect Validation 的 Roman 校验器验证罗马数字:正则原理、模板定制与实战用例

原创2026-10-09 14:34:101,674 阅读
文章标签:后端开发工具

使用 Respect Validation 的 Roman 校验器验证罗马数字:正则原理、模板定制与实战用例

导读

Roman 是 Respect Validation(PHP 验证引擎)中专门用于校验"输入是否为合法罗马数字"的校验器,适用于表单章节编号、年份/日期展示、历史文档元数据等需要严格限定罗马数字格式的场景。读完本文,你将掌握 v::roman() 的调用方式、其底层基于正则的判定规则与边界行为、默认错误消息模板与占位符的定制方法,以及如何通过单元测试与特性测试理解它的精确语义。

快速上手:一行代码完成罗马数字校验

按 getting-started 完成安装后,即可直接调用 Roman 校验器。其使用形式与 官方文档 中的示例一致:

v::roman()->assert('IV');
// Validation passes successfully

assert() 在验证失败时会抛出异常(默认抛出 Respect\Validation\Exceptions\ValidationException,参见 handling-exceptions);若只想获得布尔结果而不抛异常,可使用 validate():

var_dump(v::roman()->validate('IV'));   // bool(true)
var_dump(v::roman()->validate('IIII')); // bool(false)

Roman 也支持与链式 API 组合使用。例如结合 v::not() 做反向断言,这正是 特性测试 中验证过的场景:

v::not(v::roman())->assert('XL');
// Validation passes successfully("XL" 不是合法罗马数字的反向断言失败时才抛出异常)

源码剖析:一个 Envelope 包裹的正则校验器

Roman 的实现非常精巧——它本身不写任何判定逻辑,而是通过继承 Envelope 将 Regex 校验器"包裹"起来。查看 src/Validators/Roman.php 可以看到其完整构造逻辑:

final class Roman extends Envelope
{
    public function __construct()
    {
        parent::__construct(new Regex('/^(?=[MDCLXVI])M*(C[MD]|D?C{0,3})(X[CL]|L?X{0,3})(I[XV]|V?I{0,3})$/'));
    }
}

Envelope 的构造签名(src/Validators/Core/Envelope.php)接收内部校验器、参数与模板;其 evaluate() 方法先让内部 Regex 校验器计算通过/失败,再用 Result::of(...) 包一层结果并挂上当前校验器与模板。Roman 因此获得了自己独立的错误消息模板,而不使用底层 Regex 的模板。

底层 Regex::evaluate()(src/Validators/Regex.php)有两点值得注意:

  • 输入必须是标量(is_scalar($input)),非标量(数组、对象等)直接判定失败;
  • 匹配判定基于 preg_match($this->regex, (string) $input) === 1,即输入会被强制转为字符串后做整体匹配。

所以 v::roman()->assert(1234) 传入整数时,会被转成字符串 '1234' 后参与正则匹配并失败——特性测试 Scenario #1 精确断言了该场景抛出的消息为 '1234 must be a Roman numeral'。

正则逐段拆解

Roman 使用的正则对罗马数字语法做了严谨约束,可拆解为四段:

片段 作用
(?=[MDCLXVI]) 正向先行断言:首字符必须是罗马数字字符 M、D、C、L、X、V、I 之一
M* 千位:任意数量的 M
(C[MD]|D?C{0,3}) 百位:CM/CD 这类减形式,或 D 后接 0~3 个 C(如 DCCC)
(X[CL]|L?X{0,3}) 十位:XC/XL 减形式,或 L 后接 0~3 个 X(如 LXXX)
(I[XV]|V?I{0,3}) 个位:IX/IV 减形式,或 V 后接 0~3 个 I(如 VIII)

配合 ^ 与 $ 锚点,该正则实现了严格的"加法 + 减法"规则,并刻意排除了 IIII、VX、MIM 等不符合规范书写的组合(详见下文测试证据)。

边界行为:哪些输入会被判为非法

从 单元测试 的 providerForValidInput 与 providerForInvalidInput 两组数据中,可以完整还原校验器的判定边界:

合法输入(12 组):III、IV、VI、XIX、XLII、LXII、CXLIX、CLIII、MCCXXXIV、MMXXIV、MCMLXXV、MMMMCMXCIX。

非法输入(8 组):

输入 非法原因
'' 空字符串——Changelog 明确记录 2.0.0 起空串不再被视为合法
' ' 空白字符不匹配字符类
IIII I 重复超过 3 次(个位组 V?I{0,3} 拒绝)
IVVVX V 出现 3 次且位置错乱
CCDC 百位组不允许 C 与 D 混排超过约束
MXM 减形式 XM 不在允许的组合内
XIIIIIIII I 大量超限重复
MIMIMI MI 减形式不在个位允许的 I[XV] 之列

需要特别说明:MMMMCMXCIX(4999)是合法输入,说明千位 M* 是开放的、不限 3999 上限;同时字符串必须整体匹配,任何非罗马字符(如 'e2')都会失败。

错误消息模板与占位符定制

Roman 通过 #<a href="https://link.gitcode.com/i/5b97f280d519a8f925ee0284848b0ae1" target="_blank">Template] 属性([src/Validators/Roman.php)声明了默认与反转两种模式的消息模板,对应 src/Validator.php 中定义的 Validator::TEMPLATE_STANDARD:

模式 模板
default {{subject}} must be a Roman numeral
inverted {{subject}} must not be a Roman numeral

模板支持 {{subject}} 占位符,其含义为:被校验的原始输入,或你通过命名机制自定义的校验器名称。关于占位符的转换与自定义修饰符机制,可参见 placeholder-conversion。

特性测试给出了三种典型的消息形态:

  • v::roman()->assert(1234) → '1234 must be a Roman numeral'(整数原样输出);
  • v::not(v::roman())->assert('XL') → '"XL" must not be a Roman numeral'(字符串带引号、使用 inverted 模板);
  • 多个校验器叠加时,catchFullMessage 会得到带 - 前缀的完整消息列表,如 - "e2" must be a Roman numeral(Scenario #3)。

若需自定义消息,可通过 setTemplate() 替换模板,或使用 translation 文档中描述的容器注入方式为 TemplateRegistry 注册多语言模板;Roman 的模板消息 {{subject}} must be a Roman numeral 也可以作为翻译键直接覆盖。

分类与相关校验器

在 validators 索引 中,Roman 被归类为 Numbers(数字类校验器)。与之配合使用的相关校验器及其文档位置如下:

  • In:限定输入必须在给定集合内;
  • Regex:Roman 的底层实现依赖,适用于任意自定义正则校验;
  • Uppercase:罗马数字通常以大写书写,可与其组合约束大小写;
  • Version:校验语义化版本号,与罗马数字同属"格式型字符串校验"。

例如组合用法:

v::uppercase(v::roman())->assert('MCMXC');

Changelog:版本演进揭示的行为变化

官方文档(docs/validators/Roman.md)的 Changelog 记录了校验器的演进历史,也解释了前文提到的若干行为差异:

版本 变更
3.0.0 模板系统重构(引入 TEMPLATE_STANDARD 与 #[Template] 属性机制)
2.0.0 异常消息由 "numbers" 改为 "numerals",措辞更精确
2.0.0 空字符串不再被视为合法罗马数字
0.3.9 校验器首次创建

这意味着在 v3 之前版本中,v::roman()->validate('') 的行为与当前版本不同——升级到 v3 时需要注意这一破坏性变更(完整的迁移指南见 migrating-from-v2-to-v3)。

总结

Roman 校验器是 Respect Validation 中"薄封装 + 正则内核"设计风格的典型代表:通过 Envelope 包裹 Regex,以一条严谨的正则同时实现了格式校验、独立模板与结果包装。无论是快速接入表单校验,还是深入理解模板定制与边界语义,都可以以 src/Validators/Roman.php 与其测试为参照,将它灵活复用到任何需要罗马数字约束的项目场景中。

登录后查看全文
Validation