From e9a96268cbd49559d883f575bd0672c2f60abf1b Mon Sep 17 00:00:00 2001
From: jygaulier <gaulier@alchemy.fr>
Date: Tue, 3 Dec 2024 09:37:19 +0100
Subject: [PATCH] documentation & config validator as services, used by
 databox.

---
 databox/api/config/validator/validation.yaml  |   5 +-
 .../Command/DocumentationDumperCommand.php    |  41 ++++++
 .../ValidRenditionDefinitionConstraint.php    |  15 +++
 ...RenditionDefinitionConstraintValidator.php |  36 +++++
 .../Resources/config/services.yaml            |   8 +-
 .../src/Command/ConfigCommand.php             | 123 ------------------
 .../Command/ConfigurationValidateCommand.php  |  43 ++++++
 .../src/Config/Validator.php                  |  58 +++++++++
 .../src/DTO/BuildConfig/Transformation.php    |   2 +-
 .../src/DocumentationDumper.php               | 108 +++++++++++++++
 .../DocumentToPdfTransformerModule.php        |  32 ++---
 .../Document/PdfToImageTransformerModule.php  |  32 ++---
 .../Imagine/ImagineTransformerModule.php      |  34 ++---
 .../Transformer/TransformerConfigHelper.php   |  64 +++++++++
 .../TransformerModuleInterface.php            |   2 +-
 .../Video/FFMpegTransformerModule.php         |  60 ++++-----
 .../Video/VideoSummaryTransformerModule.php   |  37 +++---
 .../VideoToAnimationTransformerModule.php     |  37 +++---
 .../Video/VideoToFrameTransformerModule.php   |  37 +++---
 .../src/Transformer/VoidTransformerModule.php |  26 ++--
 20 files changed, 528 insertions(+), 272 deletions(-)
 create mode 100644 databox/api/src/Command/DocumentationDumperCommand.php
 create mode 100644 databox/api/src/Validator/ValidRenditionDefinitionConstraint.php
 create mode 100644 databox/api/src/Validator/ValidRenditionDefinitionConstraintValidator.php
 delete mode 100644 lib/php/rendition-factory/src/Command/ConfigCommand.php
 create mode 100644 lib/php/rendition-factory/src/Command/ConfigurationValidateCommand.php
 create mode 100644 lib/php/rendition-factory/src/Config/Validator.php
 create mode 100644 lib/php/rendition-factory/src/DocumentationDumper.php
 create mode 100644 lib/php/rendition-factory/src/Transformer/TransformerConfigHelper.php

diff --git a/databox/api/config/validator/validation.yaml b/databox/api/config/validator/validation.yaml
index 74292be91..240e6e38b 100644
--- a/databox/api/config/validator/validation.yaml
+++ b/databox/api/config/validator/validation.yaml
@@ -127,6 +127,7 @@ App\Entity\Core\RenditionDefinition:
           - workspace
           - class.workspace
           - parent.workspace
+    - App\Validator\ValidRenditionDefinitionConstraint: ~
   properties:
     class:
       - NotNull: ~
@@ -176,8 +177,8 @@ App\Entity\Core\Tag:
         errorPath: name
 
 App\Entity\Integration\WorkspaceIntegration:
-  constraints:
-    - App\Validator\ValidIntegrationOptionsConstraint: ~
+    constraints:
+        - App\Validator\ValidIntegrationOptionsConstraint: ~
 
 App\Entity\Integration\IntegrationData:
   properties:
