startsevdenis / liform
将 Symfony 表单转换为 Json Schema 的库
Requires
- php: ^7.2.5|^8.1
- symfony/contracts: ^1.0|^2.1|3.0
- symfony/form: ^4.4|^5.0|^6.0
- symfony/serializer: ^4.4|^5.0|^6.0
- symfony/translation: ^4.4|^5.0|^6.0
Requires (Dev)
README
Liform 是一个库，可以将 Symfony 表单序列化为 JSON schema。它可以与 liform-react 或 json-editor 一起使用，或使用基于 json-schema 的任何其他表单生成器。
它被 LiformBundle 使用，但也可以作为一个独立的库使用。
维护后端表单以匹配客户端技术（如 JavaScript）中的表单非常令人烦恼。维护此类表单的文档也很麻烦。而且容易出错。
Liform 生成一个 JSON schema 表示，作为文档，可用于文档、验证数据，如果需要，还可以使用生成器生成表单。
安装
打开控制台，进入您的项目目录，并执行以下命令以下载此库的最新稳定版本
$ composer require startsevdenis/liform
此命令要求您全局安装了 Composer，如 Composer 文档的 安装章节 所述。
Liform 遵循其类的 PSR-4 命名约定，这意味着您可以将
Liform类的加载轻松集成到自己的自动加载器中。
注意
symfony/form ^5.0 在我们使用的某些抽象函数上破坏了向后兼容性。如果您需要与早期版本兼容的功能，您需要使用 Liform v0.15 或更早版本
$ composer require limenius/liform "^0.15"
使用
将表单序列化为 JSON Schema
use Limenius\Liform\Resolver; use Limenius\Liform\Liform; use Limenius\Liform\Liform\Transformer; $resolver = new Resolver(); $resolver->setTransformer('text', Transformer\StringTransformer); $resolver->setTransformer('textarea', Transformer\StringTransformer, 'textarea'); // more transformers you might need, for a complete list of what is used in Symfony // see https://github.com/Limenius/LiformBundle/blob/master/Resources/config/transformers.xml $liform = new Liform($resolver); $form = $this->createForm(CarType::class, $car, ['csrf_protection' => false]); $schema = json_encode($liform->transform($form));
则 $schema 将包含类似于以下 JSON Schema 表示的形式
{ "title":null, "properties":{ "name":{ "type":"string", "title":"Name", "propertyOrder":1 }, "color":{ "type":"string", "title":"Color", "attr":{ "placeholder":"444444" }, "description":"3 hexadecimal digits", "propertyOrder":2 }, "drivers":{ "type":"array", "title":"hola", "items":{ "title":"Drivers", "properties":{ "firstName":{ "type":"string", "propertyOrder":1 }, "familyName":{ "type":"string", "propertyOrder":2 } }, "required":[ "firstName", "familyName" ], "type":"object" }, "propertyOrder":3 } }, "required":[ "name", "drivers" ] }
使用自己的转换器
Liform 通过递归检查表单，为每个子项找到（解析）正确的转换器，并使用该转换器构建相应的 json-schema 片段。因此，如果您想修改特定表单类型转换的方式，您应该设置一个与该 block_prefix 匹配的转换器。
为此，您可以使用 Resolver 类的 setTransformer 方法。在这种情况下，我们正在重用 StringTransformer，通过覆盖 widget 属性并将其设置为 my_widget 来重新使用它，但您可以使用您自己的转换器，如果您喜欢的话
use Limenius\Liform\Liform; $stringTransformer = $this->get('liform.transformer.string'); $resolver = $this->get('liform.resolver'); $resolver->setTransformer('file', $stringTransformer, 'file_widget'); $liform = new Liform($resolver);
序列化初始值
此库提供了一个规范化器，可以将 FormView（您可以使用 $form->createView() 创建一个）序列化为初始值数组。
use Limenius\Liform\Serializer\Normalizer\FormViewNormalizer; $encoders = array(new XmlEncoder(), new JsonEncoder()); $normalizers = array(new FormViewNormalizer()); $serializer = new Serializer($normalizers, $encoders); $initialValues = $serializer->normalize($form),
以获取与您的 json-schema 匹配的初始值数组。
序列化错误
此库提供了一个规范化器，可以将带有错误的表单序列化为数组。这部分内容是从 FOSRestBundle 中无耻地借鉴的。要使用此功能，请将以下代码复制到您的控制器操作中
use Limenius\Liform\Serializer\Normalizer\FormErrorNormalizer; $encoders = array(new XmlEncoder(), new JsonEncoder()); $normalizers = array(new FormErrorNormalizer()); $serializer = new Serializer($normalizers, $encoders); $errors = $serializer->normalize($form),
以获取包含您表单错误的数组。如果使用 liform-react，则它可以理解此格式。
提取到 JSON-schema 的信息
Liform 的目标是尽可能从表单中提取数据，以便在 schema 中具有完整的表示，包括验证和 UI 提示。目前支持以下选项。
一些数据可以从常规表单属性中提取，然而，某些属性将使用特殊的 liform 数组来提供，该数组被传递到表单选项中。为此，提供了一个 表单扩展，以便更方便地实现。请参阅 AddLiformExtension.php
必填
如果字段是必填的（在 Symfony 中默认如此），它将反映在模式中。
class DummyType extends AbstractType { public function buildForm(FormBuilderInterface $builder, array $options) { $builder ->add('someText', Type\TextType::class); } }
{
"title":"dummy",
"type":"object",
"properties":{
"someText":{
"type":"string",
"title":"someText",
"propertyOrder":1
}
},
"required":[
"someText"
]
}
小部件
有时您可能希望以不同于该类型默认行为的方式渲染字段。通过使用 liform 属性，您可以指定一个特定的小部件，以确定如何渲染该字段。
如果提供 liform 的 widget 属性，如下所示
class DummyType extends AbstractType { public function buildForm(FormBuilderInterface $builder, array $options) { $builder ->add('someText', Type\TextType::class, [ 'liform' => [ 'widget' => 'my_widget' ] ]); } }
生成的模式将包含那个 widget 选项
{
"title":"dummy",
"type":"object",
"properties":{
"someText":{
"type":"string",
"widget":"my_widget",
"title":"someText",
"propertyOrder":1
}
},
"required":[
"someText"
]
}
标签/标题
如果您提供了 label，它将作为模式中的标题使用。
class DummyType extends AbstractType { public function buildForm(FormBuilderInterface $builder, array $options) { $builder ->add('someText', Type\TextType::class, [ 'label' => 'Some text', ]); } }
{
"title":"dummy",
"type":"object",
"properties":{
"someText":{
"type":"string",
"title":"Some text",
"propertyOrder":1
}
},
"required":[
"someText"
]
}
模式
如果提供 attr 的 pattern 属性，如下所示
class DummyType extends AbstractType { public function buildForm(FormBuilderInterface $builder, array $options) { $builder ->add('someText', Type\TextType::class, [ 'attr' => [ 'pattern' => '.{5,}', ], ]); } }
它将作为 pattern 选项提取，因此可用于验证。注意，除了这些之外，提供给 attr 的所有内容也将被保留。
{
"title":"dummy",
"type":"object",
"properties":{
"someText":{
"type":"string",
"title":"someText",
"attr":{
"pattern":".{5,}"
},
"pattern":".{5,}",
"propertyOrder":1
}
},
"required":[
"someText"
]
}
描述
如果提供 liform 的 description 属性，如下所示，它将被提取到模式中
class DummyType extends AbstractType { public function buildForm(FormBuilderInterface $builder, array $options) { $builder ->add('someText', Type\TextType::class, [ 'label' => 'Some text', 'liform' => [ 'description' => 'This is a help message', ] ]); } }
{
"title":"dummy",
"type":"object",
"properties":{
"someText":{
"type":"string",
"title":"Some text",
"description":"This is a help message",
"propertyOrder":1
}
},
"required":[
"someText"
]
}
许可证
此库受 MIT 许可证保护。请参阅文件中的完整许可证。
LICENSE.md
致谢
使用解析器和还原器转换表单的技术灵感来源于 Symfony Console Form