Gotenberg PHP

https://github.com/gotenberg/gotenberg-php
Admin
A PHP client for Gotenberg, a developer-friendly API for converting documents to PDF using tools...
Tokens:79,637
Snippets:618
Trust Score:7.6
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Viewer Configuration Example

Source: https://github.com/gotenberg/gotenberg-php/blob/main/_autodocs/api-reference/modules/libreoffice-pdf-options.md

Example demonstrating how to chain multiple viewer option methods when creating a LibreOffice conversion request.

```APIDOC
## Example: Viewer Configuration

```php
use Gotenberg\Gotenberg;

$request = Gotenberg::libreOffice('http://localhost:3000')
    ->initialView('outline')
    ->initialPage(2)
    ->magnification('fitWidth')
    ->displayPDFDocumentTitle()
    ->hideViewerToolbar()
    ->convert(Stream::path('manual.odt'));
```
```

--------------------------------

### Example of generated prefix ordering

Source: https://github.com/gotenberg/gotenberg-php/blob/main/_autodocs/api-reference/index.md

Shows example multipart filenames generated by the default HrtimeIndex when merging a.docx and b.docx.

```text
1690000000123456789_a.docx
1690000000123456790_b.docx
```

--------------------------------

### Basic call example

Source: https://github.com/gotenberg/gotenberg-php/blob/main/_autodocs/api-reference/gotenberg.md

Builds a Chromium PDF request and sends it, then retrieves the PDF body from the response.

```php
use Gotenberg\Gotenberg;

$request = Gotenberg::chromium('http://localhost:3000')
    ->pdf()
    ->url('https://my.url');

$response = Gotenberg::send($request);
$pdfBody  = (string) $response->getBody();
```

--------------------------------

### Install dependencies and run checks

Source: https://github.com/gotenberg/gotenberg-php/blob/main/CONTRIBUTING.md

Run Composer commands to install dependencies, fix coding standards, run static analysis, and execute tests.

```bash
composer install
composer run lint:fix  # Auto-fix coding standard violations
composer run lint      # phpcs + phpstan at max level (zero errors permitted)
composer run tests     # PHPUnit with coverage
composer run all       # lint:fix + lint + tests
```

--------------------------------

### Example - plain download with DownloadFrom

Source: https://github.com/gotenberg/gotenberg-php/blob/main/_autodocs/api-reference/download-from.md

Shows how to use downloadFrom() with an array of DownloadFrom instances to fetch remote files. The first instance includes extra HTTP headers, the second does not.

```php
use Gotenberg\DownloadFrom;
use Gotenberg\Gotenberg;

$request = Gotenberg::libreOffice('http://localhost:3000')
    ->downloadFrom([
        new DownloadFrom('https://url.to/document.docx', ['MyHeader' => 'MyValue']),
        new DownloadFrom('https://url.to/logo.png'),
    ])
    ->convert();
```

--------------------------------

### Install Gotenberg PHP package via Composer

Source: https://github.com/gotenberg/gotenberg-php/blob/main/README.md

Installs the gotenberg/gotenberg-php package using Composer. Requires Composer to be installed.

```bash
composer require gotenberg/gotenberg-php
```

--------------------------------

### Usage example for Chromium factory

Source: https://github.com/gotenberg/gotenberg-php/blob/main/_autodocs/api-reference/modules/chromium.md

Shows how to create ChromiumPdf and ChromiumScreenshot builders using the static factory Gotenberg::chromium().

```php
use Gotenberg\Gotenberg;

$pdf  = Gotenberg::chromium('http://localhost:3000');      // Chromium
$req1 = $pdf->pdf()->url('https://my.url');                // ChromiumPdf
$req2 = $pdf->screenshot()->png()->width(800)->url('https://my.url'); // ChromiumScreenshot
```

--------------------------------

### Combined example

Source: https://github.com/gotenberg/gotenberg-php/blob/main/_autodocs/api-reference/modules/chromium.md

Shows a complete PDF request using multiple Chromium options: waitDelay, waitForExpression, emulateScreenMediaType, extraHttpHeaders, cookies, assets, and html.

```php
use Gotenberg\Gotenberg;
use Gotenberg\Modules\ChromiumCookie;
use Gotenberg\Stream;

$request = Gotenberg::chromium('http://localhost:3000')
    ->pdf()
    ->waitDelay('2s')
    ->waitForExpression("window.status === 'ready'")
    ->emulateScreenMediaType()
    ->extraHttpHeaders(['X-Custom' => 'value'])
    ->cookies([new ChromiumCookie('session', 'abc123', '.my.url')])
    ->assets(
        Stream::string('logo.png', $pngBytes),
        Stream::string('font.woff2', $woffBytes),
    )
    ->html(Stream::string('index.html', '<html>…</html>'));
```

--------------------------------

### Custom Index Implementation

Source: https://github.com/gotenberg/gotenberg-php/blob/main/_autodocs/api-reference/index.md

Example of a custom Index implementation passed to a module to impose any ordering convention.

```APIDOC
## Custom Index Implementation

### Description
Because `LibreOffice::index()` and `PdfEngines::index()` accept any `Index` implementation, you can impose any ordering convention. This example shows a custom `FixedOrderIndex` that generates sequential prefixes.

### Example
```php
use Gotenberg\Gotenberg;
use Gotenberg\Index;
use Gotenberg\Stream;

final class FixedOrderIndex implements Index
{
    public function create(): string
    {
        static $i = 0;
        return sprintf('%03d', $i++); // '000', '001', …
    }
}

$request = Gotenberg::pdfEngines('http://localhost:3000')
    ->index(new FixedOrderIndex())
    ->merge(Stream::path('vol-a.pdf'), Stream::path('vol-b.pdf'));
```
```

--------------------------------

### Stream constructor usage example

Source: https://github.com/gotenberg/gotenberg-php/blob/main/_autodocs/api-reference/stream.md

Wraps an existing PSR-7 stream in a new `Stream` instance with a given filename.

```php
use Gotenberg\Stream;

$stream = new Stream('document.docx', $anyPsr7Stream);
```

--------------------------------

### Install Guzzle 7 adapter for PSR-18

