NextPDF Gotenberg installeren

In het kort

De installatie van de bridge bestaat uit twee delen: het PHP-pakket met de bijbehorende PHP Standard Recommendation (PSR)-HTTP-afhankelijkheden, dat u met Composer installeert, en de Gotenberg-service die door het pakket wordt aangeroepen. De bridge converteert bestanden door het werk naar die service te sturen, dus hij kan niets converteren zolang er geen Gotenberg-instance bereikbaar is.

Rond beide delen af voordat u conversiecode schrijft.

Vereisten

Vereiste	Beperking	Waarom
PHP	>=8.4 <9.0	Gedeclareerd door het pakket in composer.json.
NextPDF core	^3.0	Gedeclareerd als directe afhankelijkheid in composer.json.
PSR-18 HTTP-client	^1.0	De bridge verstuurt requests via een geïnjecteerde Psr\Http\Client\ClientInterface.
PSR-17 HTTP-factory’s	^1.1	De bridge bouwt requests en streams met geïnjecteerde PSR-17-factory’s.
PSR-3-logger	^3.0 (optioneel)	U kunt een logger injecteren voor debuglogging op requestniveau.
Gotenberg-service	Bereikbaar via HTTPS	De externe service voert de conversie uit; dit pakket niet.

De bridge bevat zelf geen PSR-18-client of PSR-17-factory’s. Kies de implementaties die bij uw applicatie passen. Combineer bijvoorbeeld een op Guzzle gebaseerde client met de bijbehorende PSR-17-factory’s, of gebruik de Symfony HTTP-client met nyholm/psr7. Elke implementatie die aan de relevante PSR-contracten voldoet werkt, omdat de bridge afhankelijk is van interfaces en niet van een specifieke bibliotheek.

Stap 1 — installeer het pakket

Voeg het pakket toe met Composer:

composer require nextpdf/gotenberg

Composer lost nextpdf/core ^3.0 en de PSR-HTTP-contracten op: psr/http-client, psr/http-factory en psr/log. Het installeert geen concrete HTTP-client.

Stap 2 — installeer een PSR-18-client en PSR-17-factory’s

Installeer één PSR-18-client en één bijbehorende set PSR-17-factory’s. Met Guzzle:

composer require guzzlehttp/guzzle guzzlehttp/psr7

Of met de Symfony HTTP-client en Nyholm PSR-7:

composer require symfony/http-client nyholm/psr7

Geef deze implementaties door aan de constructor van de bridge. De bridge bouwt nooit zelf een HTTP-client. U kiest de implementatie wanneer u de bridge samenstelt. Zie /integrations/gotenberg/configuration/ voor de vorm van de constructor en /integrations/gotenberg/quickstart/ voor een compleet configuratievoorbeeld.

Stap 3 — zet een Gotenberg-service op

De bridge roept de LibreOffice-conversieroute van Gotenberg aan, dus voer een Gotenberg-instance uit die voor de bridge bereikbaar is. Het upstream-project publiceert een container-image. Gebruik voor lokale ontwikkeling:

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

Hiermee wordt Gotenberg beschikbaar gesteld op poort 3000 via gewone HTTP. Gebruik dit alleen voor lokale ontwikkeling. De bridge vereist HTTPS voor de geconfigureerde application programming interface (API)-URL en weigert gewone http:// voordat hij een request verstuurt. Plaats Gotenberg voor alles wat verder gaat dan een lokaal experiment achter een reverse proxy of service mesh die Transport Layer Security (TLS) beëindigt, en wijs de bridge vervolgens naar het HTTPS-endpoint. /integrations/gotenberg/security-and-operations/ behandelt de vorm van de productie-deployment, netwerkblootstelling en authenticatie.

De hier getoonde image-tag (gotenberg/gotenberg:8) verwijst naar de upstream Gotenberg-majorlijn. De README en de integratiebasislijn van dit project verwijzen naar die lijn. Pin in productie op een specifieke patch-tag in plaats van een bewegende major-tag te volgen. Controleer ook de routepaden (/forms/libreoffice/convert, /health) ten opzichte van de Gotenberg-versie die u uitrolt. De bridge gaat uit van die twee paden en doet geen andere aannames over de service.

Stap 4 — verifieer de configuratie

Inmiddels zijn het pakket en een HTTP-client geïnstalleerd en is Gotenberg bereikbaar via HTTPS. Controleer voordat u een echte conversie uitvoert of de bridge de service kan bereiken met de ingebouwde 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() valideert eerst de geconfigureerde URL. Het retourneert false voor een lege URL, een niet-HTTPS-URL of een URL met een privéadres, zonder netwerkverkeer te versturen. Vervolgens verstuurt het een HEAD-request naar <apiUrl>/health en rapporteert het de service als beschikbaar wanneer de status lager is dan 500. Als er een netwerkfout optreedt, vangt de bridge die op en rapporteert hij de service als niet beschikbaar in plaats van een exception te werpen.

Versie-opmerking

Deze documentatie beschrijft het pakket op de ^3.0-lijn. Die lijn komt overeen met de composer.json-vereiste en de ondersteuningsmatrix in SECURITY.md, waarin 3.x wordt ondersteund en 2.x niet. Eerdere 0.x-verwijzingen in de skeletpagina’s in de repository dateren van vóór de 3.0-lijn. De beperking in composer.json is daarvoor in de plaats gekomen.

Zie ook

• /integrations/gotenberg/overview/ — wat de bridge doet en welke formaten hij converteert.
• /integrations/gotenberg/configuration/ — elk constructorargument en configuratieveld.
• /integrations/gotenberg/quickstart/ — een volledige, uitvoerbare eerste conversie.
• /integrations/gotenberg/security-and-operations/ — hoe u de Gotenberg-afhankelijkheid veilig beheert.
• /integrations/gotenberg/boot-and-discovery/ — automatische configuratie via het framework.