chamber-orchestra/form-bundle

[](https://github.com/chamber-orchestra/form-bundle/actions/workflows/php.yml) [](https://packagist.org/packages/chamber-orchestra/form-bundle) [](https://packagist.org/packages/chamber-orchestra/form-bundle)      # ChamberOrchestra Form Bundle 一个 Symfony 8 bundle，用于简化 REST API 的 JSON 优先表单处理。它提供了用于提交/验证/响应流程的 controller trait，禁用了 CSRF 的专用 API 表单类型，可重用的 data transformer，基于 Doctrine 的唯一性验证，以及遵循 [RFC 9457 (HTTP APIs 的 Problem Details)](https://www.rfc-editor.org/rfc/rfc9457) 的结构化错误响应。 ## 功能 - **Controller trait** (`FormTrait`, `ApiFormTrait`)，用于带有 null 安全请求处理的提交/验证/响应流程 - **JSON payload 处理**，用于带有自动合并上传文件的 mutation 请求 - **API 表单基础类型** (`QueryForm`, `MutationForm`)，禁用 CSRF 并使用空的 block prefix 以获得纯净的 JSON payload - **自定义表单类型**：`BooleanType`、`TimestampType`、`HiddenEntityType`，具有安全的 query builder 参数化 - **Data transformer**，用于布尔值、Unix 时间戳、逗号分隔的数组和 JSON 字符串 - **RFC 9457 problem details**，通过 `ValidationFailedView` 提供结构化违规信息，以实现一致的 API 错误响应 - **可翻译的错误 normalizer** (`ProblemNormalizer`)，用于在 problem detail 响应中提供本地化的异常消息 - **`UniqueField` 验证约束**，适用于带有多个字段检查、基于闭包的排除和自定义 normalizer 的 Doctrine repository - **`TelExtension`**，用于从电话号码输入中移除非数字字符 - **`CollectionUtils`**，用于同步 Doctrine collection（添加新的 / 移除过期的项目） ## 要求 - PHP ^8.5 - Symfony 8.0 组件 (framework-bundle, form, validator, config, dependency-injection, runtime, translation, clock) - Doctrine ORM 3.6 - [chamber-orchestra/view-bundle](https://github.com/chamber-orchestra/view-bundle) 8.0 ## 安装说明 ``` composer require chamber-orchestra/form-bundle:8.0.* ``` 在 `config/bundles.php` 中启用该 bundle： ``` return [ // ... ChamberOrchestra\FormBundle\ChamberOrchestraFormBundle::class => ['all' => true], ]; ``` ## 使用说明 ### Controller Traits 对于标准的 HTML 表单提交使用 `FormTrait`，对于 JSON API endpoint 使用 `ApiFormTrait`。 `handleFormCall()` 接受一个表单类或实例，处理请求，并返回一个视图或响应。`handleApiCall()` 对 API endpoint 执行相同的操作——它会自动为 `MutationForm` 类型解析 JSON payload 并合并上传的文件。 `onFormSubmitted()` 检查有效性，如果失败则返回 `ValidationFailedView`，或者在成功时调用回调函数： ``` use ChamberOrchestra\FormBundle\ApiFormTrait; use ChamberOrchestra\ViewBundle\View\ViewInterface; use Symfony\Component\HttpFoundation\Request; final class SearchCourseAction { use ApiFormTrait; public function __invoke(Request $request): ViewInterface { $form = $this->createForm(SearchCourseForm::class); $form->submit($request->query->all()); return $this->onFormSubmitted($form, function (SearchCourseData $dto) use ($request) { $entities = $this->er->searchCourses( $pagination = $this->getPagination(['per_page_limit' => $this->getPerPageLimit($request)]), $dto->query, $dto->brands, $dto->topics, $dto->products, $dto->durations ); return new PaginatedView($entities, $pagination, CourseView::class); }); } } ``` ### API 表单类型 为 GET 请求扩展 `QueryForm`，或为 POST/PUT/PATCH 请求扩展 `MutationForm`。两者都禁用了 CSRF 保护，并使用空的 block prefix 以实现纯净的 JSON 输入/输出。 ### Data Transformer | Transformer | 描述 | |---|---| | `TextToBoolTransformer` | 将 `"true"`、`"1"`、`"yes"` 转换为布尔值 | | `DateTimeToNumberTransformer` | 将 Unix 时间戳转换为 `DateTimeInterface` 对象 | | `ArrayToStringTransformer` | 在数组与逗号分隔的字符串之间进行转换 | | `JsonStringToArrayTransformer` | 将 JSON 字符串解析为数组（处理空字符串） | ### HiddenEntityType 通过隐藏的表单字段按 ID 加载 Doctrine entity。支持带有安全参数化查询的自定义 `query_builder` 选项。 ### UniqueField Validator 根据 Doctrine repository 验证字段的唯一性。支持多个字段、基于闭包的排除、自定义 normalizer 以及针对性的错误路径。 ### ProblemNormalizer 扩展了 Symfony 的 `ProblemNormalizer`，以便在异常实现 `TranslatableExceptionInterface` 时翻译异常消息。这确保了在 RFC 9457 problem detail 响应中包含本地化的错误消息。 ## 响应视图 | 视图 | HTTP 状态码 | 描述 | |---|---|---| | `SuccessView` | 200 | 空的成功响应 | | `ValidationFailedView` | 422 | 包含结构化 `ViolationView` 项目的表单验证错误 | | `FailureView` | 可配置 | 通用的错误响应 | | `RedirectView` | 301/302 | 用于 AJAX 请求的重定向响应 | | `SuccessHtmlView` | 200 | 用于 AJAX 请求的 HTML 片段响应 | ## 测试 安装依赖并运行完整的测试套件： ``` composer install ./vendor/bin/phpunit ``` 集成测试内核 (`tests/Integrational/TestKernel.php`) 会启动一个最小化的 Symfony 应用，并使用内存中的 SQLite 进行 Doctrine 测试。 ## 许可证 MIT

标签：ffuf, JSON, OpenVAS, PHP, RESTful API, Symfony, Syscall, Web开发, 提示词优化, 数据校验, 表单处理