Source: https://github.com/gotenberg/gotenberg-php/blob/main/README.md

Installs the php-http/guzzle7-adapter package, which is a recommended PSR-18 HTTP client adapter for this library.

```bash
composer require php-http/guzzle7-adapter
```

--------------------------------

### Example — merge + split combination

Source: https://github.com/gotenberg/gotenberg-php/blob/main/_autodocs/api-reference/modules/libreoffice-pdf-options.md

Demonstrates merging multiple documents into one. Note that split and merge cannot be combined server-side on the same builder.

```php
use Gotenberg\Gotenberg;
use Gotenberg\SplitMode;

$request = Gotenberg::libreOffice('http://localhost:3000')
    ->merge()
    ->convert(
        Stream::path('part1.docx'),
        Stream::path('part2.docx')
    );
// Merge only; split + merge on the same builder is not combined server-side.
```

--------------------------------

### Example: reduce file size with LibreOffice conversion

Source: https://github.com/gotenberg/gotenberg-php/blob/main/_autodocs/api-reference/modules/libreoffice.md

Shows how to configure a LibreOffice request with landscape orientation, page ranges, bookmarks export, and image optimization. Uses the Gotenberg client to convert a presentation file.

```php
use Gotenberg\Gotenberg;

$request = Gotenberg::libreOffice('http://localhost:3000')
    ->landscape()
    ->nativePageRanges('1-4')
    ->exportBookmarks()
    ->optimizeImages(70)
    ->convert(Stream::path('presentation.pptx'));
```

--------------------------------

### Example - watermark download and error handling

Source: https://github.com/gotenberg/gotenberg-php/blob/main/_autodocs/api-reference/download-from.md

Combines downloadFrom() with watermarking() to fetch PDFs and provide a watermark source. Also shows the serialized JSON for a DownloadFrom entry and catches NativeFunctionErrored if json_encode() fails.

```php
use Gotenberg\DownloadFrom;
use Gotenberg\Exceptions\NativeFunctionErrored;
use Gotenberg\Gotenberg;
use Gotenberg\Stream;

$request = Gotenberg::pdfEngines('http://localhost:3000');
$request->watermarking('pdf', '', '', [], Stream::path('watermark.pdf'))
    ->downloadFrom([new DownloadFrom('https://url.to/doc.pdf')]);

// The serialized JSON for the entry above is:
// [
//   "url"      => "https://url.to/doc.pdf",
//   "embedded" => false,
// ]

try {
    $request->watermarks();
} catch (NativeFunctionErrored $e) {
    // json_encode() of the downloadFrom array failed.
}
```

--------------------------------

### Custom Index implementation (ChapterIndex)

Source: https://github.com/gotenberg/gotenberg-php/blob/main/_autodocs/api-reference/index.md

Example of a custom Index implementation that returns zero-padded sequential numbers.

```php
use Gotenberg\Index;

final class ChapterIndex implements Index
{
    public function create(): string
    {
        static $i = 0;
        return sprintf('%03d', $i++);
    }
}
```

--------------------------------

### watermarking() usage example

Source: https://github.com/gotenberg/gotenberg-php/blob/main/_autodocs/api-reference/traits/multipart-form-data-module.md

Example of using watermarking() with a text watermark and two PDF streams. Applies a red text watermark at 50% opacity to all pages.

```php
$request = Gotenberg::pdfEngines($url)
    ->watermarking('My Text', '50%', '', ['color' => 'red'])
    ->watermarks(Stream::path('a.pdf'), Stream::path('b.pdf'));
```

--------------------------------

### Minimal metadata and error handling example

Source: https://github.com/gotenberg/gotenberg-php/blob/main/_autodocs/api-reference/embed-metadata.md

Uses LibreOffice to convert a document while embedding a zip file with minimal metadata (only filename and MIME type). Catches NativeFunctionErrored when json_encode() of the embedsMetadata map fails.

```php
use Gotenberg\EmbedMetadata;
use Gotenberg\Exceptions\NativeFunctionErrored;
use Gotenberg\Gotenberg;
use Gotenberg\Stream;

try {
    $request = Gotenberg::libreOffice('http://localhost:3000')
        ->embeds(Stream::path('attachment.zip'))
        ->embedsMetadata(new EmbedMetadata('attachment.zip', 'application/zip'))
        ->convert(Stream::path('invoice.docx'));
} catch (NativeFunctionErrored $e) {
    // json_encode() of the embedsMetadata map failed.
}
```

--------------------------------

### SplitMode::intervals() usage example

Source: https://github.com/gotenberg/gotenberg-php/blob/main/_autodocs/api-reference/split-mode.md

Shows how to create a SplitMode for intervals of 5 pages. The resulting object has mode='intervals', span='5', and unify=false.

```php
use Gotenberg\SplitMode;

$mode = SplitMode::intervals(5);
// mode='intervals', span='5', unify=false
```

--------------------------------

### Factur-X embeds metadata example

Source: https://github.com/gotenberg/gotenberg-php/blob/main/_autodocs/api-reference/embed-metadata.md

Builds a Chromium PDF request with Factur-X conformance EN_16931, embeds an XML stream, and attaches metadata with relationship Alternative. Requires a running Gotenberg instance at localhost:3000.

```php
use Gotenberg\EmbedMetadata;
use Gotenberg\FacturX;
use Gotenberg\Gotenberg;
use Gotenberg\Stream;

$xml = Stream::string('factur-x.xml', '<Factur-X>…</Factur-X>');

$request = Gotenberg::chromium('http://localhost:3000')
    ->pdf()
    ->pdfa('PDF/A-3b')
    ->facturX(new FacturX($xml, FacturX::CONFORMANCE_EN_16931))
    ->embeds($xml)
    ->embedsMetadata(
        new EmbedMetadata('factur-x.xml', 'application/xml', EmbedMetadata::RELATIONSHIP_ALTERNATIVE)
    )
    ->url('https://my.url');
```

--------------------------------

### Example of using correlationId() with Gotenberg builder

Source: https://github.com/gotenberg/gotenberg-php/blob/main/_autodocs/api-reference/traits/api-module.md

