使用 Respect Validation 的 Roman 校验器验证罗马数字:正则原理、模板定制与实战用例
使用 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 与其测试为参照,将它灵活复用到任何需要罗马数字约束的项目场景中。