README

此 Symfony 扩展生成并公开了您的固定数据的文档。还可以配置重新加载固定数据的功能。

此扩展的目标是允许测试人员独立，他们可以在想要再次测试时查看数据和重新加载固定数据。

它做了什么

它将生成一个包含所有数据的 json 文件，这些数据用于在 twig 页面上显示固定数据给最终用户。

要向此 json 文件添加数据，您可以完全手动处理、通过传递实体手动处理或完全自动处理。需要了解的主要数据是：固定数据的类型（部分标题）、固定数据的 id 和固定数据的数据。

它将显示一个页面，其中包含与不同部分对应的菜单（带有链接），以及按部分分组的数据表。如果您使用了链接，它将显示一些带有可见链接的列，可以直接跳转到链接的对象。

当它遇到一个可以具有 3 种行为的属性时

如果它是一个简单的（标量）属性，则将其显示出来（字符串、布尔值、整数等）
如果它是一个数组，则显示数组中的元素总数
如果它是一个对象并且具有公共的 __toString 方法，则显示此方法的输出。如果此类在您的实体配置中，它将添加一个指向它的链接。

工作项目示例

一些外部项目可供查看和测试此扩展的行为。您需要将其克隆到扩展旁边，并按照文档说明进行操作，以使其工作并自行查看准备好的结果。

手动案例项目：Manual case：如果您想手动管理文档
Doctrine 自动案例项目：Doctrine automatic case：如果您使用 doctrine，只想配置要文档化的实体和属性，并让扩展来做
Alice 案例项目：Alice case：如果您通过 Alice 扩展加载固定数据，并希望让扩展处理您的配置

安装

您可以通过 Composer 安装它，作为 adlarge/fixtures-documentation-bundle

composer require --dev adlarge/fixtures-documentation-bundle

访问文档的默认 URL 为 /fixtures/doc

配置

将扩展添加到您的 config/bundles.php

return [
    // ...
    Adlarge\FixturesDocumentationBundle\AdlargeFixturesDocumentationBundle::class => ['dev' => true],
    // ...
];

添加路由文件 config/routes/dev/adlarge_fixtures_documentation.yaml 并粘贴以下内容

AdlargeFixturesDocumentation:
    resource: '@AdlargeFixturesDocumentationBundle/Resources/config/routing.yml'

您可以通过创建文件 config/packages/dev/adlarge_fixtures_documentation.yaml 来定义变量

adlarge_fixtures_documentation:
    title: 'Your title'
    reloadCommands:
        - php bin/console doctrine:fixtures:load
        - ....
    listenedCommand: 'doctrine:fixtures:load'
    enableAutoDocumentation: true
    fileDest: '%kernel.project_dir%/custom-folder'
    configEntities:
        Product:
            - id
            - name
            - category
        Customer:
            - firstname
            - lastname

title 具有默认值 'Fixtures documentation'
listenedCommand 具有默认值 'doctrine:fixtures:load'。对于 Alice 扩展，您可以将其设置为 'hautelook:fixtures:load'
reloadCommand 是您想要从视图中运行的命令的可选数组。如果存在，将在此视图中显示一个按钮以运行这些命令
enableAutoDocumentation 是默认为 false 的布尔值。将其设置为 true 以在 postPersist 中自动文档化固定数据中的所有实体
fileDest 覆盖 var 文件夹中的默认文档文件位置
configEntities - 是一个可选的配置数组，用于您想要自动文档化的实体

然后您可以安装资产

php bin/console assets:install --symlink

示例

您可以使用 'enableAutoDocumentation' 配置。如果设置为 'True'，则此配置将在对象在数据库中 postPersist 时自动根据 'configEntities' 配置进行文档化。

仅在您配置的包（希望是开发环境和测试/验收环境）以及您启动监听命令时检查 postPersist。

以下示例基于以下实体和属性

1 客户端，John Doe，具有
- id
- firstname
- lastname
- email
2 产品，与 John Doe 链接，具有
- id
- name
- tags
- owner

它们的所有属性都具有公共获取器以访问它们

使用 doctrine

使用此示例配置

    adlarge_fixtures_documentation:
      title: Documentation auto
      enableAutoDocumentation: true

当您的监听命令解析时，只需在代码中持久化实体即可

    $john = (new Customer())
        ->setFirstname('John')
        ->setLastname('Doe')
        ->setEmail('john.doe@test.fr');

    $manager->persist($john);

    $product = (new Product())
        ->setName("Product 1")
        ->setCategory("Category 1")
        ->setOwner($john)
        ->setTags(['tag1', 'tag2']);

    $manager->persist($product);

    $product = (new Product())
        ->setName("Product 2")
        ->setCategory("Category 2")
        ->setOwner($john)
        ->setTags(['tag2', 'tag2', 'tag3']);

    $manager->flush();

使用 Alice 包

使用此示例配置

    adlarge_fixtures_documentation:
      title: Documentation alice
      enableAutoDocumentation: true
      listenedCommand: hautelook:fixtures:load
      reloadCommands:
        - php bin/console hautelook:fixtures:load

然后您可以使用 yaml 配置来加载实体

    App\Entity\Customer:
      john:
        firstname: John
        lastname: Doe
        email: john.doe@test.com
    
    App\Entity\Product:
      product1:
        name: product 1
        owner: '@john'
      product2:
        name: product 2
        owner: '@john'

结果

两种方式都将遵循以下规则来自动文档化您的实体

它将使用所有以 'get' 开头的方法来文档化每个实体。

生成文档

要生成文档，您只需运行 php bin/console doctrine:fixtures:load 或您在项目中配置的命令。

开发

为了在您的环境中运行它，您必须安装

composer
php (7.1 or higher)
PHP extensions
* php-xml
* php-mbstring
* php-xdebug

要在您的环境中运行测试，运行以下命令。每个开发者在提交 PR 之前都必须覆盖 100% 的代码

make test
make coverage

adlarge / fixtures-documentation-bundle

维护者

详细信息