Shows a fluent usage of the Gotenberg builder to create a PDF request and set a correlation ID. The code sends the header 'Gotenberg-Trace: debug'.

```php
use Gotenberg\Gotenberg;

$request = Gotenberg::chromium('http://localhost:3000')
    ->pdf()
    ->correlationId('debug')
    ->url('https://my.url');
// Sends header: Gotenberg-Trace: debug
```

--------------------------------

### Send a request and get a response using PSR-7 client

Source: https://github.com/gotenberg/gotenberg-php/blob/main/README.md

Creates a PDF request for a URL using Gotenberg::chromium()->pdf()->url() and sends it with any PSR-7 compatible HTTP client. The response is a PSR-7 ResponseInterface.

```php
use Gotenberg\Gotenberg;

$request = Gotenberg::chromium($apiUrl)
    ->pdf()
    ->url('https://my.url');

$response = $client->sendRequest($request);
```

--------------------------------

### Constructor

Source: https://github.com/gotenberg/gotenberg-php/blob/main/_autodocs/api-reference/download-from.md

Creates a new DownloadFrom instance with the given URL, optional extra HTTP headers, embedded flag, and destination form field.

```APIDOC
## Constructor

### Description
Creates a new DownloadFrom instance describing a remote file to be downloaded by Gotenberg.

### Signature
```php
public function __construct(
    public readonly string $url,
    public readonly array|null $extraHttpHeaders = null,
    public readonly bool $embedded = false,
    public readonly string $field = '',
)
```

### Parameters
- `$url` (string) - Required - URL of the file to download
- `$extraHttpHeaders` (array<string,string>|null) - Optional - Extra HTTP headers sent with the download request
- `$embedded` (bool) - Optional - Whether the downloaded file is embedded
- `$field` (string) - Optional - Destination form field; may use FIELD_EMBEDDED, FIELD_WATERMARK, or FIELD_STAMP constants (or any other value)

### Example
```php
use Gotenberg\DownloadFrom;

$download = new DownloadFrom('https://url.to/document.docx', ['MyHeader' => 'MyValue']);
```
```

--------------------------------

### Stream::path() usage example

Source: https://github.com/gotenberg/gotenberg-php/blob/main/_autodocs/api-reference/stream.md

Creates a Stream from a local file, optionally specifying a different multipart filename. The example shows that `getFilename()` returns the forced filename.

```php
use Gotenberg\Stream;

$stream = Stream::path('/var/data/report.docx');
// Or force a different multipart filename:
$stream = Stream::path('/var/data/report.docx', 'export.docx');

echo $stream->getFilename(); // 'export.docx'
```

--------------------------------

### getStream() usage example

Source: https://github.com/gotenberg/gotenberg-php/blob/main/_autodocs/api-reference/stream.md

Reads the file content from the underlying stream by casting it to a string.

```php
$contents = (string) $stream->getStream(); // re-read the file content
```

--------------------------------

### Using ChromiumEmulatedMediaFeatures with emulatedMediaFeatures()

Source: https://github.com/gotenberg/gotenberg-php/blob/main/_autodocs/types.md

Shows how to create a PDF request with emulated media features for prefers-color-scheme and prefers-reduced-motion.

```php
use Gotenberg\Modules\ChromiumEmulatedMediaFeatures;
use Gotenberg\Gotenberg;

$request = Gotenberg::chromium('http://localhost:3000')
    ->pdf()
    ->emulatedMediaFeatures([
        new ChromiumEmulatedMediaFeatures('prefers-color-scheme', 'dark'),
        new ChromiumEmulatedMediaFeatures('prefers-reduced-motion', 'reduce'),
    ])
    ->url('https://my.url');
```

--------------------------------

### Class Gotenberg\FacturX

Source: https://github.com/gotenberg/gotenberg-php/blob/main/_autodocs/api-reference/facturx.md

Documentation for the FacturX value object class, including its constructor, constants, and usage examples.

```APIDOC
## Class `Gotenberg\FacturX`

### Description
A value object describing a Factur-X / ZUGFeRD electronic invoice XML to embed in a PDF. It is consumed by the `facturX()` method of `ChromiumPdf`, `LibreOffice` and `PdfEngines`, and by `PdfEngines::injectFacturX()`.

### Constructor

```php
public function __construct(
    public readonly Stream $xml,
    public readonly string $conformanceLevel,
    public readonly string $documentType = self::DOCUMENT_TYPE_INVOICE,
    public readonly string $version = '1.0',
)
```

### Parameters
- **$xml** (`Gotenberg\Stream`) - Required - The invoice XML, uploaded as a form file named `facturxXml`.
- **$conformanceLevel** (string) - Required - One of the `CONFORMANCE_*` constants.
- **$documentType** (string) - Optional - Default: `self::DOCUMENT_TYPE_INVOICE` (`'INVOICE'`) - One of the `DOCUMENT_TYPE_*` constants.
- **$version** (string) - Optional - Default: `'1.0'` - Factur-X / ZUGFeRD version.

### Constants

```php
public const CONFORMANCE_MINIMUM   = 'MINIMUM';
public const CONFORMANCE_BASIC_WL  = 'BASIC WL';
public const CONFORMANCE_BASIC     = 'BASIC';
public const CONFORMANCE_EN_16931  = 'EN 16931';
public const CONFORMANCE_EXTENDED  = 'EXTENDED';
public const CONFORMANCE_XRECHNUNG = 'XRECHNUNG';

public const DOCUMENT_TYPE_INVOICE        = 'INVOICE';
public const DOCUMENT_TYPE_ORDER          = 'ORDER';
public const DOCUMENT_TYPE_ORDER_RESPONSE = 'ORDER_RESPONSE';
public const DOCUMENT_TYPE_ORDER_CHANGE   = 'ORDER_CHANGE';
```

- `CONFORMANCE_*` — allowed values for the `$conformanceLevel` argument (ZUGFeRD conformance levels, including `XRECHNUNG`).
- `DOCUMENT_TYPE_*` — allowed values for the `$documentType` argument.

### Usage Notes
- The embedding requires a PDF/A-3 variant (set via the `pdfa()` method) for the Chromium and LibreOffice routes.
- Factur-X embedding is invalid when the XML conformance level does not match the PDF/A-3 conformance level.

### Example — basic usage

```php
use Gotenberg\FacturX;
use Gotenberg\Gotenberg;
use Gotenberg\Stream;

