feat: add read/write metadata

gotenberg · Mar 23, 2024 · 66afd63 · 66afd63
1 parent 0309bfb
commit 66afd63
Show file tree

Hide file tree

Showing 7 changed files with 329 additions and 10 deletions.
diff --git a/README.md b/README.md
@@ -625,6 +625,21 @@ $request = Gotenberg::chromium($apiUrl)
     ->url('https://my.url');
 ```
 
+#### Metadata
+
+See https://gotenberg.dev/docs/routes#metadata-chromium.
+
+You may set the metadata to write with:
+
+```php
+use Gotenberg\Gotenberg;
+
+$request = Gotenberg::chromium($apiUrl)
+    ->pdf()
+    ->metadata(['Producer' => 'Gotenberg'])
+    ->url('https://my.url');
+```
+
 #### Screenshots
 
 You can capture full-page screenshots using the following three routes, which function similarly to their PDF equivalents:
@@ -781,6 +796,20 @@ $request = Gotenberg::libreOffice($apiUrl)
     ->convert(Stream::path('/path/to/my.docx'));
 ```
 
+#### Metadata
+
+See https://gotenberg.dev/docs/routes#metadata-libreoffice.
+
+You may set the metadata to write with:
+
+```php
+use Gotenberg\Gotenberg;
+
+$request = Gotenberg::libreOffice($apiUrl)
+    ->metadata(['Producer' => 'Gotenberg'])
+    ->convert(Stream::path('/path/to/my.docx'));
+```
+
 ### PDF Engines
 
 The [PDF Engines module](https://gotenberg.dev/docs/configuration#pdf-engines) gathers all engines that can manipulate PDF files.
@@ -857,6 +886,63 @@ $request = Gotenberg::pdfEngines($apiUrl)
 $filename = Gotenberg::save($request, $pathToSavingDirectory);
 ```
 
+#### Read PDF metadata
+
+See https://gotenberg.dev/docs/routes#read-pdf-metadata-route
+
+⚠️ You cannot use the `Gotenberg::save` method if you're using this feature.
+
+You may retrieve one or more PDFs metadata with:
+
+```php
+use Gotenberg\Gotenberg;
+use Gotenberg\Stream;
+
+$request = Gotenberg::pdfEngines($apiUrl)
+    ->readMetadata(
+        Stream::path('/path/to/my.pdf'),
+        Stream::path('/path/to/my2.pdf')
+    );
+```
+
+This request returns a JSON formatted response with the structure filename => metadata.
+
+#### Write PDF metadata
+
+See https://gotenberg.dev/docs/routes#write-pdf-metadata-route
+
+You may write specified metadata to one or more PDFs:
+
+```php
+use Gotenberg\Gotenberg;
+use Gotenberg\Stream;
+
+$request = Gotenberg::pdfEngines($apiUrl)
+    ->writeMetadata(
+        [ 'Producer' => 'Gotenberg' ],
+        Stream::path('/path/to/my.pdf')
+    );
+```
+
+If you send many PDFs, Gotenberg will return a ZIP archive with the PDFs:
+
+```php
+use Gotenberg\Gotenberg;
+use Gotenberg\Stream;
+
+$request = Gotenberg::pdfEngines($apiUrl)
+    ->outputFilename('archive')
+    ->writeMetadata(
+        [ 'Producer' => 'Gotenberg' ],
+        Stream::path('/path/to/my.pdf'),
+        Stream::path('/path/to/my2.pdf'),
+        Stream::path('/path/to/my3.pdf')
+    );
+
+// $filename = archive.zip
+$filename = Gotenberg::save($request, $pathToSavingDirectory);
+```
+
 ### Webhook
 
 The [Webhook module](https://gotenberg.dev/docs/webhook) is a Gotenberg middleware that sends the API

diff --git a/src/Modules/ChromiumPdf.php b/src/Modules/ChromiumPdf.php
@@ -8,6 +8,8 @@
 use Gotenberg\Stream;
 use Psr\Http\Message\RequestInterface;
 
+use function json_encode;
+
 class ChromiumPdf
 {
     use ChromiumMultipartFormDataModule;
@@ -161,6 +163,25 @@ public function pdfua(): self
         return $this;
     }
 
+    /**
+     * Sets the metadata to write.
+     *
+     * @param array<string,string|bool|float|int|array<string>> $metadata
+     *
+     * @throws NativeFunctionErrored
+     */
+    public function metadata(array $metadata): self
+    {
+        $json = json_encode($metadata);
+        if ($json === false) {
+            throw NativeFunctionErrored::createFromLastPhpError();
+        }
+
+        $this->formValue('metadata', $json);
+
+        return $this;
+    }
+
     /**
      * Converts a target URL to PDF.
      *

diff --git a/src/Modules/LibreOffice.php b/src/Modules/LibreOffice.php
@@ -4,12 +4,15 @@
 
 namespace Gotenberg\Modules;
 
+use Gotenberg\Exceptions\NativeFunctionErrored;
 use Gotenberg\HrtimeIndex;
 use Gotenberg\Index;
 use Gotenberg\MultipartFormDataModule;
 use Gotenberg\Stream;
 use Psr\Http\Message\RequestInterface;
 
+use function json_encode;
+
 class LibreOffice
 {
     use MultipartFormDataModule;
@@ -82,6 +85,25 @@ public function pdfua(): self
         return $this;
     }
 
+    /**
+     * Sets the metadata to write.
+     *
+     * @param array<string,string|bool|float|int|array<string>> $metadata
+     *
+     * @throws NativeFunctionErrored
+     */
+    public function metadata(array $metadata): self
+    {
+        $json = json_encode($metadata);
+        if ($json === false) {
+            throw NativeFunctionErrored::createFromLastPhpError();
+        }
+
+        $this->formValue('metadata', $json);
+
+        return $this;
+    }
+
     /**
      * Merges the resulting PDFs.
      */

diff --git a/src/Modules/PdfEngines.php b/src/Modules/PdfEngines.php
@@ -4,12 +4,15 @@
 
 namespace Gotenberg\Modules;
 
+use Gotenberg\Exceptions\NativeFunctionErrored;
 use Gotenberg\HrtimeIndex;
 use Gotenberg\Index;
 use Gotenberg\MultipartFormDataModule;
 use Gotenberg\Stream;
 use Psr\Http\Message\RequestInterface;
 
+use function json_encode;
+
 class PdfEngines
 {
     use MultipartFormDataModule;
@@ -47,6 +50,25 @@ public function pdfua(): self
         return $this;
     }
 
+    /**
+     * Sets the metadata to write.
+     *
+     * @param array<string,string|bool|float|int|array<string>> $metadata
+     *
+     * @throws NativeFunctionErrored
+     */
+    public function metadata(array $metadata): self
+    {
+        $json = json_encode($metadata);
+        if ($json === false) {
+            throw NativeFunctionErrored::createFromLastPhpError();
+        }
+
+        $this->formValue('metadata', $json);
+
+        return $this;
+    }
+
     /**
      * Merges PDFs into a unique PDF.
      *
@@ -85,4 +107,42 @@ public function convert(string $pdfa, Stream $pdf, Stream ...$pdfs): RequestInte
 
         return $this->request();
     }
+
+    /**
+     * Retrieves the metadata of specified PDFs, returning a JSON formatted
+     * response with the structure filename => metadata.
+     */
+    public function readMetadata(Stream $pdf, Stream ...$pdfs): RequestInterface
+    {
+        $this->formFile($pdf->getFilename(), $pdf->getStream());
+
+        foreach ($pdfs as $pdf) {
+            $this->formFile($pdf->getFilename(), $pdf->getStream());
+        }
+
+        $this->endpoint = '/forms/pdfengines/metadata/read';
+
+        return $this->request();
+    }
+
+    /**
+     * Allows writing specified metadata to one or more PDF.
+     *
+     * @param array<string,string|bool|float|int|array<string>> $metadata
+     *
+     * @throws NativeFunctionErrored
+     */
+    public function writeMetadata(array $metadata, Stream $pdf, Stream ...$pdfs): RequestInterface
+    {
+        $this->metadata($metadata);
+        $this->formFile($pdf->getFilename(), $pdf->getStream());
+
+        foreach ($pdfs as $pdf) {
+            $this->formFile($pdf->getFilename(), $pdf->getStream());
+        }
+
+        $this->endpoint = '/forms/pdfengines/metadata/write';
+
+        return $this->request();
+    }
 }