NextPDF-Gotenberg-integratie

In een oogopslag

Deze pagina laat zien hoe je de brug aansluit op de rest van je applicatie. Installeer de brug, sluit deze aan en geef de geconverteerde Portable Document Format (PDF) daarna door aan een NextPDF-nabewerkingspijplijn. De brug converteert een Office-document naar PDF; de pijplijn verwerkt alles na de conversie. Zie /integrations/gotenberg/boot-and-discovery/ voor het ontwerp achter deze aansluiting.

Installeren

composer require nextpdf/gotenberg

Als je dit pakket installeert, worden ook nextpdf/core ^3.0 en de PHP Standards Recommendation (PSR) Hypertext Transfer Protocol (HTTP)-contracten geïnstalleerd. Installeer een PSR-18-client en PSR-17-factory’s als afzonderlijke pakketten. De brug is alleen afhankelijk van de interfaces, zodat je zelf de concrete bibliotheken kunt kiezen. Zie /integrations/gotenberg/install/ voor de volledige installatiestappen, inclusief hoe je de Gotenberg-service via Hypertext Transfer Protocol Secure (HTTPS) draait.

Bedrading

Maak de brug aan met een configuratieobject en de PSR-afhankelijkheden. Injecteer ook een response-factory; die schakelt het transport in met Domain Name System (DNS)-pinning en Transport Layer Security (TLS)-pinning:

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,
);

De brug vereist HTTPS voor de geconfigureerde URL. De brug weigert http:// voordat er een verzoek wordt verzonden. Draai Gotenberg achter TLS-terminatie en wijs de brug daarna naar het HTTPS-eindpunt.

Container-bindingen

Registreer drie items in je host-container: de GotenbergConfig die vanuit je configuratiebron is opgebouwd, je PSR-18-client met je PSR-17-factory’s, en GotenbergBridge, aangesloten op die afhankelijkheden. Dit pakket levert geen eigen bindingen. Frameworkspecifieke registratie hoort thuis in de daarvoor bedoelde framework-integratiepakketten. Zie /integrations/gotenberg/boot-and-discovery/.

Configuratie

Alle velden en limieten van de servicedescriptor staan in GotenbergConfig. Daaronder vallen de application programming interface (API)-URL, de time-out, de groottelimiet, het bearertoken en de TLS-pins. De opties per verzoek, landscape en nativePageRanges, staan daarentegen op het payload-type. In /integrations/gotenberg/configuration/ wordt elk veld gedocumenteerd, met het bijbehorende type, de standaardwaarde en het effect.

De geconverteerde PDF koppelen aan een NextPDF-pijplijn

Een typische end-to-end-flow:

1. Converteer het Office-document met convertFile() of convertString().
2. Neem $result->pdfData, dat de ruwe PDF-bytes bevat, en laad deze in een NextPDF-document.
3. Pas nabewerking toe, zoals pagina-assemblage, het aanbrengen van een watermerk, PDF/A-conversie of digitale handtekeningen.

Stap 3 hoort bij NextPDF, niet bij de brug. Het nextpdf/premium-pakket biedt ondertekening, PDF/A-profielen en het aanbrengen van watermerken. Houd conversie en nabewerking gescheiden, zodat je elke fout afzonderlijk kunt diagnosticeren.

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.

De ondersteuning voor PDF Advanced Electronic Signatures (PAdES) in de Pro-editie geldt uitsluitend voor de B-B-baseline. Die biedt geen B-T, B-LT of B-LTA. Een document converteren via deze brug impliceert geen enkele mogelijkheid voor tijdstempels of langetermijnvalidatie.

Smoke-test

Controleer na het aansluiten de integratie zonder een echt document te converteren:

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

isAvailable() valideert de URL zonder netwerkverkeer. Daarna stuurt de methode een HEAD-verzoek naar <apiUrl>/health. Converteer vervolgens één klein document waarvan je zeker weet dat het correct is. Daarmee doorloop je het volledige multipart-pad naar <apiUrl>/forms/libreoffice/convert en valideer je de respons.

Openbare API-toegangspunten

De openbare API die deze integratie gebruikt:

• GotenbergConfig — onveranderlijke servicedescriptor met limieten; fromArray() bouwt deze op uit een configuratie-array.
• GotenbergBridge::convertFile(string $path) — converteert een bestand op schijf.
• GotenbergBridge::convertString(string $bytes, string $fileName) — converteert bytes die in het geheugen worden bewaard.
• GotenbergBridge::isAvailable() — gereedheidstest die geen uitzondering werpt.
• GotenbergConvertResult — bevat pdfData, sourceFormat, isValid() en size().
• GotenbergConvertException — het uitzonderingstype van de conversielaag.

Het volledige contract staat in /integrations/gotenberg/configuration/ en /integrations/gotenberg/troubleshooting/. Daarin worden de transportselectie en de uitzonderingscatalogus behandeld.

Zie ook

• /integrations/gotenberg/boot-and-discovery/ — waarom de aansluiting eruitziet zoals die eruitziet.
• /integrations/gotenberg/quickstart/ — een begeleide eerste conversie.
• /integrations/gotenberg/production-usage/ — secrets, herhaalpogingen, time-outs, waarneembaarheid.
• /integrations/gotenberg/install/ — installatie van het pakket en de Gotenberg-service.