answear/liform

将 Symfony 表单转换为 Json Schema 的库

维护者

详细信息

github.com/answear/Liform

源代码

问题

安装次数: 12,325

依赖关系: 1

建议者: 0

安全: 0

星标: 1

关注者: 2

分支: 75

开放问题: 1

0.21.0 2024-06-14 08:31 UTC

Requires

Requires (Dev)

Replaces

MIT 544d835ded6e77a73602fb0c1e84edf49d396c4a

  • Nacho Martín <nacho.woop@limenius.com>

This package is auto-updated.

Last update: 2024-09-14 09:12:31 UTC

README

Liform 是一个库，可以将 Symfony 表单序列化为 JSON 模式。它可以与 liform-react 或 json-editor 一起使用，或者任何基于 json-schema 的表单生成器。

它由 LiformBundle 使用，但也可以作为独立的库使用。

维护与客户端技术（如 JavaScript）中的表单相匹配的后端表单非常令人烦恼。维护此类表单的文档也很令人烦恼。而且容易出错。

Liform 生成一个 JSON 模式表示，充当文档，可以用来文档化、验证您的数据，如果您想的话，还可以使用生成器生成表单。

Build Status Latest Stable Version Latest Unstable Version License

安装

打开控制台，进入您的项目目录，并执行以下命令以下载此库的最新稳定版本

$ composer require limenius/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 的目标是尽可能从表单中提取数据，以便在模式中具有完整的表示，包括验证和 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 的启发