feat: comply with Gotenberg 8.29.0

Author: gulien

README.md

@@ -229,16 +229,17 @@ $request = Gotenberg::chromium($apiUrl)
 
 Gotenberg will automatically add the correct file extension.
 
-### Trace or request ID
+### Correlation ID
 
-By default, Gotenberg creates a *UUID* trace that identifies a request in its logs. You may override its value thanks to:
+By default, Gotenberg creates a *UUID* correlation ID that identifies a request in its logs. You may override its value
+thanks to:
 
 ```php
 use Gotenberg\Gotenberg;
 
-$request = Gotenberg::chromium('$apiUrl')
+$request = Gotenberg::chromium($apiUrl)
     ->pdf()
-    ->trace('debug')
+    ->correlationId('debug')
     ->url('https://my.url');
 ```
 
@@ -249,15 +250,15 @@ use Gotenberg\Gotenberg;
 
 $request = Gotenberg::chromium($apiUrl)
     ->pdf()
-    ->trace('debug', 'Request-Id')
+    ->correlationId('debug', 'Request-Id')
     ->url('https://my.url');
 ```
 
-Please note that it should be the same value as defined by the `--api-trace-header` Gotenberg's property.
+Please note that it should be the same value as defined by the `--api-correlation-id-header` Gotenberg's property.
 
-The response from Gotenberg will also contain the trace header. In case of error, both the `Gotenberg::send` and 
-`Gotenberg::save` methods throw a `GotenbergApiErrored` exception that provides the following method for retrieving the 
-trace:
+The response from Gotenberg will also contain the correlation ID header. In case of error, both the `Gotenberg::send`
+and `Gotenberg::save` methods throw a `GotenbergApiErrored` exception that provides the following method for retrieving
+it:
 
 ```php
 use Gotenberg\Exceptions\GotenbergApiErrored;
