NextPDF Gotenberg overview

At a glance

NextPDF Gotenberg is a small bridge between NextPDF and an external Gotenberg service. Use it when NextPDF cannot render an Office document natively. The bridge sends the document to a Gotenberg instance over Hypertext Transfer Protocol (HTTP), receives Portable Document Format (PDF) output, and hands the PDF to your application. From there, NextPDF handles the rest of the post-processing.

The package is small and explicit. It does not embed a renderer, does not spawn LibreOffice, and does not run a browser. Every conversion uses a single multipart HTTP request to a Gotenberg endpoint. You operate that endpoint and point the bridge to it in configuration.

Use this bridge when you have .docx, .xlsx, .pptx, .odt, .ods, or .odp source files and need PDF output in a NextPDF pipeline. After the PDF exists, NextPDF or nextpdf/premium handles signing, PDF/A conversion, watermarking, and merging.

What the bridge depends on

The bridge has one runtime dependency that is not a PHP package: a running Gotenberg service that the bridge can reach over Hypertext Transfer Protocol Secure (HTTPS).

The bridge does not install, manage, or supervise Gotenberg. You deploy Gotenberg yourself; the upstream project publishes a container image. You are responsible for its availability, capacity, and network exposure.
The bridge talks to Gotenberg’s LibreOffice conversion route. The request URL is built as <apiUrl>/forms/libreoffice/convert, where <apiUrl> is the base URL you configure. This route defines the bridge’s supported-format set.
The health probe sends an HTTP HEAD request to <apiUrl>/health and treats any status below 500 as available.

Because conversion runs in a service you operate, behavior depends on the Gotenberg version you run. The bridge sends a fixed multipart request, and it assumes only two Gotenberg paths: the route path (/forms/libreoffice/convert) and the health path (/health). See /integrations/gotenberg/install/ for the deployment baseline and /integrations/gotenberg/security-and-operations/ for service hardening.

Supported document formats

The bridge converts only the formats enumerated in its OfficeFormat type. It detects each format from the file extension. Matching is case-insensitive, and a leading dot is allowed. The bridge then sends each file to Gotenberg with a fixed Multipurpose Internet Mail Extensions (MIME) type:

Format	Extension	MIME type sent to Gotenberg
Word (OOXML)	`docx`	`application/vnd.openxmlformats-officedocument.wordprocessingml.document`
Excel (OOXML)	`xlsx`	`application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`
PowerPoint (OOXML)	`pptx`	`application/vnd.openxmlformats-officedocument.presentationml.presentation`
OpenDocument Text	`odt`	`application/vnd.oasis.opendocument.text`
OpenDocument Spreadsheet	`ods`	`application/vnd.oasis.opendocument.spreadsheet`
OpenDocument Presentation	`odp`	`application/vnd.oasis.opendocument.presentation`

This list is complete. An extension outside this set raises a ValueError before any network request is made, so the bridge never attempts a conversion it cannot describe. The bridge does not claim to support “any Office file” or “all document formats.” It supports the six formats above because the code recognizes only those six and the test suite exercises only those six.

Legacy binary formats (.doc, .xls, .ppt), rich text (.rtf), plain text, comma-separated values (CSV), and image formats are not part of the bridge’s recognized set. Gotenberg’s own LibreOffice route may accept a broader range of inputs. The bridge deliberately limits itself to the enumerated set so format detection, the MIME type, and the result metadata stay consistent and verifiable.

How a conversion flows

A conversion is a single, linear pass. The bridge validates each step before any byte leaves the process:

The configuration is checked. An empty Application Programming Interface (API) URL fails immediately with a conversion exception.
The API URL is validated. HTTPS is required, and the host is resolved and screened so it cannot point to a private or reserved address. The resolved address set is captured for later pinning.
The input is read (for file conversions, the path is canonicalised first to block traversal) and its extension is mapped to an OfficeFormat.
The bridge checks the byte length against the configured maximum and screens the filename for traversal sequences, slashes, null bytes, and control characters.
The address set is checked again immediately before the request to close the gap between validation and connection.
The bridge builds a multipart/form-data body and POSTs it to the LibreOffice route, with a bearer token if one is configured.
The bridge parses the response. The status must be 200, the Content-Type must contain application/pdf, and the body must begin with the %PDF signature. Only then is a result returned.

Any failure in steps 1–7 raises a typed exception. The bridge does not return a partial or unchecked result. The exact exceptions and their triggers are cataloged in /integrations/gotenberg/troubleshooting/.

What you get back

A successful conversion returns a result object. The object includes the raw PDF bytes, the converted source format, and an optional render-time measurement. It also exposes a validity check (a non-empty body that starts with %PDF) and a byte-size accessor. The bytes are a normal PDF stream, so you can write them to disk, stream them to a client, or feed them into a NextPDF document for more processing.

Where the bridge stops

The bridge converts and validates. It does not:

Sign, encrypt, linearize, or convert the output to PDF/A. NextPDF core or nextpdf/premium handles those post-processing concerns.
Retry failed requests, queue work, or cache results. Those are application-level concerns. /integrations/gotenberg/production-usage/ shows how to add them around the bridge.
Manage the Gotenberg service lifecycle. Deployment and operations are covered in /integrations/gotenberg/security-and-operations/.

Editions and post-processing

The open source software (OSS) core can write the converted PDF as is. If you need to sign the converted document, produce a PDF/A archival profile, or apply a watermark, the nextpdf/premium package adds those capabilities. The bridge itself is edition-neutral: it produces a PDF. What you do with that PDF determines whether you need a commercial edition.

The PDF Advanced Electronic Signatures (PAdES) baseline available in the Pro edition is B-B only. Long-term validation (LTV) profiles (B-T, B-LT, B-LTA) are not part of the Pro edition and are not provided by this bridge. Do not infer timestamp or LTV capability from the presence of this package.