更新日志 2.0.0 — 2025 年 6 月 27 日¶
v2系列首次发布！ 🎉
此版本引入了一些新功能，但也引入了向后兼容性中断，这些内容在升级章节中进行了详细介绍：强烈建议在升级之前仔细阅读。
值得注意的新功能¶
Mapper转换器介绍
映射器转换器允许用户通过定义正确描述何时应该调用的可调用签名来挂钩映射过程并将自定义逻辑应用于输入：
- 第一个参数的类型与映射的预期输入相匹配
- 表示目标映射类型的返回类型
这两种类型足以让库知道何时调用转换器，并且可以包含针对更具体用例的高级类型注释。
下面是将字符串输入转换为大写的转换器的基本示例：
(new \CuyZ\Valinor\MapperBuilder())
->registerConverter(
fn (string $value): string => strtoupper($value)
)
->mapper()
->map('string', 'hello world'); // 'HELLO WORLD'
转换器可以链接起来，允许对一个值应用多个转换。可以声明第二个callable参数，允许当前转换器调用链中的下一个。
可以给转换器赋予优先级以控制转换器的应用顺序。优先级越高，转换器越早执行。默认优先级为 0。
(new \CuyZ\Valinor\MapperBuilder())
->registerConverter(
function(string $value, callable $next): string {
return $next(strtoupper($value));
}
)
->registerConverter(
function(string $value, callable $next): string {
return $next($value . '!');
},
priority: -10,
)
->registerConverter(
function(string $value, callable $next): string {
return $next($value . '?');
},
priority: 10,
)
->mapper()
->map('string', 'hello world'); // 'HELLO WORLD?!'
更多信息可以在映射器转换器章节中找到。
NormalizerBuilder介绍
NormalizerBuilder类已经被引入，现在将成为实例化规范化器的主要入口。因此， MapperBuilder中用于配置和返回规范化器的方法已被删除。
此决定旨在明确区分映射器和规范化器配置 API，因为使用两者时可能会出现混淆。
NormalizerBuilder可以这样使用：
$normalizer = (new \CuyZ\Valinor\NormalizerBuilder())
->registerTransformer(
fn (\DateTimeInterface $date) => $date->format('Y/m/d')
)
->normalizer(\CuyZ\Valinor\Normalizer\Format::array())
->normalize($someData);
消息/错误处理的更改
对消息和错误的处理方式进行了一些更改。
现在，当映射期间发生错误时，可以更轻松地获取消息：
try {
(new \CuyZ\Valinor\MapperBuilder())->mapper()->map(/* … */);
} catch (\CuyZ\Valinor\Mapper\MappingError $error) {
// Before (1.x):
$messages = \CuyZ\Valinor\Mapper\Tree\Message\Messages::flattenFromNode(
$error->node()
);
// After (2.x):
$messages = $error->messages();
}
从 1.x 升级到 2.x ¶
⚠ 重大变更¶
- 在
MapperBuilder和NormalizerBuilder中添加纯度标记 ( 123058 ) - 将类型和源访问器添加到
MappingError( 378141 ) - 更改公开的错误消息代码（ 15bb11 ）
- 引入
NormalizerBuilder作为规范化器的主要入口（ f79ce2 ） - 引入内部缓存接口并删除 PSR-16 依赖 ( dfdf40 )
- 将一些类构造函数标记为
@internal( 7fe5fe ) - 删除
MapperBuilder::alter()以支持映射器转换器 ( bee098 ) - 删除
MapperBuilder::enableFlexibleCasting()( f8f16d ) - 删除未使用的类
PrioritizedList( 0b8c89 ) - 删除未使用的接口
IdentifiableSource( aefb20 ) - 将
MapperBuilder::warmup()方法重命名为warmupCacheFor()( 963156 ) - 返工映射器节点和消息处理（ 14d5ca ）
新功能¶
错误修复¶
- 更新文件系统缓存条目权限（ 6ffb0f ）