diff --git a/databox/api/src/Command/DocumentationDumperCommand.php b/databox/api/src/Command/DocumentationDumperCommand.php
new file mode 100644
index 000000000..2f8c49a99
--- /dev/null
+++ b/databox/api/src/Command/DocumentationDumperCommand.php
@@ -0,0 +1,41 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Command;
+
+use Symfony\Component\Console\Attribute\AsCommand;
+use Symfony\Component\Console\Command\Command;
+use Symfony\Component\Console\Input\InputInterface;
+use Symfony\Component\Console\Output\OutputInterface;
+
+use Alchemy\RenditionFactory\DocumentationDumper as RenditionFactoryDocumentationDumper;
+
+
+#[AsCommand('app:documentation:dump')]
+class DocumentationDumperCommand extends Command
+{
+    public function __construct(
+        private readonly RenditionFactoryDocumentationDumper $renditionFactoryDocumentationDumper,
+    )
+    {
+        parent::__construct();
+    }
+
+    protected function configure(): void
+    {
+        parent::configure();
+
+        $this
+            ->setName('app:documentation:dump')
+        ;
+    }
+
+    protected function execute(InputInterface $input, OutputInterface $output): int
+    {
+        $output->writeln('# rendition factory');
+        $output->writeln($this->renditionFactoryDocumentationDumper->dump());
+
+        return 0;
+    }
+}
diff --git a/databox/api/src/Validator/ValidRenditionDefinitionConstraint.php b/databox/api/src/Validator/ValidRenditionDefinitionConstraint.php
new file mode 100644
index 000000000..75b0096e1
--- /dev/null
+++ b/databox/api/src/Validator/ValidRenditionDefinitionConstraint.php
@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Validator;
+
+use Symfony\Component\Validator\Constraint;
+
+class ValidRenditionDefinitionConstraint extends Constraint
+{
+    public function getTargets(): string|array
+    {
+        return self::CLASS_CONSTRAINT;
+    }
+}
diff --git a/databox/api/src/Validator/ValidRenditionDefinitionConstraintValidator.php b/databox/api/src/Validator/ValidRenditionDefinitionConstraintValidator.php
new file mode 100644
index 000000000..6578cccca
--- /dev/null
+++ b/databox/api/src/Validator/ValidRenditionDefinitionConstraintValidator.php
@@ -0,0 +1,36 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Validator;
+
+
+use Alchemy\RenditionFactory\Config\Validator;
+use Alchemy\RenditionFactory\Config\YamlLoader;
+use App\Entity\Core\RenditionDefinition;
+use Symfony\Component\Config\Definition\Exception\InvalidConfigurationException;
+use Symfony\Component\Validator\Constraint;
+use Symfony\Component\Validator\ConstraintValidator;
+
+class ValidRenditionDefinitionConstraintValidator extends ConstraintValidator
+{
+    public function __construct(private readonly YamlLoader $yamlLoader, private readonly Validator $validator)
+    {
+    }
+
+    /**
+     * @param RenditionDefinition $value
+     * @param ValidRenditionDefinitionConstraint $constraint
+     */
+    public function validate($value, Constraint $constraint): void
+    {
+        try {
+            $config = $this->yamlLoader->parse($value->getDefinition());
+            $this->validator->validate($config);
+        } catch (\Throwable $e) {
+            $this->context
+                ->buildViolation($e->getMessage())
+                ->addViolation();
+        }
+    }
+}
diff --git a/lib/php/rendition-factory-bundle/Resources/config/services.yaml b/lib/php/rendition-factory-bundle/Resources/config/services.yaml
index 1e2d8def2..47522f5a9 100644
--- a/lib/php/rendition-factory-bundle/Resources/config/services.yaml
+++ b/lib/php/rendition-factory-bundle/Resources/config/services.yaml
@@ -4,7 +4,7 @@ services:
         autoconfigure: true
 
     Alchemy\RenditionFactory\Command\CreateCommand: ~
-    Alchemy\RenditionFactory\Command\ConfigCommand: ~
+    Alchemy\RenditionFactory\Command\ConfigurationValidateCommand: ~
 
     Alchemy\RenditionFactory\Context\TransformationContextFactory: ~
     Alchemy\RenditionFactory\FileFamilyGuesser: ~
@@ -102,3 +102,9 @@ services:
     Alchemy\RenditionFactory\Format\FormatGuesser: ~
     Alchemy\RenditionFactory\Format\FormatFactory: ~
     Alchemy\RenditionFactory\Config\ModuleOptionsResolver: ~