$request = Gotenberg::chromium('http://localhost:3000')
    ->pdf()
    ->pdfa('PDF/A-3b')
    ->facturX(new FacturX(
        Stream::string('factur-x.xml', '<Factur-X>…</Factur-X>'),
        FacturX::CONFORMANCE_EN_16931,
    ))
    ->html(Stream::string('index.html', '<html><body>Invoice</body></html>'));
```

### Example — XRechnung order with error handling

```php
use Gotenberg\Exceptions\GotenbergApiErrored;
use Gotenberg\FacturX;
use Gotenberg\Gotenberg;
use Gotenberg\Stream;

$facturx = new FacturX(
    Stream::path('/var/xml/order.xml'),
    FacturX::CONFORMANCE_XRECHNUNG,
    FacturX::DOCUMENT_TYPE_ORDER,
    '2.3',
);

try {
    $filename = Gotenberg::save(
        Gotenberg::pdfEngines('http://localhost:3000')
            ->injectFacturX($facturx, Stream::path('order.pdf')),
        '/tmp/pdfs'
    );
} catch (GotenbergApiErrored $e) {
    // Gotenberg rejects malformed XML / wrong conformance level.
}
```
```

--------------------------------

### Error handling example

Source: https://github.com/gotenberg/gotenberg-php/blob/main/_autodocs/api-reference/modules/chromium.md

Shows how to catch Gotenberg\Exceptions\NativeFunctionErrored when json_encode() fails for an array-valued option. Uses failOnHttpStatusCodes and url.

```php
use Gotenberg\Exceptions\NativeFunctionErrored;
use Gotenberg\Gotenberg;

try {
    $request = Gotenberg::chromium('http://localhost:3000')
        ->screenshot()
        ->failOnHttpStatusCodes([404, 500])
        ->url('https://my.url');
} catch (NativeFunctionErrored $e) {
    // Only reached if json_encode() failed for an array-valued option.
}
```

--------------------------------

### Configure LibreOffice PDF viewer options

Source: https://github.com/gotenberg/gotenberg-php/blob/main/_autodocs/api-reference/modules/libreoffice-pdf-options.md

Chains viewer configuration methods on a LibreOffice request: initialView, initialPage, magnification, displayPDFDocumentTitle, hideViewerToolbar, and convert. Use this to set how the PDF opens in the viewer.

```php
use Gotenberg\Gotenberg;

$request = Gotenberg::libreOffice('http://localhost:3000')
    ->initialView('outline')
    ->initialPage(2)
    ->magnification('fitWidth')
    ->displayPDFDocumentTitle()
    ->hideViewerToolbar()
    ->convert(Stream::path('manual.odt'));
```

--------------------------------

### Access Gotenberg modules

Source: https://github.com/gotenberg/gotenberg-php/blob/main/README.md

Shows how to access the three main modules: chromium, libreOffice, and pdfEngines, each returning a module instance for building requests.

```php
use Gotenberg\Gotenberg;

Gotenberg::chromium($apiUrl);
Gotenberg::libreOffice($apiUrl);
Gotenberg::pdfEngines($apiUrl);
```

--------------------------------

### Method: pdfua()

Source: https://github.com/gotenberg/gotenberg-php/blob/main/_autodocs/api-reference/modules/libreoffice-pdf-options.md

Enables PDF for Universal Access.

```php
public function pdfua(): self
```

--------------------------------

### Using outputFilename() in a request

Source: https://github.com/gotenberg/gotenberg-php/blob/main/_autodocs/api-reference/traits/multipart-form-data-module.md

Example usage of the outputFilename() method in a fluent chain to generate a PDF with a custom output filename.

```php
$request = Gotenberg::chromium($url)->pdf()->outputFilename('my_file')->url('https://my.url');
```

--------------------------------

### Stream::string() error handling example

Source: https://github.com/gotenberg/gotenberg-php/blob/main/_autodocs/api-reference/stream.md

Catches `Gotenberg\Exceptions\NativeFunctionErrored` when `Stream::string()` fails due to underlying `fopen()` or `fwrite()` errors.

```php
use Gotenberg\Exceptions\NativeFunctionErrored;
use Gotenberg\Stream;

try {
    $stream = Stream::string('index.html', '<html></html>');
} catch (NativeFunctionErrored $e) {
    // Fired only if the underlying fopen()/fwrite() failed.
    error_log($e->getMessage());
}
```

--------------------------------

### Error handling example

Source: https://github.com/gotenberg/gotenberg-php/blob/main/_autodocs/api-reference/gotenberg.md

Catches GotenbergApiErrored to access HTTP status, error body, and correlation ID (e.g., 'debug') when the response is not 2xx.

```php
use Gotenberg\Exceptions\GotenbergApiErrored;
use Gotenberg\Gotenberg;

try {
    $response = Gotenberg::send(
        Gotenberg::chromium('http://localhost:3000')
            ->screenshot()
            ->url('https://my.url')
    );
} catch (GotenbergApiErrored $e) {
    $httpStatus    = $e->getCode();
    $errorBody     = $e->getMessage();
    $correlationId = $e->getCorrelationId(); // e.g. 'debug'
}
```

--------------------------------

### Method signatures: pdfa(), pdfua(), metadata(), flattening(), optimizeImages(), encrypting()

Source: https://github.com/gotenberg/gotenberg-php/blob/main/_autodocs/api-reference/modules/pdf-engines.md

Public method signatures for setting PDF/A format, enabling PDF/UA, writing metadata, flattening, optimizing images, and encrypting the resulting PDF. Each returns self.

```php
public function pdfa(string $format): self
public function pdfua(): self
public function metadata(array $metadata): self
public function flattening(): self
public function optimizeImages(int $quality = 80): self
public function encrypting(string $userPassword, string $ownerPassword = ''): self
```

--------------------------------

### Merge with download-from and error handling

Source: https://github.com/gotenberg/gotenberg-php/blob/main/_autodocs/api-reference/modules/libreoffice.md

