README

这是什么？

Document Generator bundle 是一个基于步骤的文档生成库，适用于使用 symfony 和 api-platform 的项目。

系统要求

PHP 8.2+
Symfony 6.3+

安装

推荐的安装方式是通过 Composer

composer require whitedigital-eu/document-generator-bundle

之后，您需要更新数据库模式以使用 Document 实体。
如果使用迁移

bin/console doctrine:migrations:diff
bin/console doctrine:migrations:migrate

如果通过模式更新

bin/console doctrine:schema:update --force

这将启用新的 Document api 资源，iri 为 /api/documents。

组件

1. 任务 - 扩展 AbstractDocumentTask 的类，定义了文档生成器中的大部分逻辑部分。
2. 转换器 - 类，将输入数据转换为在定义的任务中定义的结构。
   目前，该软件包仅包含将 twig 转换为 pdf 的转换器，但可以在项目中通过创建实现 TransformerInterface 的自定义转换器来更改。
3. 生成器 - 类，从定义的数据、模板和可选的上下文生成生成的结果（二进制数据或文件的路径）。
4. 生成器上下文 - 类，包含生成器执行文档生成时使用的附加可选上下文。
5. Html 到 Pdf 服务 - 用于从 html 生成 pdf 文件的可重用服务。在这里用于转换器，但可以在其他地方使用。使用 gotenberg 在后台。

用法

1. 定义一个新的 Task，它扩展 AbstractDocumentTask

use Doctrine\ORM\EntityManagerInterface;
use WhiteDigital\DocumentGeneratorBundle\Generator\TwigToPdfGenerator;
use WhiteDigital\DocumentGeneratorBundle\Task\AbstractDocumentTask;

class TestDocumentTask extends AbstractDocumentTask
{

}

并定义所需的函数
__construct

public function __construct(
     EntityManagerInterface $em,
     TwigToPdfGenerator $twigToPdfGenerator,
     ReceiptTransformer $receiptTransformer,
 ) {
     parent::__construct($em, $twigToPdfGenerator, $receiptTransformer);
 }

AbstractDocumentTask 需要 3 个服务

1. EntityManagerInterface
2. Generator - 来自库的 TwigToPdfGenerator 或其他定义的生成器
3. Transformer - 您定义的服务（关于它的更多信息见下文）

getTransformerFields

public function getTransformerFields(): array
{
    return [
        'field1' => 'string',
        'array1' => [
            'array2' => [
                'field2' => 'bool',
            ],
        ],
    ]; // array of fields that Transformer can contain
}

getTemplatePath

public function getTemplatePath(): string
{
    return '/path/to/defined/template.html.twig'; // must be in directory visible by twig, usually /templates
}

getType

public function getType(): string 
{
    return 'TEST'; // simple identifier to separate different documents
}

getInputType

public function getInputType(): string
{
    return 'array'; // what type of data does Transformer require as input
}

1. 定义一个新的实现 TransformerInterface 的 Transformer

class TestTransformer implements Transformer
{
    public function getTransformedFields(mixed $input): array {
        return [
            'field1' => 'abc',
             'array1' => [
                'array2' => [
                    'field2' => false,
                ],
            ],
            'field3' => 3
        ];
    }
}

转换器可以返回 getTransformedFields 中列出的字段的一部分或全部，为数组形式

1. 使用生成定义的任务现在可以作为服务使用

public function __construct(private TestDocumentTask $task)
{
}

public function abc()
{
    return $this->task->generate([1, 2, 3]);
}

generate 函数的输入必须是 Transformer 中定义的类型。
generate 函数将返回已存在的 Document 实体或抛出错误（如果出现错误）。

重新生成

如果您需要出于任何原因重新生成现有文档，可以使用内置的 DocumentTask 与现有的文档实体一起使用。

use WhiteDigital\DocumentGeneratorBundle\Entity\Document;use WhiteDigital\DocumentGeneratorBundle\Task\DocumentTask;
use Doctrine\ORM\EntityManagerInterface;

public function __construct(private DocumentTask $task, private EntityManagerInterface $em)
{
}

public function abc()
{
    return $this->task->generate($this->em->getRepository(Document::class)->find(123));
}