+
+    Alchemy\RenditionFactory\DocumentationDumper:
+        tags:
+              - { name: 'documentation.dumper' }
+
+    Alchemy\RenditionFactory\Config\Validator: ~
diff --git a/lib/php/rendition-factory/src/Command/ConfigCommand.php b/lib/php/rendition-factory/src/Command/ConfigCommand.php
deleted file mode 100644
index 7ccad1a40..000000000
--- a/lib/php/rendition-factory/src/Command/ConfigCommand.php
+++ /dev/null
@@ -1,123 +0,0 @@
-<?php
-
-declare(strict_types=1);
-
-namespace Alchemy\RenditionFactory\Command;
-
-use Alchemy\RenditionFactory\Config\YamlLoader;
-use Alchemy\RenditionFactory\DTO\FamilyEnum;
-use Alchemy\RenditionFactory\Transformer\Documentation;
-use Alchemy\RenditionFactory\Transformer\TransformerModuleInterface;
-use Symfony\Component\Config\Definition\Dumper\YamlReferenceDumper;
-use Symfony\Component\Config\Definition\Exception\InvalidConfigurationException;
-use Symfony\Component\Config\Definition\Processor;
-use Symfony\Component\Console\Attribute\AsCommand;
-use Symfony\Component\Console\Command\Command;
-use Symfony\Component\Console\Input\InputArgument;
-use Symfony\Component\Console\Input\InputInterface;
-use Symfony\Component\Console\Output\OutputInterface;
-use Symfony\Component\DependencyInjection\Attribute\TaggedLocator;
-use Symfony\Component\DependencyInjection\ServiceLocator;
-
-#[AsCommand('alchemy:rendition-factory:config')]
-class ConfigCommand extends Command
-{
-    public function __construct(
-        private readonly YamlLoader $yamlLoader,
-        #[TaggedLocator(TransformerModuleInterface::TAG, defaultIndexMethod: 'getName')]
-        private readonly ServiceLocator $transformers,
-    ) {
-        parent::__construct();
-    }
-
-    protected function configure(): void
-    {
-        parent::configure();
-
-        $this->addArgument('config', InputArgument::OPTIONAL, 'A build config YAML file to validate')
-            ->setHelp('Display rendition modules documentation, or validate a config file.')
-        ;
-    }
-
-    protected function execute(InputInterface $input, OutputInterface $output): int
-    {
-        if (null !== ($configPath = $input->getArgument('config'))) {
-            $config = $this->yamlLoader->load($configPath);
-
-            foreach (FamilyEnum::cases() as $family) {
-                $familyConfig = $config->getFamily($family);
-                if (null === $familyConfig) {
-                    continue;
-                }
-                foreach ($familyConfig->getTransformations() as $transformation) {
-                    $transformerName = $transformation->getModule();
-
-                    /** @var TransformerModuleInterface $transformer */
-                    $transformer = $this->transformers->get($transformerName);
-
-                    try {
-                        $this->checkTransformerConfiguration($transformerName, $transformer, $transformation->asArray());
-                    } catch (\Throwable $e) {
-                        $msg = sprintf("Error in module \"%s\"\n%s", $transformerName, $e->getMessage());
-                        throw new InvalidConfigurationException($msg);
-                    }
-                }
-            }
-            $output->writeln('Configuration is valid.');
-        } else {
-            foreach ($this->transformers->getProvidedServices() as $transformerName => $transformerFqcn) {
-
-                /** @var TransformerModuleInterface $transformer */
-                $transformer = $this->transformers->get($transformerName);
-                $output->writeln($this->getTransformerDocumentation($transformerName, $transformer));
-            }
-        }
-
-        return 0;
-    }
-
-    private function getTransformerDocumentation(string $transformerName, TransformerModuleInterface $transformer): string
-    {
-        $docToText = function (Documentation $documentation, int $depth = 0) use (&$docToText): string {
-
-            $text = '';
-            if ($t = $documentation->getHeader()) {
-                $text .= $t."\n";
-            }
-
-            $treeBuilder = $documentation->getTreeBuilder();
-            $node = $treeBuilder->buildTree();
-            $dumper = new YamlReferenceDumper();
-
-            $t = $dumper->dumpNode($node);
-            $t = preg_replace("#^root:($|(\s+)\[]$)#m", "-\n", (string) $t);
-            $t = preg_replace("#\n+#", "\n", $t);
-            $t = trim($t);
-
-            $text .= "```yaml\n".$t."\n```\n";
-
-            if ($t = $documentation->getFooter()) {
-                $text .= $t."\n";
-            }
-
-            foreach ($documentation->getChildren() as $child) {
-                $text .= $docToText($child, $depth + 1);
-            }
-
-            return $text;
-        };
-
-        $documentation = $transformer->getDocumentation();
-
-        return "## `$transformerName` transformer module\n".$docToText($documentation);
-    }
-
-    private function checkTransformerConfiguration(string $transformerName, TransformerModuleInterface $transformer, array $options): void
-    {
-        $documentation = $transformer->getDocumentation();
-        $treeBuilder = $documentation->getTreeBuilder();
-
-        $processor = new Processor();
-        $processor->process($treeBuilder->buildTree(), ['root' => $options]);
-    }
-}
diff --git a/lib/php/rendition-factory/src/Command/ConfigurationValidateCommand.php b/lib/php/rendition-factory/src/Command/ConfigurationValidateCommand.php
new file mode 100644
index 000000000..6d8785b58
--- /dev/null
+++ b/lib/php/rendition-factory/src/Command/ConfigurationValidateCommand.php
@@ -0,0 +1,43 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Alchemy\RenditionFactory\Command;
+
+use Alchemy\RenditionFactory\Config\Validator;
+use Alchemy\RenditionFactory\Config\YamlLoader;
+use Symfony\Component\Console\Attribute\AsCommand;
+use Symfony\Component\Console\Command\Command;
+use Symfony\Component\Console\Input\InputArgument;
+use Symfony\Component\Console\Input\InputInterface;
+use Symfony\Component\Console\Output\OutputInterface;
+
+#[AsCommand('alchemy:rendition-factory:conf:validate')]
+class ConfigurationValidateCommand extends Command
+{
+    public function __construct(
+        private readonly YamlLoader $yamlLoader,
+        private readonly Validator $validator,
+    ) {
+        parent::__construct();
+    }
+
+    protected function configure(): void
+    {
+        parent::configure();
+
+        $this->addArgument('config', InputArgument::REQUIRED, 'A build config YAML file to validate')
+            ->setHelp('Validate a config file.')
+        ;
+    }
+
+    protected function execute(InputInterface $input, OutputInterface $output): int
+    {
+        $config = $this->yamlLoader->load($input->getArgument('config'));
+        $this->validator->validate($config);
+
+        $output->writeln('Configuration is valid.');
+
+        return 0;
+    }
+}
diff --git a/lib/php/rendition-factory/src/Config/Validator.php b/lib/php/rendition-factory/src/Config/Validator.php
new file mode 100644
index 000000000..81ee26dcd
--- /dev/null
+++ b/lib/php/rendition-factory/src/Config/Validator.php
@@ -0,0 +1,58 @@
+<?php
+
+namespace Alchemy\RenditionFactory\Config;
+
+use Alchemy\RenditionFactory\DTO\BuildConfig\BuildConfig;
+use Alchemy\RenditionFactory\DTO\FamilyEnum;
+use Alchemy\RenditionFactory\Transformer\TransformerModuleInterface;
+use Symfony\Component\Config\Definition\Exception\InvalidConfigurationException;
+use Symfony\Component\Config\Definition\Processor;
+use Symfony\Component\DependencyInjection\Attribute\TaggedLocator;
+use Symfony\Component\DependencyInjection\ServiceLocator;
+
+class Validator
+{
+    public function __construct(
+        #[TaggedLocator(TransformerModuleInterface::TAG, defaultIndexMethod: 'getName')]
+        private readonly ServiceLocator $transformers,
+    ) {
+
+    }
+
+    public function getTransformers(): ServiceLocator
+    {
+        return $this->transformers;
+    }
+
+    public function validate(BuildConfig $config): void
+    {
+        foreach (FamilyEnum::cases() as $family) {
+            $familyConfig = $config->getFamily($family);
+            if (null === $familyConfig) {
+                continue;
+            }
+            foreach ($familyConfig->getTransformations() as $transformation) {
+                $transformerName = $transformation->getModule();
+
+                /** @var TransformerModuleInterface $transformer */
+                $transformer = $this->transformers->get($transformerName);
+
+                try {
+                    $this->checkTransformerConfiguration($transformer, $transformation->toArray());
+                } catch (\Throwable $e) {
+                    $msg = sprintf("Error in module \"%s\"\n%s", $transformerName, $e->getMessage());
+                    throw new InvalidConfigurationException($msg);
+                }
+            }
+        }
+    }
+
+    private function checkTransformerConfiguration(TransformerModuleInterface $transformer, array $options): void
+    {
+        $documentation = $transformer->getDocumentation();
+        $treeBuilder = $documentation->getTreeBuilder();
+
+        $processor = new Processor();
+        $processor->process($treeBuilder->buildTree(), ['root' => $options]);
+    }
+}
diff --git a/lib/php/rendition-factory/src/DTO/BuildConfig/Transformation.php b/lib/php/rendition-factory/src/DTO/BuildConfig/Transformation.php
index 202656432..90fca1916 100644
--- a/lib/php/rendition-factory/src/DTO/BuildConfig/Transformation.php
+++ b/lib/php/rendition-factory/src/DTO/BuildConfig/Transformation.php
@@ -32,7 +32,7 @@ public function isEnabled(): bool
         return $this->enabled;
     }
 
