NextPDF Gotenberg quickstart

At a glance

This walkthrough converts one .docx file to Portable Document Format (PDF). When you finish, you have three things: a working bridge instance, a verified service connection, and a PDF on disk. The full program is in the repository at examples/convert-office-to-pdf.php. The snippets below come from that program.

This tutorial starts with the simplest working path. Production topics, including secret sourcing, retries, timeouts, and observability, are covered in /integrations/gotenberg/production-usage/.

Before you start

Before you continue, confirm these three things:

1. You have run composer require nextpdf/gotenberg, and a PHP Standards Recommendation (PSR)-18 client plus PSR-17 factories are installed. See /integrations/gotenberg/install/.
2. A Gotenberg service is reachable over Hypertext Transfer Protocol Secure (HTTPS). The bridge rejects plain http:// before any request leaves the process.
3. You have a sample file in one of these formats: .docx, .xlsx, .pptx, .odt, .ods, or .odp. Other extensions fail with a ValueError.

Step 1 — describe the service

GotenbergConfig is an immutable value object. At minimum, it needs the HTTPS base URL for your Gotenberg service:

use NextPDF\Gotenberg\GotenbergConfig;

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

The cURL-pinned transport applies timeout as the transfer timeout in seconds. When apiKey is non-empty, the bridge sends it as Authorization: Bearer <token>. Leave apiKey empty if your Gotenberg deployment does not require a token.

Step 2 — wire the bridge

Pass the config and the PSR components to the bridge. Also inject a responseFactory to enable the cURL transport with Domain Name System (DNS) and Transport Layer Security (TLS) pinning:

use NextPDF\Gotenberg\GotenbergBridge;

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

The bridge never creates a Hypertext Transfer Protocol (HTTP) client for you. Use the PSR-18 client and PSR-17 factories you installed. The example file shows the Guzzle wiring in a comment.

Step 3 — check availability

Check the service before you convert a file. The probe validates the URL without network traffic, then sends a HEAD request to <apiUrl>/health:

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

For an empty, non-HTTPS, or private-address URL, or for any network error, isAvailable() returns false (never throws). A status below 500 from /health means the service is available.

Step 4 — convert

Call convertFile() with a path on disk. The bridge canonicalizes the path to block traversal. It maps the extension to a supported format, checks the size and filename, and then sends a multipart request to <apiUrl>/forms/libreoffice/convert:

use NextPDF\Gotenberg\GotenbergConvertException;

try {
    $result = $bridge->convertFile('/path/to/report.docx');
} catch (GotenbergConvertException $e) {
    // Bad config, HTTP failure, non-200, wrong Content-Type, or non-PDF body.
    throw $e;
} catch (\RuntimeException $e) {
    // Non-HTTPS URL, private address, oversized input, or unsafe filename.
    throw $e;
} catch (\ValueError $e) {
    // Extension is not one of the six recognised Office formats.
    throw $e;
}

To convert bytes already in memory, use convertString(). Pass the original filename so the bridge can detect the extension:

$pdf = $bridge->convertString($docxBytes, 'report.docx');

Step 5 — use the result

The result includes three things: the PDF bytes, the source format, and a validity check:

if (! $result->isValid()) {
    throw new \RuntimeException('Result is not a valid PDF.');
}

\file_put_contents('/path/to/report.pdf', $result->pdfData);

\printf(
    "Converted %s (%d bytes)\n",
    $result->sourceFormat->value,
    $result->size(),
);

isValid() is true when the body is non-empty and starts with %PDF. size() returns the byte length. From here, the PDF is an ordinary stream you can pass to NextPDF for post-processing.

The complete program

The full, runnable program is at examples/convert-office-to-pdf.php in the package repository. It includes argument parsing, environment-driven configuration, the health probe, exhaustive error handling, and the write step. Run it with:

GOTENBERG_URL=https://gotenberg.example.com \
php examples/convert-office-to-pdf.php report.docx report.pdf

What next

• /integrations/gotenberg/configuration/ — review every option and the transport-selection rules.
• /integrations/gotenberg/production-usage/ — handle secrets, retries, timeouts, logging, and concurrency.
• /integrations/gotenberg/troubleshooting/ — understand every exception this code can throw and what it means.
• /integrations/gotenberg/integration/ — drive a NextPDF rendering pipeline through the service.