feat(pdfengines): add embed metadata

Author: gulien

src/EmbedMetadata.php

@@ -0,0 +1,42 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Gotenberg;
+
+use JsonSerializable;
+
+class EmbedMetadata implements JsonSerializable
+{
+    public const FIELD_MIME_TYPE    = 'mimeType';
+    public const FIELD_RELATIONSHIP = 'relationship';
+
+    public const RELATIONSHIP_SOURCE      = 'Source';
+    public const RELATIONSHIP_DATA        = 'Data';
+    public const RELATIONSHIP_ALTERNATIVE = 'Alternative';
+    public const RELATIONSHIP_SUPPLEMENT  = 'Supplement';
+    public const RELATIONSHIP_UNSPECIFIED = 'Unspecified';
+
+    public function __construct(
+        public readonly string $filename,
+        public readonly string|null $mimeType = null,
+        public readonly string|null $relationship = null,
+    ) {
+    }
+
+    /** @return array<string,string> */
+    public function jsonSerialize(): array
+    {
+        $serialized = [];
+
+        if ($this->mimeType !== null) {
+            $serialized[self::FIELD_MIME_TYPE] = $this->mimeType;
+        }
+
+        if ($this->relationship !== null) {
+            $serialized[self::FIELD_RELATIONSHIP] = $this->relationship;
+        }
+
+        return $serialized;
+    }
+}

src/Modules/ChromiumPdf.php

@@ -4,6 +4,7 @@
 
 namespace Gotenberg\Modules;
 
+use Gotenberg\EmbedMetadata;
 use Gotenberg\Exceptions\NativeFunctionErrored;
 use Gotenberg\SplitMode;
 use Gotenberg\Stream;
@@ -248,6 +249,29 @@ public function embeds(Stream ...$embeds): self
         return $this;
     }
 
+    /**
+     * Sets metadata on embedded files in the resulting PDF, required for
+     * Factur-X / ZUGFeRD compliance.
+     *
+     * @throws NativeFunctionErrored
+     */
+    public function embedsMetadata(EmbedMetadata ...$metadata): self
+    {
+        $map = [];
+        foreach ($metadata as $entry) {
+            $map[$entry->filename] = $entry;
+        }
+
+        $json = json_encode($map);
+        if ($json === false) {
+            throw NativeFunctionErrored::createFromLastPhpError();
+        }
+
+        $this->formValue('embedsMetadata', $json);
+
+        return $this;
+    }
+
     /**
      * Converts a target URL to PDF.
      *

src/Modules/LibreOffice.php

@@ -4,6 +4,7 @@
 
 namespace Gotenberg\Modules;
 
+use Gotenberg\EmbedMetadata;
 use Gotenberg\Exceptions\NativeFunctionErrored;
 use Gotenberg\HrtimeIndex;
 use Gotenberg\Index;
@@ -601,6 +602,29 @@ public function embeds(Stream ...$embeds): self
         return $this;
     }
 
+    /**
+     * Sets metadata on embedded files in the resulting PDF, required for
+     * Factur-X / ZUGFeRD compliance.
+     *
+     * @throws NativeFunctionErrored
+     */
+    public function embedsMetadata(EmbedMetadata ...$metadata): self
+    {
+        $map = [];
+        foreach ($metadata as $entry) {
+            $map[$entry->filename] = $entry;
+        }
+
+        $json = json_encode($map);
+        if ($json === false) {
+            throw NativeFunctionErrored::createFromLastPhpError();
+        }
+
+        $this->formValue('embedsMetadata', $json);
+
+        return $this;
+    }
+
     /**
      * Converts the given document(s) to PDF(s). Gotenberg will return either
      * a unique PDF if you request a merge or a ZIP archive with the PDFs.

src/Modules/PdfEngines.php

@@ -4,6 +4,7 @@
 
 namespace Gotenberg\Modules;
 
+use Gotenberg\EmbedMetadata;
 use Gotenberg\Exceptions\NativeFunctionErrored;
 use Gotenberg\HrtimeIndex;
 use Gotenberg\Index;
@@ -105,6 +106,29 @@ public function embeds(Stream ...$embeds): self
         return $this;
     }
 
+    /**
+     * Sets metadata on embedded files in the resulting PDF, required for
+     * Factur-X / ZUGFeRD compliance.
+     *
+     * @throws NativeFunctionErrored
+     */
+    public function embedsMetadata(EmbedMetadata ...$metadata): self
+    {
+        $map = [];
+        foreach ($metadata as $entry) {
+            $map[$entry->filename] = $entry;
+        }
+
+        $json = json_encode($map);
+        if ($json === false) {
+            throw NativeFunctionErrored::createFromLastPhpError();
+        }
+
+        $this->formValue('embedsMetadata', $json);
+
+        return $this;
+    }
+
     /**
      * Merges PDFs into a unique PDF.
      *

tests/EmbedMetadataTest.php

@@ -0,0 +1,64 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Gotenberg\Test;
+
+use Gotenberg\EmbedMetadata;
+use PHPUnit\Framework\Attributes\Test;
+
+use function json_encode;
+
+final class EmbedMetadataTest extends TestCase
+{
+    #[Test]
+    public function it_serializes_all_fields(): void
+    {
+        $metadata = new EmbedMetadata(
+            'embed_1.xml',
+            'text/xml',
+            EmbedMetadata::RELATIONSHIP_DATA,
+        );
+
+        $this->assertSame(
+            '{"mimeType":"text\/xml","relationship":"Data"}',
+            json_encode($metadata),
+        );
+    }
+
+    #[Test]
+    public function it_serializes_only_mime_type(): void
+    {
+        $metadata = new EmbedMetadata('embed_1.xml', 'text/xml');
+
+        $this->assertSame('{"mimeType":"text\/xml"}', json_encode($metadata));
+    }
+
+    #[Test]
+    public function it_serializes_only_relationship(): void
+    {
+        $metadata = new EmbedMetadata(
+            'embed_1.xml',
+            null,
+            EmbedMetadata::RELATIONSHIP_ALTERNATIVE,
+        );
+
+        $this->assertSame('{"relationship":"Alternative"}', json_encode($metadata));
+    }
+
+    #[Test]
+    public function it_serializes_to_empty_when_no_optional_fields(): void
+    {
+        $metadata = new EmbedMetadata('embed_1.xml');
+
+        $this->assertSame('[]', json_encode($metadata));
+    }
+
+    #[Test]
+    public function it_exposes_filename_as_a_public_property(): void
+    {
+        $metadata = new EmbedMetadata('embed_1.xml', 'text/xml');
+
+        $this->assertSame('embed_1.xml', $metadata->filename);
+    }
+}