-    public function asArray(): array
+    public function toArray(): array
     {
         return [
             'module' => $this->module,
diff --git a/lib/php/rendition-factory/src/DocumentationDumper.php b/lib/php/rendition-factory/src/DocumentationDumper.php
new file mode 100644
index 000000000..e4c01fdd8
--- /dev/null
+++ b/lib/php/rendition-factory/src/DocumentationDumper.php
@@ -0,0 +1,108 @@
+<?php
+
+namespace Alchemy\RenditionFactory;
+
+use Alchemy\RenditionFactory\Format\FormatInterface;
+use Alchemy\RenditionFactory\Transformer\Documentation;
+use Alchemy\RenditionFactory\Transformer\TransformerModuleInterface;
+use Symfony\Component\Config\Definition\Dumper\YamlReferenceDumper;
+use Symfony\Component\DependencyInjection\Attribute\TaggedLocator;
+use Symfony\Component\DependencyInjection\ServiceLocator;
+
+final readonly class DocumentationDumper
+{
+    public function __construct(
+        #[TaggedLocator(TransformerModuleInterface::TAG, defaultIndexMethod: 'getName')]
+        private ServiceLocator $transformers,
+        #[TaggedLocator(FormatInterface::TAG, defaultIndexMethod: 'getFormat')]
+        private ServiceLocator $formats,
+    ) {
+    }
+
+    public static function getName(): string
+    {
+        return 'rendition-factory';
+    }
+
+    public function dump(): string
+    {
+        $text = '';
+        foreach ($this->transformers->getProvidedServices() as $transformerName => $transformerFqcn) {
+            /** @var TransformerModuleInterface $transformer */
+            $transformer = $this->transformers->get($transformerName);
+            $text .= $this->getTransformerDocumentation($transformerName, $transformer);
+        }
+        $text .= $this->listFormats();
+
+        return $text;
+    }
+
+    private function listFormats(): string
+    {
+        $formats = [];
+        foreach ($this->formats->getProvidedServices() as $formatName => $formatFqcn) {
+            /** @var FormatInterface $format */
+            $format = $this->formats->get($formatName);
+            $family = $format->getFamily()->value;
+            if (!array_key_exists($family, $formats)) {
+                $formats[$family] = [];
+            }
+            $formats[$family][] = $format;
+        }
+        ksort($formats);
+
+        $text = '## Supported formats'."\n";
+        $text .= "| Family | Format | Mime type | Extensions |\n";
+        $text .= "|-|-|-|-|\n";
+        foreach ($formats as $familyFormats) {
+            $text .= sprintf("| %s ||||\n",
+                $familyFormats[0]->getFamily()->value,
+            );
+            foreach ($familyFormats as $format) {
+                $text .= sprintf("|| %s | %s | %s |\n",
+                    $format->getFormat(),
+                    $format->getMimeType(),
+                    implode(', ', $format->getAllowedExtensions())
+                );
+            }
+        }
+
+        return $text;
+    }
+
+    private function getTransformerDocumentation(string $transformerName, TransformerModuleInterface $transformer): string
+    {
+        $docToText = function (Documentation $documentation, int $depth = 0) use (&$docToText): string {
+
+            $text = '';
+            if ($t = $documentation->getHeader()) {
+                $text .= $t."\n";
+            }
+
+            $treeBuilder = $documentation->getTreeBuilder();
+            $node = $treeBuilder->buildTree();
+            $dumper = new YamlReferenceDumper();
+
+            $t = $dumper->dumpNode($node);
+            $t = preg_replace("#^root:($|(\s+)\[]$)#m", "-\n", (string) $t);
+            $t = preg_replace("#\n+#", "\n", $t);
+            $t = trim($t);
+
+            $text .= "```yaml\n".$t."\n```\n";
+
+            if ($t = $documentation->getFooter()) {
+                $text .= $t."\n";
+            }
+
+            foreach ($documentation->getChildren() as $child) {
+                $text .= $docToText($child, $depth + 1);
+            }
+
+            return $text;
+        };
+
+        $documentation = $transformer->getDocumentation();
+
+        return "## `$transformerName` transformer module\n".$docToText($documentation);
+    }
+}
diff --git a/lib/php/rendition-factory/src/Transformer/Document/DocumentToPdfTransformerModule.php b/lib/php/rendition-factory/src/Transformer/Document/DocumentToPdfTransformerModule.php
index 875b7f926..a14b976e9 100644
--- a/lib/php/rendition-factory/src/Transformer/Document/DocumentToPdfTransformerModule.php
+++ b/lib/php/rendition-factory/src/Transformer/Document/DocumentToPdfTransformerModule.php
@@ -19,26 +19,28 @@ public static function getName(): string
         return 'document_to_pdf';
     }
 
-    public static function getDocumentation(): Documentation
+    public function getDocumentation(): Documentation
     {
-        static $doc = null;
-        if (null === $doc) {
-            $treeBuilder = Documentation::createBaseTree(self::getName());
-            self::buildConfiguration($treeBuilder->getRootNode()->children());
-            $doc = new Documentation(
-                $treeBuilder,
-                <<<HEADER
-                **documentation to be done**.
-                HEADER
-            );
-        }
+        $treeBuilder = Documentation::createBaseTree(self::getName());
+        $this->buildConfiguration($treeBuilder->getRootNode()->children());
 
-        return $doc;
+        return new Documentation(
+            $treeBuilder,
+            <<<HEADER
+            **documentation to be done**.
+            HEADER
+        );
     }
 
-    private static function buildConfiguration(NodeBuilder $builder): void
+    public function buildConfiguration(NodeBuilder $builder): void
     {
-        // todo
+        // @formatter:off
+        $builder
+            ->arrayNode('options')
+            ->ignoreExtraKeys(false)
+            ->end()
+        ;
+        // @formatter:on
     }
 
     public function transform(InputFileInterface $inputFile, array $options, TransformationContextInterface $context): OutputFileInterface
diff --git a/lib/php/rendition-factory/src/Transformer/Document/PdfToImageTransformerModule.php b/lib/php/rendition-factory/src/Transformer/Document/PdfToImageTransformerModule.php
index fbf85a3ca..03aa1fcd6 100644
--- a/lib/php/rendition-factory/src/Transformer/Document/PdfToImageTransformerModule.php
+++ b/lib/php/rendition-factory/src/Transformer/Document/PdfToImageTransformerModule.php
@@ -20,26 +20,28 @@ public static function getName(): string
         return 'pdf_to_image';
     }
 
