Install NextPDF Gotenberg

At a glance

Installing the bridge has two parts: the PHP package and its PHP Standard Recommendation (PSR) HTTP dependencies, which you install with Composer, and the Gotenberg service that the package calls. The bridge converts files by sending the work to that service, so it cannot convert anything until a Gotenberg instance is reachable.

Complete both parts before you write conversion code.

Requirements

Requirement	Constraint	Why
PHP	`>=8.4 <9.0`	Declared by the package in `composer.json`.
NextPDF core	`^3.0`	Declared as a direct dependency in `composer.json`.
PSR-18 HTTP client	`^1.0`	The bridge sends requests through an injected `Psr\Http\Client\ClientInterface`.
PSR-17 HTTP factories	`^1.1`	The bridge builds requests and streams with injected PSR-17 factories.
PSR-3 logger	`^3.0` (optional)	You can inject a logger for request-level debug logging.
Gotenberg service	Reachable over HTTPS	The external service performs conversion; this package does not.

The bridge does not bundle a PSR-18 client or PSR-17 factories. Choose the implementations that fit your application. For example, pair a Guzzle-based client with its PSR-17 factories, or use the Symfony HTTP client with nyholm/psr7. Any implementation that conforms to the relevant PSR contracts works because the bridge depends on interfaces, not a specific library.

Step 1 — install the package

Add the package with Composer:

composer require nextpdf/gotenberg

Composer resolves nextpdf/core ^3.0 and the PSR HTTP contracts: psr/http-client, psr/http-factory, and psr/log. It does not install a concrete HTTP client.

Step 2 — install a PSR-18 client and PSR-17 factories

Install one PSR-18 client and one matching set of PSR-17 factories. With Guzzle:

composer require guzzlehttp/guzzle guzzlehttp/psr7

Or with the Symfony HTTP client and Nyholm PSR-7:

composer require symfony/http-client nyholm/psr7

Pass these implementations to the bridge constructor. The bridge never builds an HTTP client itself. You choose the implementation when you wire the bridge together. See /integrations/gotenberg/configuration/ for the constructor shape and /integrations/gotenberg/quickstart/ for a complete wiring example.

Step 3 — stand up a Gotenberg service

The bridge calls Gotenberg’s LibreOffice conversion route, so run a Gotenberg instance that the bridge can reach. The upstream project publishes a container image. For local development, use:

docker run --rm -p 3000:3000 gotenberg/gotenberg:8

This exposes Gotenberg on port 3000 over plain HTTP. Use it for local development only. The bridge requires HTTPS for the configured application programming interface (API) URL and rejects plain http:// before it sends any request. For anything beyond a local experiment, place Gotenberg behind a Transport Layer Security (TLS)-terminating reverse proxy or service mesh, then point the bridge at the HTTPS endpoint. /integrations/gotenberg/security-and-operations/ covers the production deployment shape, network exposure, and authentication.

The image tag shown here (gotenberg/gotenberg:8) is the upstream Gotenberg major line. This project’s README and integration baseline reference that line. In production, pin to a specific patch tag rather than track a moving major tag. Also verify the route paths (/forms/libreoffice/convert, /health) against the Gotenberg version you deploy. The bridge assumes those two paths and makes no other assumptions about the service.

Step 4 — verify the wiring

By now, the package and an HTTP client are installed, and Gotenberg is reachable over HTTPS. Before you run a real conversion, confirm that the bridge can reach the service with the built-in health probe:

<?php

declare(strict_types=1);

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

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

$bridge = new GotenbergBridge(
    config: $config,
    httpClient: $psrHttpClient,
    requestFactory: $psrRequestFactory,
    streamFactory: $psrStreamFactory,
);

if (! $bridge->isAvailable()) {
    throw new \RuntimeException('Gotenberg is not reachable — check the URL, TLS, and network path.');
}

isAvailable() validates the configured URL first. It returns false for an empty URL, a non-HTTPS URL, or a private-address URL without sending network traffic. It then sends a HEAD request to <apiUrl>/health and reports the service as available when the status is below 500. If a network error occurs, the bridge catches it and reports the service as unavailable instead of throwing an exception.

Version note

This documentation describes the package at its ^3.0 line. That line matches the composer.json requirement and the SECURITY.md support matrix, where 3.x is supported and 2.x is not. Earlier 0.x references in the in-repository skeleton pages predate the 3.0 line. The composer.json constraint supersedes them.