Conversion with `downloadFrom()` to fetch a remote document, `merge()` to produce a single PDF, and error handling via `GotenbergApiErrored`. The response is saved to `/tmp/pdfs`.

```php
use Gotenberg\DownloadFrom;
use Gotenberg\Exceptions\GotenbergApiErrored;
use Gotenberg\Gotenberg;

try {
    $request = Gotenberg::libreOffice('http://localhost:3000')
        ->downloadFrom([new DownloadFrom('https://url.to/document.docx', ['MyHeader' => 'MyValue'])])
        ->merge()
        ->convert();

    $filename = Gotenberg::save($request, '/tmp/pdfs');
} catch (GotenbergApiErrored $e) {
    $message = $e->getMessage();
}
```

--------------------------------

### assets() method signature

Source: https://github.com/gotenberg/gotenberg-php/blob/main/_autodocs/api-reference/modules/chromium.md

Adds each asset as a multipart file (default part name 'files'). Accepts variadic Gotenberg\Stream objects.

```php
public function assets(Stream ...$assets): self
```

--------------------------------

### Create streams for form files

Source: https://github.com/gotenberg/gotenberg-php/blob/main/README.md

Shows various ways to create streams for form files: using Stream::path, Stream::string for direct content, creating a Stream from scratch, and using DownloadFrom to let Gotenberg download files.

```php
use Gotenberg\DownloadFrom;
use Gotenberg\Gotenberg;
use Gotenberg\Stream;

Gotenberg::libreOffice($apiUrl)
    ->convert(Stream::path($pathToDocument));

// Alternatively, you may also set the content directly.
Gotenberg::chromium($apiUrl)
    ->pdf()
    ->assets(Stream::string('style.css', 'body{font-family: Arial, Helvetica, sans-serif;}'))
    ->html(Stream::string('index.html', '<html><head><link rel="stylesheet" type="text/css" href="style.css"></head><body><p>Hello, world!</p></body></html>'));

// Or create your stream from scratch.
Gotenberg::libreOffice($apiUrl)
    ->convert(new Stream('document.docx', $stream));

// Or even tell Gotenberg to download the files for you.
Gotenberg::libreOffice($apiUrl)
    ->downloadFrom([
        new DownloadFrom('https://url.to.document.docx', ['MyHeader' => 'MyValue'])
    ])
    ->convert();
```

--------------------------------

### Project directory structure

Source: https://github.com/gotenberg/gotenberg-php/blob/main/CONTRIBUTING.md

Overview of the source and test directories for the Gotenberg PHP client.

```text
src/
  Gotenberg.php                  Static factory (entry point)
  ApiModule.php                  Base trait: URL, endpoint, headers, request building
  MultipartFormDataModule.php    Trait: multipart form data, webhooks, downloads
  Modules/
    Chromium.php                 Chromium entry point (pdf/screenshot)
    ChromiumPdf.php              Chromium PDF conversion builder
    ChromiumScreenshot.php       Chromium screenshot builder
    ChromiumMultipartFormDataModule.php  Shared Chromium trait
    ChromiumCookie.php           Cookie value object
    LibreOffice.php              LibreOffice conversion builder
    PdfEngines.php               PDF engines builder (merge, split, convert)
  Exceptions/                    Custom exceptions
  Stream.php                     File stream wrapper
  SplitMode.php                  Split mode enum
  DownloadFrom.php               Download-from value object
tests/
  TestCase.php                   Base class with custom assertions
  Modules/                       Module-specific tests
```

--------------------------------

### Catch GotenbergApiErrored and extract details

Source: https://github.com/gotenberg/gotenberg-php/blob/main/_autodocs/errors.md

Complete catch example showing how to extract the HTTP status, error body, correlation ID (default and custom header), and the full response from a GotenbergApiErrored exception.

```php
use Gotenberg\Exceptions\GotenbergApiErrored;
use Gotenberg\Gotenberg;

try {
    $response = Gotenberg::send(
        Gotenberg::chromium($apiUrl)->screenshot()->url('https://my.url')
    );
} catch (GotenbergApiErrored $e) {
    $httpStatus    = $e->getCode();                   // e.g. 400
    $errorBody     = $e->getMessage();                // response body
    $correlationId = $e->getCorrelationId();          // default header
    $correlationId = $e->getCorrelationId('Request-Id'); // custom header
    $response      = $e->getResponse();               // full ResponseInterface
}
```

--------------------------------

### libreOffice() method signature

Source: https://github.com/gotenberg/gotenberg-php/blob/main/_autodocs/api-reference/gotenberg.md

Static factory method that returns a Gotenberg\Modules\LibreOffice builder for LibreOffice conversions. Requires the base URL of the Gotenberg API.

```php
public static function libreOffice(string $baseUrl): LibreOffice
```

--------------------------------

### Gotenberg\Modules\PdfEngines

Source: https://github.com/gotenberg/gotenberg-php/blob/main/_autodocs/api-reference/modules/pdf-engines.md

Documentation for the Gotenberg\Modules\PdfEngines fluent builder class, covering all option methods for PDF engines.