-    public static function getDocumentation(): Documentation
+    public function getDocumentation(): Documentation
     {
-        static $doc = null;
-        if (null === $doc) {
-            $treeBuilder = Documentation::createBaseTree(self::getName());
-            self::buildConfiguration($treeBuilder->getRootNode()->children());
-            $doc = new Documentation(
-                $treeBuilder,
-                <<<HEADER
-                **documentation to be done**.
-                HEADER
-            );
-        }
+        $treeBuilder = Documentation::createBaseTree(self::getName());
+        $this->buildConfiguration($treeBuilder->getRootNode()->children());
 
-        return $doc;
+        return new Documentation(
+            $treeBuilder,
+            <<<HEADER
+            **documentation to be done**.
+            HEADER
+        );
     }
 
-    private static function buildConfiguration(NodeBuilder $builder): void
+    public function buildConfiguration(NodeBuilder $builder): void
     {
-        // todo
+        // @formatter:off
+        $builder
+            ->arrayNode('options')
+            ->ignoreExtraKeys(false)
+            ->end()
+        ;
+        // @formatter:on
     }
 
     public function transform(InputFileInterface $inputFile, array $options, TransformationContextInterface $context): OutputFileInterface
diff --git a/lib/php/rendition-factory/src/Transformer/Image/Imagine/ImagineTransformerModule.php b/lib/php/rendition-factory/src/Transformer/Image/Imagine/ImagineTransformerModule.php
index 97c428821..61dbeab5c 100644
--- a/lib/php/rendition-factory/src/Transformer/Image/Imagine/ImagineTransformerModule.php
+++ b/lib/php/rendition-factory/src/Transformer/Image/Imagine/ImagineTransformerModule.php
@@ -26,26 +26,28 @@ public static function getName(): string
         return 'imagine';
     }
 
-    public static function getDocumentation(): Documentation
+    public function getDocumentation(): Documentation
     {
-        static $doc = null;
-        if (null === $doc) {
-            $treeBuilder = Documentation::createBaseTree(self::getName());
-            self::buildConfiguration($treeBuilder->getRootNode()->children());
-            $doc = new Documentation(
-                $treeBuilder,
-                <<<HEADER
-                **documentation to be done**.
-                HEADER
-            );
-        }
-
-        return $doc;
+        $treeBuilder = Documentation::createBaseTree(self::getName());
+        $this->buildConfiguration($treeBuilder->getRootNode()->children());
+
+        return new Documentation(
+            $treeBuilder,
+            <<<HEADER
+            **documentation to be done**.
+            HEADER
+        );
     }
 