@@ -270,8 +271,11 @@ try {
             ->url('https://my.url')
     );
 } catch (GotenbergApiErrored $e) {
-    $trace = $e->getGotenbergTrace();
+    $correlationId = $e->getCorrelationId();
     // Or if you override the header name:
-    $trace = $e->getGotenbergTrace('Request-Id');
+    $correlationId = $e->getCorrelationId('Request-Id');
 }
 ```
+
+> [!NOTE]
+> The `trace()` and `getGotenbergTrace()` methods are deprecated but still available for backward compatibility.

src/ApiModule.php

@@ -29,15 +29,26 @@ public function __construct(string $baseUrl)
         $this->url = $baseUrl;
     }
 
+    /**
+     * Overrides the default UUID correlation ID that identifies a request in
+     * Gotenberg's logs.
+     */
+    public function correlationId(string $correlationId, string $header = 'Gotenberg-Trace'): self
+    {
+        $this->headers[$header] = $correlationId;
+
+        return $this;
+    }
+
     /**
      * Overrides the default UUID trace, or request ID, that identifies a
      * request in Gotenberg's logs.
+     *
+     * @deprecated Use correlationId() instead.
      */
     public function trace(string $trace, string $header = 'Gotenberg-Trace'): self
     {
-        $this->headers[$header] = $trace;
-
-        return $this;
+        return $this->correlationId($trace, $header);
     }
 
     protected function request(string $method, StreamInterface|null $body = null): RequestInterface

src/Exceptions/GotenbergApiErrored.php

@@ -20,11 +20,17 @@ public static function createFromResponse(ResponseInterface $response): self
         return $exception;
     }
 
-    public function getGotenbergTrace(string $header = 'Gotenberg-Trace'): string
+    public function getCorrelationId(string $header = 'Gotenberg-Trace'): string
     {
         return $this->response->getHeaderLine($header);
     }
 
+    /** @deprecated Use getCorrelationId() instead. */
+    public function getGotenbergTrace(string $header = 'Gotenberg-Trace'): string
+    {
+        return $this->getCorrelationId($header);
+    }
+
     public function getResponse(): ResponseInterface
     {
         return $this->response;

src/Modules/LibreOffice.php

@@ -230,7 +230,167 @@ public function addOriginalDocumentAsStream(): self
     }
 
     /**
-     * Ignores each sheet’s paper size, print ranges and shown/hidden status
+     * Specifies how the document shall be displayed when opened. Possible
+     * values are: "document", "outline", "thumbnails".
+     */
+    public function initialView(string $view): self
+    {
+        $this->formValue('initialView', $view);
+
+        return $this;
+    }
+
+    /**
+     * Specifies the page on which a PDF document should be opened in the
+     * viewer.
+     */
+    public function initialPage(int $page): self
+    {
+        $this->formValue('initialPage', $page);
+
+        return $this;
+    }
+
+    /**
+     * Specifies the magnification to use when the document is opened.
+     * Possible values are: "default", "fitVisible", "fitWidth", "fitPage",
+     * "fitActualSize".
+     */
+    public function magnification(string $magnification): self
+    {
+        $this->formValue('magnification', $magnification);
+
+        return $this;
+    }
+
+    /**
+     * Specifies the zoom value to use when the document is opened.
+     */
+    public function zoom(int $zoom): self
+    {
+        $this->formValue('zoom', $zoom);
+
+        return $this;
+    }
+
+    /**
+     * Specifies the page layout to use when the document is opened. Possible
+     * values are: "default", "singlePage", "continuous", "continuousFacing".
+     */
+    public function pageLayout(string $layout): self
+    {
+        $this->formValue('pageLayout', $layout);
+
+        return $this;
+    }
+
+    /**
+     * Specifies that the first page on the left side of the viewer should be
+     * displayed in a two-column layout.
+     */
+    public function firstPageOnLeft(): self
+    {
+        $this->formValue('firstPageOnLeft', true);
+
+        return $this;
+    }
+
+    /**
+     * Specifies that the PDF viewer window should be resized to fit the size
+     * of the first page of the document.
+     */
+    public function resizeWindowToInitialPage(): self
+    {
+        $this->formValue('resizeWindowToInitialPage', true);
+
+        return $this;
+    }
+
+    /**
+     * Specifies that the PDF viewer window should be centered on the screen.
+     */
+    public function centerWindow(): self
+    {
+        $this->formValue('centerWindow', true);
+
+        return $this;
+    }
+
+    /**
+     * Specifies that the PDF document should be displayed in full-screen mode.
+     */
+    public function openInFullScreenMode(): self
+    {
+        $this->formValue('openInFullScreenMode', true);
+
+        return $this;
+    }
+
+    /**
+     * Specifies that the title of the document should be displayed in the
+     * title bar of the viewer.
+     */
+    public function displayPDFDocumentTitle(): self
+    {
+        $this->formValue('displayPDFDocumentTitle', true);
+
+        return $this;
+    }
+
+    /**
+     * Specifies that the viewer's menu bar should be hidden.
+     */
+    public function hideViewerMenubar(): self
+    {
+        $this->formValue('hideViewerMenubar', true);
+
+        return $this;
+    }
+
+    /**
+     * Specifies that the viewer's toolbar should be hidden.
+     */
+    public function hideViewerToolbar(): self
+    {
+        $this->formValue('hideViewerToolbar', true);
+
+        return $this;
+    }
+
+    /**
+     * Specifies that the viewer's window controls should be hidden.
+     */
+    public function hideViewerWindowControls(): self
+    {
+        $this->formValue('hideViewerWindowControls', true);
+
+        return $this;
+    }
+
+    /**
+     * Specifies whether to use transition effects when displaying the
+     * document.
+     */
+    public function useTransitionEffects(): self
+    {
+        $this->formValue('useTransitionEffects', true);
+
+        return $this;
+    }
+
+    /**
+     * Specifies the number of bookmark levels to display in the viewer when
+     * the document is opened.
+     */
+    public function openBookmarkLevels(int $levels): self
+    {
+        $this->formValue('openBookmarkLevels', $levels);
+
+        return $this;
+    }
+
+    /**
+     * Ignores each sheet's paper size, print ranges and shown/hidden status
      * and puts every sheet (even hidden sheets) on exactly one page.
      */
     public function singlePageSheets(): self

src/MultipartFormDataModule.php

@@ -109,6 +109,17 @@ public function webhookExtraHttpHeaders(array $headers): self
         return $this;
     }
 
+    /**
+     * Sets the URL that Gotenberg will use to send webhook event
+     * notifications (e.g., success/error events after webhook delivery).
+     */
+    public function webhookEventsUrl(string $url): self
+    {
+        $this->headers['Gotenberg-Webhook-Events-Url'] = $url;
+
+        return $this;
+    }
+
     /**
      * Configures watermarking on the resulting PDF(s).
      * Only non-empty values are set.

tests/ApiModuleTest.php

@@ -10,14 +10,25 @@
 final class ApiModuleTest extends TestCase
 {
     #[Test]
-    public function it_creates_a_valid_request_with_a_trace_header(): void
+    public function it_creates_a_valid_request_with_a_correlation_id_header(): void
     {
         $dummy   = new DummyApiModule('https://my.url/');
         $request = $dummy
-            ->trace('debug')
+            ->correlationId('debug')
             ->build();
 
         $this->assertSame('https://my.url', $dummy->getUrl());
         $this->assertSame(['debug'], $request->getHeader('Gotenberg-Trace'));
     }
+
+    #[Test]
+    public function it_creates_a_valid_request_with_a_deprecated_trace_header(): void
+    {
+        $dummy   = new DummyApiModule('https://my.url/');
+        $request = $dummy
+            ->trace('debug')
+            ->build();
+
+        $this->assertSame(['debug'], $request->getHeader('Gotenberg-Trace'));
+    }
 }

tests/GotenbergTest.php

@@ -44,7 +44,7 @@ public function it_sends_a_request_and_throws_an_exception_if_response_is_not_2x
         } catch (GotenbergApiErrored $e) {
             $this->assertSame(400, $e->getCode());
             $this->assertSame('Bad Request', $e->getMessage());
-            $this->assertSame($withTrace ? 'debug' : '', $e->getGotenbergTrace());
+            $this->assertSame($withTrace ? 'debug' : '', $e->getCorrelationId());
             $this->assertSame($response, $e->getResponse());
         }
     }