```APIDOC
## Class `Gotenberg\Modules\PdfEngines`

### Description
Composes the `Gotenberg\MultipartFormDataModule` trait (inherits [api-module](../traits/api-module.md) constructor/correlation-id and [multipart-form-data-module](../traits/multipart-form-data-module.md) fields). A fluent builder for Gotenberg's PDF engines: merge, split, flatten, optimize, convert to PDF/A, metadata read/write, encrypt, watermark, stamp, rotate, bookmarks read/write, embed and Factur-X injection.

### Constructor
Inherited from the `Gotenberg\MultipartFormDataModule` trait. See [api-module](../traits/api-module.md) and [multipart-form-data-module](../traits/multipart-form-data-module.md).

### Methods

#### `index(Index $index): self`

Sets a custom index generator for ordering merged files. Default is `Gotenberg\HrtimeIndex`.

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `$index` | `Gotenberg\Index` | yes | — | Custom index generator for ordering merged files (default: `Gotenberg\HrtimeIndex`) |

#### `pdfa(string $format): self`

Sets the PDF/A format of the resulting PDF.

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `$format` | string | yes | — | PDF/A format (e.g., `PDF/A-1a`, `PDF/A-2b`, etc.) |

#### `pdfua(): self`

Enables PDF for Universal Access.

#### `metadata(array $metadata): self`

Sets metadata to write to the resulting PDF. Throws `NativeFunctionErrored` if `json_encode()` fails.

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `$metadata` | `array<string,string\|bool\|float\|int\|array<string>>` | yes | — | Metadata to write (JSON-encoded) |

#### `flattening(): self`

Flattens the resulting PDF(s). Prefer `flatten()` if you only want to flatten one or more PDFs.

#### `optimizeImages(int $quality = 80): self`

Re-encodes images of the resulting PDF.

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `$quality` | int | no | `80` | Image quality (1-100) |

#### `encrypting(string $userPassword, string $ownerPassword = ''): self`

Encrypts the resulting PDF. Prefer `encrypt()` if you only want to encrypt one or more PDFs.

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `$userPassword` | string | yes | — | User password |
| `$ownerPassword` | string | no | `''` | Owner password |

#### Permission methods

Restricting any permission requires a `userPassword` or `ownerPassword` (set via `encrypting()`/`encrypt()`).

| Method | Signature | Description |
|--------|-----------|-------------|
| `allowPrinting()` | `public function allowPrinting(bool $allow = true): self` | Allows printing |
| `allowCopying()` | `public function allowCopying(bool $allow = true): self` | Allows copying |
| `allowModifying()` | `public function allowModifying(bool $allow = true): self` | Allows modifying |
| `allowAnnotating()` | `public function allowAnnotating(bool $allow = true): self` | Allows annotating |
| `allowFillingForms()` | `public function allowFillingForms(bool $allow = true): self` | Allows filling forms |
| `allowAssembling()` | `public function allowAssembling(bool $allow = true): self` | Allows assembling |

#### `facturX(FacturX $facturx): self`

Configures embedding of a Factur-X / ZUGFeRD invoice XML; requires PDF/A-3 (see [facturx.md](../facturx.md)).

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `$facturx` | `Gotenberg\FacturX` | yes | — | Factur-X configuration |

#### `embeds(Stream ...$embeds): self`

Files to embed into the resulting PDF.

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `$embeds` | `Gotenberg\Stream` variadic | yes | — | Files to embed |

#### `embedsMetadata(EmbedMetadata ...$metadata): self`

Metadata on embedded files (Factur-X / ZUGFeRD compliance). Throws `NativeFunctionErrored` if `json_encode()` fails.

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `$metadata` | `Gotenberg\EmbedMetadata` variadic | yes | — | Metadata for embedded files |

#### Bookmark options for merge

| Method | Signature | Description |
|--------|-----------|-------------|
| `bookmarks()` | `public function bookmarks(string $bookmarks): self` | Sets the bookmarks for the merge route |
| `autoIndexBookmarks()` | `public function autoIndexBookmarks(): self` | Enables auto-indexing of bookmarks for the merge route |
| `titleBookmarks()` | `public function titleBookmarks(): self` | Adds a bookmark per merged document, labeled by its title metadata, pointing to its first page |

### Return Values
All option methods return `self`; every terminal method returns a PSR-7 `RequestInterface`.
```

--------------------------------

### Constructor signature for DownloadFrom

Source: https://github.com/gotenberg/gotenberg-php/blob/main/_autodocs/api-reference/download-from.md

The constructor accepts a required URL, optional extra HTTP headers, an embedded flag, and a destination form field. All properties are public readonly.

```php
/** @param array<string,string> $extraHttpHeaders */
public function __construct(
    public readonly string $url,
    public readonly array|null $extraHttpHeaders = null,
    public readonly bool $embedded = false,
    public readonly string $field = '',
)
```

--------------------------------

### webp()

Source: https://github.com/gotenberg/gotenberg-php/blob/main/_autodocs/api-reference/modules/chromium-screenshot.md

Sets WEBP as the image compression format for the screenshot.

```APIDOC
## webp()

### Description
Sets WEBP as the image compression format for the screenshot.

### Method
webp

### Parameters
None

### Returns
- **self** - Returns the current instance for method chaining.

### Form Value
`format` = `'webp'`
```

--------------------------------

### SplitMode::pages() usage with ChromiumPdf

Source: https://github.com/gotenberg/gotenberg-php/blob/main/_autodocs/api-reference/split-mode.md

Example of using SplitMode::pages() with the ChromiumPdf module's split() method. Splits the PDF at page ranges '1-3, 5-7' and unifies the resulting PDFs into a single one.

```php
use Gotenberg\Gotenberg;
use Gotenberg\SplitMode;

$request = Gotenberg::chromium('http://localhost:3000')
    ->pdf()
    ->split(SplitMode::pages('1-3, 5-7', true))
    ->url('https://my.url');
```

--------------------------------

### Chromium::__construct

Source: https://github.com/gotenberg/gotenberg-php/blob/main/_autodocs/api-reference/modules/chromium.md

Creates a new Chromium instance with the base URL of the Gotenberg API.

```APIDOC
## `Chromium::__construct`

### Description
Creates a new Chromium instance with the base URL of the Gotenberg API.

### Method
`__construct`

### Signature
```php
public function __construct(public readonly string $baseUrl)
```

### Parameters
- `$baseUrl` (string) - Required - Base URL of the Gotenberg API

### Returns
No return value (constructor).

### Example
```php
$chromium = new Chromium('http://localhost:3000');
```
```

--------------------------------

### Method: html()

Source: https://github.com/gotenberg/gotenberg-php/blob/main/_autodocs/api-reference/modules/chromium-screenshot.md

Sets the HTML document for a Chromium screenshot. Endpoint: POST /forms/chromium/screenshot/html. The $index parameter may be null and forces the multipart filename to 'index.html'.

```php
public function html(Stream|null $index): RequestInterface
```

--------------------------------

### SplitMode::intervals() usage with PdfEngines and error handling

Source: https://github.com/gotenberg/gotenberg-php/blob/main/_autodocs/api-reference/split-mode.md