-    private static function buildConfiguration(NodeBuilder $builder): void
+    public function buildConfiguration(NodeBuilder $builder): void
     {
-        // todo
+        // @formatter:off
+        $builder
+            ->arrayNode('options')
+                ->ignoreExtraKeys(false)
+            ->end()
+        ;
+        // @formatter:on
     }
 
     public function transform(InputFileInterface $inputFile, array $options, TransformationContextInterface $context): OutputFileInterface
diff --git a/lib/php/rendition-factory/src/Transformer/TransformerConfigHelper.php b/lib/php/rendition-factory/src/Transformer/TransformerConfigHelper.php
new file mode 100644
index 000000000..d71896ef2
--- /dev/null
+++ b/lib/php/rendition-factory/src/Transformer/TransformerConfigHelper.php
@@ -0,0 +1,64 @@
+<?php
+
+namespace Alchemy\RenditionFactory\Transformer;
+
+use Symfony\Component\Config\Definition\Builder\TreeBuilder;
+
+class TransformerConfigHelper
+{
+    /** @var Documentation[] */
+    private array $children = [];
+
+    public function __construct(private readonly TreeBuilder $treeBuilder, private readonly string $header = '', private readonly string $footer = '')
+    {
+        $this->children = [];
+    }
+
+    public function addChild(TransformerConfigHelper $child): void
+    {
+        $this->children[] = $child;
+    }
+
+    public function getChildren(): array
+    {
+        return $this->children;
+    }
+
+    public function getHeader(): string
+    {
+        return $this->header;
+    }
+
+    public function getFooter(): string
+    {
+        return $this->footer;
+    }
+
+    /**
+     * helper to create a base tree for a module, including common options.
+     */
+    public static function createBaseTree(string $name): TreeBuilder
+    {
+        $treeBuilder = new TreeBuilder('root');
+        $rootNode = $treeBuilder->getRootNode();
+        // @formatter:off
+        $rootNode
+            ->children()
+                ->scalarNode('module')
+                    ->isRequired()
+                    ->defaultValue($name)
+                ->end()
+                ->scalarNode('description')
+                    ->info('Description of the module action')
+                ->end()
+                ->scalarNode('enabled')
+                    ->defaultTrue()
+                    ->info('Whether to enable this module')
+                ->end()
+            ->end()
+        ;
+        // @formatter:on
+
+        return $treeBuilder;
+    }
+}
diff --git a/lib/php/rendition-factory/src/Transformer/TransformerModuleInterface.php b/lib/php/rendition-factory/src/Transformer/TransformerModuleInterface.php
index af4587720..97d703bf3 100644
--- a/lib/php/rendition-factory/src/Transformer/TransformerModuleInterface.php
+++ b/lib/php/rendition-factory/src/Transformer/TransformerModuleInterface.php
@@ -14,5 +14,5 @@ public static function getName(): string;
 
     public function transform(InputFileInterface $inputFile, array $options, TransformationContextInterface $context): OutputFileInterface;
 
-    public static function getDocumentation(): Documentation;
+    public function getDocumentation(): Documentation;
 }
diff --git a/lib/php/rendition-factory/src/Transformer/Video/FFMpegTransformerModule.php b/lib/php/rendition-factory/src/Transformer/Video/FFMpegTransformerModule.php
index deb36e966..71b423bf5 100644
--- a/lib/php/rendition-factory/src/Transformer/Video/FFMpegTransformerModule.php
+++ b/lib/php/rendition-factory/src/Transformer/Video/FFMpegTransformerModule.php
@@ -39,43 +39,39 @@ public static function getName(): string
         return 'ffmpeg';
     }
 
