README

What is it?

Document Generator bundle is step based document generator library for projects using symfony and api-platform.

System Requirements

PHP 8.2+
Symfony 6.3+

Installation

The recommended way to install is via Composer:

composer require whitedigital-eu/document-generator-bundle

After this, you need to update your database schema to use Document entity.
If using migrations:

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

If by schema update:

bin/console doctrine:schema:update --force

This will enable new Document api resource with /api/documents iri.

Components

Task - requirement and config class that extends AbstractDocumentTask and defines most of the logical parts in document generator.
Transformer - class that transforms input data into structure defined in your defined task.
For now, package only comes with transformer that turns twig into pdf but this can be changed within project by creating your own transformers by implementing TransformerInterface
Html to Pdf service - reusable service to generate pdf files from html. Here used within transformer but can be used elsewhere. Uses gotenberg in background.

Usage

Define new Task that extends AbstractDocumentTask

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

class TestDocumentTask extends AbstractDocumentTask
{

}

and define required functions:
__construct

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

AbstractDocumentTask requires 3 services:

EntityManagerInterface
Generator - TwigToPdfGenerator from library or other defined one
Transformer - service defined by you (more about it below)

getRequiredFields

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

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
}

and one optional function could be defined:
getOptionalFields

public function getOptionalFields(): array
{
    return [
        'field3' => 'int',
    ]; // array of fields that Transformer COULD also return
}

Define new Transformer that implements TransformerInterface:

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

transformer MUST return an array of fields:
a. ALL from Task getRequiredFields,
b. NONE, SOME or ALL from getTransformedFields

ALL fields returned by transformer MUST be defined in either required or optional fields

Use generation Defined task can now be used as a service

public function __construct(private TestDocumentTask $task)
{
}

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

Input of generate function must be type defined in Transformer.
generate function will return already Document entity or throw an error if something is wrong.

Regenerate

If for any reason you need to regenerate existing document, you can use built-in DocumentTask with existing document entity.

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));
}

whitedigital-eu / document-generator-bundle

Maintainers

Details