Feature: Add a builder to write pdf metadata

config/builder_pdf.php

@@ -6,6 +6,7 @@
 use Sensiolabs\GotenbergBundle\Builder\Pdf\MarkdownPdfBuilder;
 use Sensiolabs\GotenbergBundle\Builder\Pdf\MergePdfBuilder;
 use Sensiolabs\GotenbergBundle\Builder\Pdf\UrlPdfBuilder;
+use Sensiolabs\GotenbergBundle\Builder\Pdf\WriteMetadataPdfBuilder;
 use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;
 use function Symfony\Component\DependencyInjection\Loader\Configurator\service;
 
@@ -71,6 +72,16 @@
         ->tag('sensiolabs_gotenberg.pdf_builder')
     ;
 
+    $services->set('.sensiolabs_gotenberg.pdf_builder.write_metadata', WriteMetadataPdfBuilder::class)
+        ->share(false)
+        ->args([
+            service('sensiolabs_gotenberg.client'),
+            service('sensiolabs_gotenberg.asset.base_dir_formatter'),
+        ])
+        ->call('setLogger', [service('logger')->nullOnInvalid()])
+        ->tag('sensiolabs_gotenberg.pdf_builder')
+    ;
+
     $services->set('.sensiolabs_gotenberg.pdf_builder.convert', ConvertPdfBuilder::class)
         ->share(false)
         ->args([

docs/pdf/merge-builder.md

@@ -1,6 +1,6 @@
 # Merge Builder
 
-You may have the possibility to merge several PDF document.
+You may have the possibility to merge several PDF documents.
 
 ## Basic usage
 

docs/pdf/write-metadata-builder.md

@@ -0,0 +1,91 @@
+# Write metadata Builder
+
+You may have the possibility to write metadata within several PDF documents.
+
+## Basic usage
+
+> [!WARNING]  
+> As assets files, by default the PDF files are fetch in the assets folder of
+> your application.  
+> For more information about path resolution go to [assets documentation](../assets.md).
+
+```php
+    namespace App\Controller;
+
+    use Sensiolabs\GotenbergBundle\GotenbergPdfInterface;
+
+    class YourController
+    {
+        public function yourControllerMethod(GotenbergPdfInterface $gotenberg): Response
+        {
+            return $gotenberg->writeMetadata()
+                ->files(
+                    'document.pdf',
+                    'document_2.pdf',
+                )
+                ->generate()
+             ;
+        }
+    }
+```
+
+> [!TIP]
+> For more information go to [Gotenberg documentations](https://gotenberg.dev/docs/routes#read-pdf-metadata-route).
+
+> [!TIP]
+> Not all metadata are writable. Consider taking a look at https://exiftool.org/TagNames/XMP.html#pdf
+> for an (exhaustive?) list of available metadata.
+
+## metatada
+
+Default: `None`
+
+Resets the configuration metadata and add new ones to write.
+
+```php
+    namespace App\Controller;
+
+    use Sensiolabs\GotenbergBundle\Enum\PdfFormat;use Sensiolabs\GotenbergBundle\GotenbergPdfInterface;
+
+    class YourController
+    {
+        public function yourControllerMethod(GotenbergPdfInterface $gotenberg): Response
+        {
+            return $gotenberg->writeMetadata()
+               ->files(
+                    'document.pdf',
+                    'document_2.pdf',
+                )
+                ->metadata(['Author' => 'SensioLabs', 'Subject' => 'Gotenberg'])
+                ->generate()
+             ;
+        }
+    }
+```
+
+## addMetadata
+
+Default: `None`
+
+If you want to add metadata from the ones already loaded in the configuration.
+
+```php
+    namespace App\Controller;
+
+    use Sensiolabs\GotenbergBundle\Enum\PdfFormat;use Sensiolabs\GotenbergBundle\GotenbergPdfInterface;
+
+    class YourController
+    {
+        public function yourControllerMethod(GotenbergPdfInterface $gotenberg): Response
+        {
+            return $gotenberg->writeMetadata()
+               ->files(
+                    'document.pdf',
+                    'document_2.pdf',
+                )
+                ->addMetadata('key', 'value')
+                ->generate()
+             ;
+        }
+    }
+```

src/Builder/Pdf/WriteMetadataPdfBuilder.php

@@ -0,0 +1,94 @@
+<?php
+
+namespace Sensiolabs\GotenbergBundle\Builder\Pdf;
+
+use Sensiolabs\GotenbergBundle\Exception\InvalidBuilderConfiguration;
+use Sensiolabs\GotenbergBundle\Exception\MissingRequiredFieldException;
+use Symfony\Component\Mime\Part\DataPart;
+use Symfony\Component\Mime\Part\File as DataPartFile;
+
+final class WriteMetadataPdfBuilder extends AbstractPdfBuilder
+{
+    private const ENDPOINT = '/forms/pdfengines/metadata/write';
+
+    /**
+     * To set configurations by an array of configurations.
+     *
+     * @param array<string, mixed> $configurations
+     */
+    public function setConfigurations(array $configurations): static
+    {
+        foreach ($configurations as $property => $value) {
+            $this->addConfiguration($property, $value);
+        }
+
+        return $this;
+    }
+
+    public function files(string ...$paths): self
+    {
+        $this->formFields['files'] = [];
+
+        foreach ($paths as $path) {
+            $this->assertFileExtension($path, ['pdf']);
+
+            $dataPart = new DataPart(new DataPartFile($this->asset->resolve($path)));
+
+            $this->formFields['files'][$path] = $dataPart;
+        }
+
+        return $this;
+    }
+
+    /**
+     * Resets the metadata.
+     *
+     * @see https://gotenberg.dev/docs/routes#metadata-chromium
+     * @see https://exiftool.org/TagNames/XMP.html#pdf
+     *
+     * @param array<string, mixed> $metadata
+     */
+    public function metadata(array $metadata): static
+    {
+        $this->formFields['metadata'] = $metadata;
+
+        return $this;
+    }
+
+    /**
+     * The metadata to write.
+     */
+    public function addMetadata(string $key, string $value): static
+    {
+        $this->formFields['metadata'] ??= [];
+        $this->formFields['metadata'][$key] = $value;
+
+        return $this;
+    }
+
+    public function getMultipartFormData(): array
+    {
+        if ([] === ($this->formFields['files'] ?? [])) {
+            throw new MissingRequiredFieldException('At least one PDF file is required');
+        }
+
+        if ([] === ($this->formFields['metadata'] ?? [])) {
+            throw new MissingRequiredFieldException('At least one metadata field is required');
+        }
+
+        return parent::getMultipartFormData();
+    }
+
+    protected function getEndpoint(): string
+    {
+        return self::ENDPOINT;
+    }
+
+    private function addConfiguration(string $configurationName, mixed $value): void
+    {
+        match ($configurationName) {
+            'metadata' => $this->metadata($value),
+            default => throw new InvalidBuilderConfiguration(sprintf('Invalid option "%s": no method does not exist in class "%s" to configured it.', $configurationName, self::class)),
+        };
+    }
+}

src/Debug/TraceableGotenbergPdf.php

@@ -9,6 +9,7 @@
 use Sensiolabs\GotenbergBundle\Builder\Pdf\MergePdfBuilder;
 use Sensiolabs\GotenbergBundle\Builder\Pdf\PdfBuilderInterface;
 use Sensiolabs\GotenbergBundle\Builder\Pdf\UrlPdfBuilder;
+use Sensiolabs\GotenbergBundle\Builder\Pdf\WriteMetadataPdfBuilder;
 use Sensiolabs\GotenbergBundle\Debug\Builder\TraceablePdfBuilder;
 use Sensiolabs\GotenbergBundle\GotenbergPdfInterface;
 
@@ -122,6 +123,23 @@ public function merge(): PdfBuilderInterface
         return $traceableBuilder;
     }
 
+    /**
+     * @return WriteMetadataPdfBuilder|TraceablePdfBuilder
+     */
+    public function writeMetadata(): PdfBuilderInterface
+    {
+        /** @var WriteMetadataPdfBuilder|TraceablePdfBuilder $traceableBuilder */
+        $traceableBuilder = $this->inner->writeMetadata();
+
+        if (!$traceableBuilder instanceof TraceablePdfBuilder) {
+            return $traceableBuilder;
+        }
+
+        $this->builders[] = ['write_metadata', $traceableBuilder];
+
+        return $traceableBuilder;
+    }
+
     /**
      * @return ConvertPdfBuilder|TraceablePdfBuilder
      */

src/GotenbergPdf.php

@@ -10,6 +10,7 @@
 use Sensiolabs\GotenbergBundle\Builder\Pdf\MergePdfBuilder;
 use Sensiolabs\GotenbergBundle\Builder\Pdf\PdfBuilderInterface;
 use Sensiolabs\GotenbergBundle\Builder\Pdf\UrlPdfBuilder;
+use Sensiolabs\GotenbergBundle\Builder\Pdf\WriteMetadataPdfBuilder;
 
 final class GotenbergPdf implements GotenbergPdfInterface
 {
@@ -24,14 +25,15 @@ public function get(string $builder): PdfBuilderInterface
     }
 
     /**
-     * @param 'html'|'url'|'markdown'|'office'|'merge'|'convert' $key
+     * @param 'html'|'url'|'markdown'|'office'|'merge'|'write_metadata'|'convert' $key
      *
      * @return (
      *   $key is 'html' ? HtmlPdfBuilder :
      *   $key is 'url' ? UrlPdfBuilder :
      *   $key is 'markdown' ? MarkdownPdfBuilder :
      *   $key is 'office' ? LibreOfficePdfBuilder :
      *   $key is 'merge' ? MergePdfBuilder :
+     *   $key is 'write_metadata' ? WriteMetadataPdfBuilder :
      *   $key is 'convert' ? ConvertPdfBuilder :
      *   PdfBuilderInterface
      * )
@@ -66,6 +68,11 @@ public function merge(): PdfBuilderInterface
         return $this->getInternal('merge');
     }
 
+    public function writeMetadata(): PdfBuilderInterface
+    {
+        return $this->getInternal('write_metadata');
+    }
+
     public function convert(): PdfBuilderInterface
     {
         return $this->getInternal('convert');

src/GotenbergPdfInterface.php

@@ -9,6 +9,7 @@
 use Sensiolabs\GotenbergBundle\Builder\Pdf\MergePdfBuilder;
 use Sensiolabs\GotenbergBundle\Builder\Pdf\PdfBuilderInterface;
 use Sensiolabs\GotenbergBundle\Builder\Pdf\UrlPdfBuilder;
+use Sensiolabs\GotenbergBundle\Builder\Pdf\WriteMetadataPdfBuilder;
 
 interface GotenbergPdfInterface
 {
@@ -46,6 +47,11 @@ public function markdown(): PdfBuilderInterface;
      */
     public function merge(): PdfBuilderInterface;
 
+    /**
+     * @return WriteMetadataPdfBuilder
+     */
+    public function writeMetadata(): PdfBuilderInterface;
+
     /**
      * @return ConvertPdfBuilder
      */