-    public static function getDocumentation(): Documentation
+    public function getDocumentation(): Documentation
     {
-        static $doc = null;
-        if (null === $doc) {
-            $treeBuilder = Documentation::createBaseTree(self::getName());
-            self::buildConfiguration($treeBuilder->getRootNode()->children());
-            $doc = new Documentation(
-                $treeBuilder,
+        $treeBuilder = Documentation::createBaseTree(self::getName());
+        $this->buildConfiguration($treeBuilder->getRootNode()->children());
+        $doc = new Documentation(
+            $treeBuilder,
+            <<<HEADER
+            apply filters to a video using FFMpeg.
+            HEADER,
+            <<<FOOTER
+            ### List of `ffmpeg` filters:
+            FOOTER
+        );
+
+        foreach ($this->getExtraConfigurationBuilders() as $name => $builder) {
+            $tree = new TreeBuilder('root');
+            $builder($tree->getRootNode());
+            $doc->addChild(new Documentation(
+                $tree,
                 <<<HEADER
-                apply filters to a video using FFMpeg.
-                HEADER,
-                <<<FOOTER
-                ### List of `ffmpeg` filters:
-                FOOTER
-            );
-
-            foreach (self::getExtraConfigurationBuilders() as $name => $builder) {
-                $tree = new TreeBuilder('root');
-                $builder($tree->getRootNode());
-                $doc->addChild(new Documentation(
-                    $tree,
-                    <<<HEADER
-                    - `$name` filter
-                    HEADER
-                ));
-            }
+                - `$name` filter
+                HEADER
+            ));
         }
 
         return $doc;
     }
 
-    private static function buildConfiguration(NodeBuilder $builder): void
+    public function buildConfiguration(NodeBuilder $builder): void
     {
         // @formatter:off
         $builder
             ->arrayNode('options')
-                ->info('Options for the module')
                 ->children()
                     ->scalarNode('format')
                         ->info('output format')
@@ -110,16 +106,12 @@ private static function buildConfiguration(NodeBuilder $builder): void
                         ->arrayPrototype()
                             ->info('see list of available filters below')
                             ->validate()->always()->then(function ($x) {
-                                self::validateFilter($x);
+                                $this->validateFilter($x);
                             })->end()
                             ->children()
                                 ->scalarNode('name')
                                     ->isRequired()
                                     ->info('Name of the filter')
-    //                                ->validate()
-    //                                    ->ifNotInArray(['pre_clip', 'remove_audio', 'resize', 'rotate', 'pad', 'crop', 'clip', 'synchronize', 'watermark', 'framerate'])
-    //                                    ->thenInvalid('Invalid filter')
-    //                                ->end()
                                 ->end()
                                 ->scalarNode('enabled')
                                     ->defaultTrue()
@@ -135,11 +127,11 @@ private static function buildConfiguration(NodeBuilder $builder): void
         // @formatter:on
     }
 
-    private static function validateFilter(array $filter): void
+    private function validateFilter(array $filter): void
     {
         $name = $filter['name'];
         unset($filter['enabled']);
-        if ($builder = self::getExtraConfigurationBuilders()[$name] ?? null) {
+        if ($builder = $this->getExtraConfigurationBuilders()[$name] ?? null) {
             $tree = new TreeBuilder($name);
             $builder($tree->getRootNode());
             $processor = new Processor();
@@ -149,7 +141,7 @@ private static function validateFilter(array $filter): void
         }
     }
 
-    private static function getExtraConfigurationBuilders(): iterable
+    private function getExtraConfigurationBuilders(): iterable
     {
         static $configurations = [
             // @formatter:off
diff --git a/lib/php/rendition-factory/src/Transformer/Video/VideoSummaryTransformerModule.php b/lib/php/rendition-factory/src/Transformer/Video/VideoSummaryTransformerModule.php
index a84a837fc..8e0f61dc2 100644
--- a/lib/php/rendition-factory/src/Transformer/Video/VideoSummaryTransformerModule.php
+++ b/lib/php/rendition-factory/src/Transformer/Video/VideoSummaryTransformerModule.php
@@ -34,29 +34,24 @@ public static function getName(): string
         return 'video_summary';
     }
 
-    public static function getDocumentation(): Documentation
+    public function getDocumentation(): Documentation
     {
-        static $doc = null;
-        if (null === $doc) {
-            $treeBuilder = Documentation::createBaseTree(self::getName());
-            self::buildConfiguration($treeBuilder->getRootNode()->children());
-            $doc = new Documentation(
-                $treeBuilder,
-                <<<HEADER
-                Assemble multiple extracts (clips) of the video.
-                HEADER
-            );
-        }
-
-        return $doc;
+        $treeBuilder = Documentation::createBaseTree(self::getName());
+        $this->buildConfiguration($treeBuilder->getRootNode()->children());
+
+        return new Documentation(
+            $treeBuilder,
+            <<<HEADER
+            Assemble multiple extracts (clips) of the video.
+            HEADER
+        );
     }
 
-    private static function buildConfiguration(NodeBuilder $builder): void
+    public function buildConfiguration(NodeBuilder $builder): void
     {
         // @formatter:off
         $builder
             ->arrayNode('options')
-                ->info('Options for the module')
                 ->children()
                     ->scalarNode('start')
                         ->defaultValue(0)
@@ -83,6 +78,16 @@ private static function buildConfiguration(NodeBuilder $builder): void
                         ->info('extension of the output file')
                         ->example('mpeg')
                     ->end()
+                    ->scalarNode('passes')
+                        ->defaultValue(2)
+                        ->info('Change the number of ffmpeg passes')
+                    ->end()
+                        ->scalarNode('timeout')
+                        ->info('Change the default timeout used by ffmpeg (defaults to symphony process timeout)')
+                    ->end()
+                    ->scalarNode('threads')
+                        ->info('Change the default number of threads used by ffmpeg')
+                    ->end()
                 ->end()
             ->end()
         ;
diff --git a/lib/php/rendition-factory/src/Transformer/Video/VideoToAnimationTransformerModule.php b/lib/php/rendition-factory/src/Transformer/Video/VideoToAnimationTransformerModule.php
index a22c145fd..bba56dfb2 100644
--- a/lib/php/rendition-factory/src/Transformer/Video/VideoToAnimationTransformerModule.php
+++ b/lib/php/rendition-factory/src/Transformer/Video/VideoToAnimationTransformerModule.php
@@ -28,29 +28,24 @@ public static function getName(): string
         return 'video_to_animation';
     }
 
-    public static function getDocumentation(): Documentation
+    public function getDocumentation(): Documentation
     {
-        static $doc = null;
-        if (null === $doc) {
-            $treeBuilder = Documentation::createBaseTree(self::getName());
-            self::buildConfiguration($treeBuilder->getRootNode()->children());
-            $doc = new Documentation(
-                $treeBuilder,
-                <<<HEADER
-                Converts a video to an animated gif / png.
-                HEADER
-            );
-        }
-
-        return $doc;
+        $treeBuilder = Documentation::createBaseTree(self::getName());
+        $this->buildConfiguration($treeBuilder->getRootNode()->children());
+
+        return new Documentation(
+            $treeBuilder,
+            <<<HEADER
+            Converts a video to an animated gif / png.
+            HEADER
+        );
     }
 
-    private static function buildConfiguration(NodeBuilder $builder): void
+    public function buildConfiguration(NodeBuilder $builder): void
     {
         // @formatter:off
         $builder
             ->arrayNode('options')
-                ->info('Options for the module')
                 ->children()
                     ->scalarNode('start')
                         ->defaultValue(0)
@@ -95,6 +90,16 @@ private static function buildConfiguration(NodeBuilder $builder): void
                         ->info('extension of the output file')
                         ->example('apng')
                     ->end()
+                    ->scalarNode('passes')
+                        ->defaultValue(2)
+                        ->info('Change the number of ffmpeg passes')
+                    ->end()
+                        ->scalarNode('timeout')
+                        ->info('Change the default timeout used by ffmpeg (defaults to symphony process timeout)')
+                    ->end()
+                    ->scalarNode('threads')
+                        ->info('Change the default number of threads used by ffmpeg')
+                    ->end()
                 ->end()
             ->end();
         // @formatter:on
diff --git a/lib/php/rendition-factory/src/Transformer/Video/VideoToFrameTransformerModule.php b/lib/php/rendition-factory/src/Transformer/Video/VideoToFrameTransformerModule.php
index 4d4239c3f..cebf7dfd1 100644
--- a/lib/php/rendition-factory/src/Transformer/Video/VideoToFrameTransformerModule.php
+++ b/lib/php/rendition-factory/src/Transformer/Video/VideoToFrameTransformerModule.php
@@ -28,29 +28,24 @@ public static function getName(): string
         return 'video_to_frame';
     }
 
-    public static function getDocumentation(): Documentation
+    public function getDocumentation(): Documentation
     {
-        static $doc = null;
-        if (null === $doc) {
-            $treeBuilder = Documentation::createBaseTree(self::getName());
-            self::buildConfiguration($treeBuilder->getRootNode()->children());
-            $doc = new Documentation(
-                $treeBuilder,
-                <<<HEADER
-                Extract one frame from the video.
-                HEADER
-            );
-        }
-
-        return $doc;
+        $treeBuilder = Documentation::createBaseTree(self::getName());
+        $this->buildConfiguration($treeBuilder->getRootNode()->children());
+
+        return new Documentation(
+            $treeBuilder,
+            <<<HEADER
+            Extract one frame from the video.
+            HEADER
+        );
     }
 
-    private static function buildConfiguration(NodeBuilder $builder): void
+    public function buildConfiguration(NodeBuilder $builder): void
     {
         // @formatter:off
         $builder
             ->arrayNode('options')
-                ->info('Options for the module')
                 ->children()
                     ->scalarNode('start')
                         ->defaultValue(0)
@@ -67,6 +62,16 @@ private static function buildConfiguration(NodeBuilder $builder): void
                         ->info('extension of the output file')
                         ->example('jpg')
                     ->end()
+                    ->scalarNode('passes')
+                        ->defaultValue(2)
+                        ->info('Change the number of ffmpeg passes')
+                    ->end()
+                    ->scalarNode('timeout')
+                        ->info('Change the default timeout used by ffmpeg (defaults to symphony process timeout)')
+                        ->end()
+                    ->scalarNode('threads')
+                        ->info('Change the default number of threads used by ffmpeg')
+                    ->end()
                 ->end()
             ->end()
         ;
diff --git a/lib/php/rendition-factory/src/Transformer/VoidTransformerModule.php b/lib/php/rendition-factory/src/Transformer/VoidTransformerModule.php
index 63628771e..7e5147db2 100644
--- a/lib/php/rendition-factory/src/Transformer/VoidTransformerModule.php
+++ b/lib/php/rendition-factory/src/Transformer/VoidTransformerModule.php
@@ -6,7 +6,6 @@
 use Alchemy\RenditionFactory\DTO\InputFileInterface;
 use Alchemy\RenditionFactory\DTO\OutputFileInterface;
 use Symfony\Component\Config\Definition\Builder\NodeBuilder;
-use Symfony\Component\Config\Definition\Builder\TreeBuilder;
 
 class VoidTransformerModule implements TransformerModuleInterface
 {
@@ -15,26 +14,21 @@ public static function getName(): string
         return 'void';
     }
 
-    public static function getDocumentation(): Documentation
+    public function getDocumentation(): Documentation
     {
-        static $doc = null;
-        if (null === $doc) {
-            $treeBuilder = new TreeBuilder('root');
-            self::buildConfiguration($treeBuilder->getRootNode()->children());
-            $doc = new Documentation(
-                $treeBuilder,
-                <<<HEADER
-                **documentation to be done**.
-                HEADER
-            );
-        }
+        $treeBuilder = Documentation::createBaseTree(self::getName());
+        $this->buildConfiguration($treeBuilder->getRootNode()->children());
 
-        return $doc;
+        return new Documentation(
+            $treeBuilder,
+            <<<HEADER
+            A module that does nothing (testing purpose)
+            HEADER
+        );
     }
 
-    private static function buildConfiguration(NodeBuilder $builder): void
+    public function buildConfiguration(NodeBuilder $builder): void
     {
-        // todo
     }
 
     public function transform(InputFileInterface $inputFile, array $options, TransformationContextInterface $context): OutputFileInterface