Example of using SplitMode::intervals() with the PdfEngines module's split() method, wrapped in a try-catch block to handle GotenbergApiErrored exceptions. Invalid ranges produce a Gotenberg error response.

```php
use Gotenberg\Exceptions\GotenbergApiErrored;
use Gotenberg\Gotenberg;
use Gotenberg\SplitMode;
use Gotenberg\Stream;

try {
    $filename = Gotenberg::save(
        Gotenberg::pdfEngines('http://localhost:3000')
            ->split(SplitMode::intervals(2), Stream::path('big.pdf')),
        '/tmp/pdfs'
    );
} catch (GotenbergApiErrored $e) {
    // Invalid ranges produce a Gotenberg error response.
}
```

--------------------------------

### Catch NativeFunctionErrored from Gotenberg::chromium()->pdf()->metadata()

Source: https://github.com/gotenberg/gotenberg-php/blob/main/_autodocs/errors.md

Example of catching NativeFunctionErrored when calling Gotenberg::chromium()->pdf()->metadata() with a title containing an invalid UTF-8 sequence. The exception's getMessage() returns the PHP error message and getCode() returns the PHP error type.

```php
use Gotenberg\Exceptions\NativeFunctionErrored;
use Gotenberg\Gotenberg;

try {
    $request = Gotenberg::chromium($apiUrl)
        ->pdf()
        ->metadata(['title' => "Caf\u{e9}"]) // invalid UTF-8 would fail json_encode
        ->url('https://my.url');
} catch (NativeFunctionErrored $e) {
    $phpMessage = $e->getMessage();
    $phpLevel   = $e->getCode(); // the PHP error type
}
```

--------------------------------

### XRechnung order injection with error handling

Source: https://github.com/gotenberg/gotenberg-php/blob/main/_autodocs/api-reference/facturx.md

XRechnung order example with error handling: constructs a FacturX with `CONFORMANCE_XRECHNUNG`, `DOCUMENT_TYPE_ORDER`, and version `'2.3'`, then injects it into an existing PDF via `PdfEngines::injectFacturX()`. Catches `GotenbergApiErrored` when Gotenberg rejects malformed XML or a wrong conformance level.

```php
use Gotenberg\Exceptions\GotenbergApiErrored;
use Gotenberg\FacturX;
use Gotenberg\Gotenberg;
use Gotenberg\Stream;

$facturx = new FacturX(
    Stream::path('/var/xml/order.xml'),
    FacturX::CONFORMANCE_XRECHNUNG,
    FacturX::DOCUMENT_TYPE_ORDER,
    '2.3',
);

try {
    $filename = Gotenberg::save(
        Gotenberg::pdfEngines('http://localhost:3000')
            ->injectFacturX($facturx, Stream::path('order.pdf')),
        '/tmp/pdfs'
    );
} catch (GotenbergApiErrored $e) {
    // Gotenberg rejects malformed XML / wrong conformance level.
}
```

--------------------------------

### Basic call — URL to PDF with options

Source: https://github.com/gotenberg/gotenberg-php/blob/main/_autodocs/api-reference/modules/chromium-pdf.md

Creates a Chromium PDF request for a URL with options such as single-page, paper size, margins, print background, document outline, and splitting. Saves the result to a file.

```php
use Gotenberg\Gotenberg;
use Gotenberg\SplitMode;

$request = Gotenberg::chromium('http://localhost:3000')
    ->pdf()
    ->singlePage()
    ->paperSize('8.27in', '11.7in')
    ->margins('0.5in', '0.5in', '0.5in', '0.5in')
    ->printBackground()
    ->generateDocumentOutline()
    ->split(SplitMode::intervals(5))
    ->outputFilename('report')
    ->url('https://my.url');

$filename = Gotenberg::save($request, '/tmp/exports');
```

--------------------------------

### width()

Source: https://github.com/gotenberg/gotenberg-php/blob/main/_autodocs/api-reference/modules/chromium-screenshot.md

Sets the device screen width in pixels for the screenshot viewport.

```APIDOC
## width()

### Description
Sets the device screen width in pixels for the screenshot viewport.

### Method
width

### Parameters
- **$width** (int) - Required - Device screen width in pixels

### Returns
- **self** - Returns the current instance for method chaining.

### Form Value
`width`
```

--------------------------------

### screenshot() method returns ChromiumScreenshot builder

Source: https://github.com/gotenberg/gotenberg-php/blob/main/_autodocs/api-reference/modules/chromium.md

Returns a new ChromiumScreenshot builder instance.

```php
public function screenshot(): ChromiumScreenshot
```

--------------------------------

### png()

Source: https://github.com/gotenberg/gotenberg-php/blob/main/_autodocs/api-reference/modules/chromium-screenshot.md

Sets PNG as the image compression format for the screenshot.

```APIDOC
## png()

### Description
Sets PNG as the image compression format for the screenshot.

### Method
png

### Parameters
None

### Returns
- **self** - Returns the current instance for method chaining.

### Form Value
`format` = `'png'`
```

--------------------------------

### Interface Index definition

Source: https://github.com/gotenberg/gotenberg-php/blob/main/_autodocs/api-reference/index.md

Defines the Index interface with a single create() method that returns a string used as a filename prefix.

```php
interface Index
{
    public function create(): string;
}
```

--------------------------------

### Chromium::screenshot()

Source: https://github.com/gotenberg/gotenberg-php/blob/main/_autodocs/api-reference/modules/chromium.md

Creates a new ChromiumScreenshot builder instance.

```APIDOC
## `Chromium::screenshot()`

### Description
Creates a new ChromiumScreenshot builder instance.

### Method
`screenshot`

### Signature
```php
public function screenshot(): ChromiumScreenshot
```

### Parameters
None.

### Returns
- `Gotenberg\Modules\ChromiumScreenshot` - A new ChromiumScreenshot builder.

### Example
```php
$screenshot = $chromium->screenshot();
```
```

--------------------------------

### Constructor for Chromium class

Source: https://github.com/gotenberg/gotenberg-php/blob/main/_autodocs/api-reference/modules/chromium.md

Creates a Chromium instance with the base URL of the Gotenberg API. The base URL is exposed as a readonly public property.

