NextPDF Gotenberg integration

At a glance

This page shows you how to connect the bridge to the rest of your application. Install it, wire it, then pass the converted Portable Document Format (PDF) into a NextPDF post-processing pipeline. The bridge converts an Office document to PDF; the pipeline handles everything after conversion. For the design behind this wiring, see /integrations/gotenberg/boot-and-discovery/.

Install

composer require nextpdf/gotenberg

Installing this package also installs nextpdf/core ^3.0 and the PHP Standards Recommendation (PSR) Hypertext Transfer Protocol (HTTP) contracts. Install a PSR-18 client and PSR-17 factories as separate packages. The bridge depends only on the interfaces, so you can choose the concrete libraries. For full installation steps, including how to run the Gotenberg service over Hypertext Transfer Protocol Secure (HTTPS), see /integrations/gotenberg/install/.

Wiring

Create the bridge with a configuration object and the PSR collaborators. Also inject a response factory; it enables the Domain Name System (DNS)-pinning, Transport Layer Security (TLS)-pinning transport:

use NextPDF\Gotenberg\GotenbergBridge;
use NextPDF\Gotenberg\GotenbergConfig;

$config = new GotenbergConfig(
    apiUrl: 'https://gotenberg.example.com',
    timeout: 60,
    apiKey: $apiKey,
);

$bridge = new GotenbergBridge(
    config: $config,
    httpClient: $httpClient,
    requestFactory: $requestFactory,
    streamFactory: $streamFactory,
    responseFactory: $responseFactory,
);

The bridge requires HTTPS for the configured URL. It rejects plain http:// before it sends any request. Run Gotenberg behind TLS termination, then point the bridge at the HTTPS endpoint.

Container bindings

Register three entries in your host container: the GotenbergConfig built from your configuration source, your PSR-18 client together with your PSR-17 factories, and GotenbergBridge, wired from those dependencies. This package does not ship its own bindings. Framework-native registration belongs to the dedicated framework integration packages. See /integrations/gotenberg/boot-and-discovery/.

Configuration

All service descriptor fields and limits live in GotenbergConfig. They cover the application programming interface (API) URL, the timeout, the size cap, the bearer token, and the TLS pins. The per-request options, landscape and nativePageRanges, live on the payload type instead. /integrations/gotenberg/configuration/ documents every field, with its type, default, and effect.

Joining the converted PDF to a NextPDF pipeline

A typical end-to-end flow:

Convert the Office document with convertFile() or convertString().
Take $result->pdfData, which contains the raw PDF bytes, and load it into a NextPDF document.
Apply post-processing, such as page assembly, watermarking, PDF/A conversion, or digital signatures.

Step 3 belongs to NextPDF, not to the bridge. The nextpdf/premium package provides signing, PDF/A profiles, and watermarking. Keep conversion and post-processing as separate stages so you can diagnose each failure on its own.

use NextPDF\Gotenberg\GotenbergConvertException;

try {
    $result = $bridge->convertFile('/path/to/report.docx');
} catch (GotenbergConvertException $e) {
    // Conversion-layer failure — handle per your retry policy.
    throw $e;
}

// $result->pdfData is now an ordinary PDF byte stream ready for
// NextPDF post-processing.

The Pro edition’s PDF Advanced Electronic Signatures (PAdES) support is the B-B baseline only. It does not provide B-T, B-LT, or B-LTA. Converting a document through this bridge does not imply any timestamp or long-term-validation capability.

Smoke test

After wiring, confirm the integration without converting a real document:

if (! $bridge->isAvailable()) {
    throw new \RuntimeException('Gotenberg is not reachable.');
}

isAvailable() validates the URL without network traffic. It then sends a HEAD request to <apiUrl>/health. After that, convert one known-good small document. This exercises the full multipart path to <apiUrl>/forms/libreoffice/convert and validates the response.

Public API entry points

The public surface this integration uses:

GotenbergConfig — immutable service descriptor and limits; fromArray() builds it from a config array.
GotenbergBridge::convertFile(string $path) — converts a file on disk.
GotenbergBridge::convertString(string $bytes, string $fileName) — converts bytes held in memory.
GotenbergBridge::isAvailable() — non-throwing readiness probe.
GotenbergConvertResult — carries pdfData, sourceFormat, isValid(), and size().
GotenbergConvertException — the conversion-layer exception type.

The complete contract is in /integrations/gotenberg/configuration/ and /integrations/gotenberg/troubleshooting/. It covers transport selection and the exception catalog.