Symfony/Validator 用于 PHP：完整指南及示例

\n\n

1. 这是什么以及为什么需要它

\n\n

Symfony/Validator 库是 Symfony 生态系统中一个强大且灵活的组件，用于数据验证。与简单的“即时”检查不同，该组件提供了一种声明式方法：您使用注解、PHP 8+ 属性、YAML、XML 或 PHP 数组来描述验证规则（约束），然后将数据传递给一个特殊的服务——ValidatorInterface。这允许将验证逻辑与应用程序的业务逻辑分离，使代码更清晰、更易于测试和重用。

\n\n

为什么需要它？在任何 Web 应用程序（以及非 Web 应用程序）中，数据都来自不可靠的来源：网站表单、API 请求、CSV 文件导入。没有验证，您可能会面临 SQL 注入、XSS 攻击、不正确的计算或数据库中的“垃圾”数据。Symfony/Validator 全面解决了这些问题：它检查数据类型、字符串长度、数字范围、电子邮件唯一性、正则表达式匹配等等。此外，它能够将所有错误收集到一个统一的 ConstraintViolationList 对象中，该对象可以轻松转换为 API 的 JSON 响应或显示为表单上的错误列表。

\n\n

该组件完全独立于 Symfony 框架。您可以在任何 PHP 项目（Laravel、Yii、您自己的框架甚至“纯”PHP）中使用它。它受到积极维护，拥有出色的文档和庞大的社区。它是 PHP 世界中验证的“黄金标准”。

\n\n

2. 安装

\n\n

通过 Composer 进行安装。在您项目的根目录下，在终端中执行：

\n\n

composer require symfony/validator

\n\n

还建议安装 symfony/property-access 组件，以便正确处理嵌套对象和数组：

\n\n

composer require symfony/property-access

\n\n

如果您计划使用注解/属性，请确保您已安装 doctrine/annotations（适用于 PHP 7.x），或者您正在使用带有原生属性的 PHP 8+。

\n\n

3. 快速入门 — 最小工作示例

\n\n

让我们创建一个简单的 User 类，其中包含验证属性并对其进行验证。

\n\n

<?php\n// 1. 引入 Composer 自动加载\nrequire_once 'vendor/autoload.php';\n\n// 2. 导入必要的类\nuse Symfony\\Component\\Validator\\Validation;\nuse Symfony\\Component\\Validator\\Constraints as Assert;\n\n// 3. 创建带有验证属性的类 (PHP 8+)\nclass User {\n    #[Assert\\NotBlank(message: "名称不能为空")]\n    #[Assert\\Length(min: 2, max: 50, minMessage: "名称必须至少包含 {{ limit }} 个字符")]\n    public string $name;\n\n    #[Assert\\NotBlank]\n    #[Assert\\Email(message: "电子邮件 '{{ value }}' 无效。")]\n    public string $email;\n\n    #[Assert\\PositiveOrZero]\n    public int $age;\n}\n\n// 4. 创建验证器\n$validator = Validation::createValidatorBuilder()\n    ->enableAttributeMapping() // 启用属性支持\n    ->getValidator();\n\n// 5. 创建包含无效数据的对象\n$user = new User();\n$user->name = 'A'; // 名称太短\n$user->email = 'not-an-email';\n$user->age = -5;\n\n// 6. 进行验证\n$violations = $validator->validate($user);\n\n// 7. 处理错误\nif (count($violations) > 0) {\n    foreach ($violations as $violation) {\n        echo $violation->getPropertyPath() . ': ' . $violation->getMessage() . "\\n";\n    }\n} else {\n    echo "数据有效！";\n}\n

\n\n

此示例将输出：

\n

name: 名称必须至少包含 2 个字符\nemail: 电子邮件 'not-an-email' 无效。\nage: 此值必须为正数或零。

\n\n

4. 主要方法/函数/类