PHP OptionsResolver怎么限制选项类型和允许值

我在给 PHP 组件封装配置时，最容易混在一起的是“这个选项应该是什么类型”和“这个类型里哪些值可以用”。OptionsResolver 的分工很清楚：用 setAllowedTypes() 限制输入形状，用 setAllowedValues() 限制枚举或业务规则，最后由 resolve() 统一解析并在不符合约束时抛出异常。

官方地址：https://symfony.com/doc/current/components/options_resolver.html

下面以 Symfony OptionsResolver 组件为例。官方组件页当前列出的安装方式是 composer require symfony/options-resolver；如果项目还没有这个依赖，先按项目的 Composer 约束安装。

先把默认值、类型和值约束放在一起

一个可维护的配置定义，通常先给出默认值，再声明类型和值的边界。类型约束解决“输入是不是字符串、整数或数组”，值约束解决“字符串是不是允许的模式”。

setDefaults([
            // 没有传入时使用稳定的默认配置。
            'format' => 'json',
            'limit' => 100,
            'columns' => null,
        ]);

        // 先约束输入形状，避免后面的值规则收到错误类型。
        $resolver->setAllowedTypes('format', 'string');
        $resolver->setAllowedTypes('limit', 'int');
        $resolver->setAllowedTypes('columns', ['null', 'array']);

        // 再约束字符串只能取这两个业务值。
        $resolver->setAllowedValues('format', ['json', 'csv']);

        return $resolver->resolve($input);
    }
}

$options = ReportOptions::resolve([
    'format' => 'csv',
    'limit' => 50,
]);

这里的关键不是把规则写得越多越好，而是让调用方一眼看出每个字段的契约：format 必须是字符串且只能是 json 或 csv，limit 必须是整数，columns 则允许为空或数组。

setAllowedTypes 负责限制输入形状

setAllowedTypes() 可以接收一个类型名或多个类型名。常见类型包括 string、int、bool、array；也可以传入完整的类名或接口名，让 OptionsResolver 使用 instanceof 判断。

如果一个选项允许多种类型，可以使用数组写法；在 Symfony 7.3 及之后，也可以使用 int|null 这样的联合类型字符串。数组元素还可以用 string[]、int[] 表达，避免只检查外层数组而放过错误元素。

$resolver->setAllowedTypes('timeout', ['null', 'int']);

// Symfony 7.3+ 可以用联合类型字符串表达同一个边界。
$resolver->setAllowedTypes('retry', 'int|null');

// 约束数组里的每一项，而不是只检查外层是不是数组。
$resolver->setAllowedTypes('tags', 'string[]');

// 类名约束用于要求调用方传入特定对象。
$resolver->setAllowedTypes('logger', Psr\Log\LoggerInterface::class);

类型不匹配时，错误会在 resolve() 阶段变成 InvalidOptionsException。因此不要只在业务代码里依赖强制类型转换；把边界放在配置入口，错误会更靠近真正的调用位置。

setAllowedValues 负责限制允许值和业务规则

当选项是有限枚举时，直接传数组最容易阅读。比如输出格式只允许 json、csv，就不应该在后续业务分支里重复判断一遍。

$resolver->setAllowedValues('format', ['json', 'csv']);

// 复杂规则使用闭包，并保持返回值明确为布尔值。
$resolver->setAllowedValues('filename', static function (string $value): bool {
    // 文件名必须有扩展名，并且不能包含路径分隔符。
    return str_contains($value, '.')
        && !str_contains($value, '/')
        && !str_contains($value, '\\');
});

固定列表适合协议模式、传输方式等枚举；闭包适合长度、前后缀或多个字段组合出的规则。若同一个选项还需要类型限制，建议同时调用 setAllowedTypes()，让“类型错误”和“值不在业务范围内”分别给出清晰提示。

继承配置时用 add 方法保留父类边界

组件或基类经常先定义一组通用选项，子类再增加可用范围。这时 setAllowedTypes() 和 setAllowedValues() 会替换原有列表，而 addAllowedTypes() 和 addAllowedValues() 会在原列表上追加，选择错误会让父类允许的值意外消失。

final class BaseOptions
{
    public function configure(OptionsResolver $resolver): void
    {
        $resolver->setDefault('format', 'json');
        $resolver->setAllowedTypes('format', 'string');
        $resolver->setAllowedValues('format', ['json']);
    }
}

final class ExportOptions extends BaseOptions
{
    public function configure(OptionsResolver $resolver): void
    {
        parent::configure($resolver);

        // 追加 csv，不会丢掉父类已经允许的 json。
        $resolver->addAllowedValues('format', 'csv');
    }
}

排查异常时可以按四个问题看：选项是否已经定义、输入类型是否正确、值是否在允许集合内、是不是在继承层误用了 set 覆盖父类规则。配置约束集中在 resolver 中，调用方只需要处理解析成功或异常这两个结果。

常见问题

类型和值约束可以只写一个吗？ 可以，但两者解决的问题不同。比如只允许字符串时写类型约束；字符串还必须属于一个有限集合时，再加值约束。

为什么不直接在业务代码里用 in_array？ 直接判断容易散落在多个入口，且默认值、继承配置和异常信息无法集中管理。OptionsResolver 更适合承担“配置进入组件之前”的契约层。

什么时候用 addAllowedValues 而不是 setAllowedValues？ 只要当前 resolver 继承或复用了父级定义，并且希望保留父级允许值，就使用 addAllowedValues()；明确要替换完整规则时才使用 setAllowedValues()。