```php
public function __construct(public readonly string $baseUrl)
```

--------------------------------

### Build and send a Chromium PDF request with Gotenberg PHP

Source: https://github.com/gotenberg/gotenberg-php/blob/main/_autodocs/README.md

Shows the basic workflow of the Gotenberg PHP client: build a Chromium PDF request, send it, or save the output file. Requires PHP ^8.1, PSR-7/PSR-18 HTTP components, and a Gotenberg 8.x server. `send()` throws `GotenbergApiErrored` on non-2xx responses; `save()` returns the filename.

```php
use Gotenberg\Gotenberg;
use Gotenberg\Stream;

// Build a request…
$request = Gotenberg::chromium('http://localhost:3000')
    ->pdf()
    ->singlePage()
    ->url('https://my.url');

// …then send it (throws GotenbergApiErrored on non-2xx)…
$response = Gotenberg::send($request);

// …or save the resulting file (returns the filename).
$filename = Gotenberg::save($request, '/tmp/pdfs');
```

--------------------------------

### HrtimeIndex create() method signature

Source: https://github.com/gotenberg/gotenberg-php/blob/main/_autodocs/api-reference/index.md

Signature of the create() method in the HrtimeIndex class.

```php
public function create(): string
```

--------------------------------

### Index::create()

Source: https://github.com/gotenberg/gotenberg-php/blob/main/_autodocs/api-reference/index.md

Returns an index string used as a filename prefix for controlling file ordering during merges.

```APIDOC
## Index::create()

### Description
Returns an index string used as a filename prefix. This method is part of the `Gotenberg\Index` interface and is used to control the ordering of files when merging. Both `LibreOffice::convert()` (when `merge()` is enabled) and `PdfEngines::merge()` prefix every uploaded file with `$index->create() . '_' . $file->getFilename()` so that alphabetical ordering of the multipart filenames matches merge order.

### Method
create

### Signature
`public function create(): string`

### Returns
- **string** - An index string used as a filename prefix.

### Example
```php
use Gotenberg\Index;

final class ChapterIndex implements Index
{
    public function create(): string
    {
        static $i = 0;
        return sprintf('%03d', $i++);
    }
}
```
```

--------------------------------

### Convert URL to PDF and save to directory

Source: https://github.com/gotenberg/gotenberg-php/blob/main/README.md

Converts a target URL to PDF and saves it to a given directory using Gotenberg::save(). Requires a Gotenberg API URL and a saving directory path.

```php
use Gotenberg\Gotenberg;

// Converts a target URL to PDF and saves it to a given directory.
$filename = Gotenberg::save(
    Gotenberg::chromium($apiUrl)->pdf()->url('https://my.url'), 
    $pathToSavingDirectory
);
```

--------------------------------

### height()

Source: https://github.com/gotenberg/gotenberg-php/blob/main/_autodocs/api-reference/modules/chromium-screenshot.md

Sets the device screen height in pixels for the screenshot viewport.

```APIDOC
## height()

### Description
Sets the device screen height in pixels for the screenshot viewport.

### Method
height

### Parameters
- **$height** (int) - Required - Device screen height in pixels

### Returns
- **self** - Returns the current instance for method chaining.

### Form Value
`height`
```

--------------------------------

### POST /forms/chromium/screenshot/html

Source: https://github.com/gotenberg/gotenberg-php/blob/main/_autodocs/endpoints.md

Creates a screenshot from an HTML file. Accepts the 'index.html' file plus screenshot options and Chromium shared fields.

```APIDOC
## POST /forms/chromium/screenshot/html

### Description
Creates a screenshot from an HTML file. Accepts the 'index.html' file plus screenshot options and Chromium shared fields.

### Method
POST

### Endpoint
/forms/chromium/screenshot/html

### Parameters
#### Request Body
- **index.html** (file) - Required - The HTML file to render.
- **width** (integer) - Optional - Screenshot width in pixels.
- **height** (integer) - Optional - Screenshot height in pixels.
- **clip** (boolean) - Optional - Whether to clip the screenshot.
- **deviceScaleFactor** (number) - Optional - Device scale factor.
- **format** (string) - Optional - Image format: png, jpeg, or webp.
- **quality** (integer) - Optional - Image quality (for jpeg/webp).
- **optimizeForSpeed** (boolean) - Optional - Optimize for speed.
- **selector** (string) - Optional - CSS selector to capture.
- **omitBackground** (boolean) - Optional - Omit background.
- **waitDelay** (string) - Optional - Delay before screenshot.
- **waitForExpression** (string) - Optional - Expression to wait for.
- **waitForSelector** (string) - Optional - Selector to wait for.
- **emulatedMediaType** (string) - Optional - Emulated media type.
- **emulatedMediaFeatures** (JSON) - Optional - Emulated media features.
- **cookies** (JSON) - Optional - Cookies to send.
- **userAgent** (string) - Optional - User agent string.
- **extraHttpHeaders** (JSON) - Optional - Extra HTTP headers.
- **failOnHttpStatusCodes** (JSON) - Optional - Fail on HTTP status codes.
- **failOnResourceHttpStatusCodes** (JSON) - Optional - Fail on resource HTTP status codes.
- **ignoreResourceHttpStatusDomains** (JSON) - Optional - Ignore resource HTTP status domains.
- **failOnResourceLoadingFailed** (boolean) - Optional - Fail on resource loading failure.
- **failOnConsoleExceptions** (boolean) - Optional - Fail on console exceptions.
- **skipNetworkIdleEvent** (boolean) - Optional - Skip network idle event.
- **skipNetworkAlmostIdleEvent** (boolean) - Optional - Skip network almost idle event.
- **assets** (file) - Optional - Arbitrary asset files.

### Response
#### Success Response (200)
Returns the screenshot image (PNG/JPEG/WEBP). Filename in Content-Disposition.

```

--------------------------------

### footer() method signature

Source: https://github.com/gotenberg/gotenberg-php/blob/main/_autodocs/api-reference/modules/chromium-pdf.md

Adds a footer to each page. The multipart filename is forced to footer.html.

```php
public function footer(Stream $footer): self
```
Tokens:
Raw