Snelstart voor NextPDF Gotenberg

In het kort

In deze handleiding converteert u één .docx-bestand naar Portable Document Format (PDF). Na afloop hebt u drie dingen: een werkende bridge-instantie, een geverifieerde serviceverbinding en een PDF op schijf. Het volledige programma staat in de repository in examples/convert-office-to-pdf.php. De fragmenten hieronder komen uit dat programma.

Deze tutorial begint met de eenvoudigste werkende aanpak. Productieonderwerpen, waaronder het beheren van geheimen, nieuwe pogingen, time-outs en observeerbaarheid, worden behandeld in /integrations/gotenberg/production-usage/.

Voordat u begint

Controleer deze drie dingen voordat u verdergaat:

1. U hebt composer require nextpdf/gotenberg uitgevoerd, en er zijn een PHP Standards Recommendation (PSR)-18-client plus PSR-17-factory’s geïnstalleerd. Zie /integrations/gotenberg/install/.
2. Een Gotenberg-service is bereikbaar via Hypertext Transfer Protocol Secure (HTTPS). De bridge weigert kale http://-URL’s voordat een verzoek het proces verlaat.
3. U hebt een voorbeeldbestand in een van deze formaten: .docx, .xlsx, .pptx, .odt, .ods of .odp. Andere extensies mislukken met een ValueError.

Stap 1 — beschrijf de service

GotenbergConfig is een immutable value-object. Het heeft minimaal de HTTPS-basis-URL van uw Gotenberg-service nodig:

use NextPDF\Gotenberg\GotenbergConfig;

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

De op cURL gepinde transportlaag gebruikt timeout als overdrachtstime-out in seconden. Als apiKey niet leeg is, verzendt de bridge deze als Authorization: Bearer <token>. Laat apiKey leeg als uw Gotenberg-deployment geen token vereist.

Stap 2 — koppel de bridge

Geef de config en de PSR-componenten door aan de bridge. Geef ook een responseFactory mee om de cURL-transportlaag in te schakelen met Domain Name System (DNS)- en Transport Layer Security (TLS)-pinning:

use NextPDF\Gotenberg\GotenbergBridge;

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

De bridge maakt nooit een Hypertext Transfer Protocol (HTTP)-client voor u aan. Gebruik de PSR-18-client en PSR-17-factory’s die u hebt geïnstalleerd. Het voorbeeldbestand laat de Guzzle-koppeling zien in een opmerking.

Stap 3 — controleer de beschikbaarheid

Controleer de service voordat u een bestand converteert. De probe valideert de URL zonder netwerkverkeer en verzendt daarna een HEAD-verzoek naar <apiUrl>/health:

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

Bij een lege URL, een niet-HTTPS-URL, een URL naar een privéadres of een netwerkfout retourneert isAvailable() de waarde false (er wordt nooit een uitzondering gegooid). Een status lager dan 500 voor /health betekent dat de service beschikbaar is.

Stap 4 — converteer

Roep convertFile() aan met een pad op schijf. De bridge canonicaliseert het pad om traversal te blokkeren. De bridge koppelt de extensie aan een ondersteund formaat, controleert de grootte en bestandsnaam en verzendt vervolgens een multipart-verzoek naar <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;
}

Gebruik convertString() om bytes te converteren die al in het geheugen staan. Geef de oorspronkelijke bestandsnaam door, zodat de bridge de extensie kan detecteren:

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

Stap 5 — gebruik het resultaat

Het resultaat bevat drie dingen: de PDF-bytes, het bronformaat en een geldigheidscontrole:

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 wanneer de inhoud niet leeg is en begint met %PDF. size() retourneert de bytelengte. Daarna is de PDF een gewone stream (gegevensstroom) die u aan NextPDF kunt doorgeven voor nabewerking.

Het volledige programma

Het volledige, uitvoerbare programma staat in examples/convert-office-to-pdf.php in de packagerepository. Het bevat argumentparsing, configuratie op basis van omgevingsvariabelen, de health-probe, volledige foutafhandeling en de schrijfstap. Voer het uit met:

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

Wat nu

• /integrations/gotenberg/configuration/ — bekijk elke optie en de regels voor transportselectie.
• /integrations/gotenberg/production-usage/ — beheer geheimen, nieuwe pogingen, time-outs, logging en gelijktijdigheid.
• /integrations/gotenberg/troubleshooting/ — begrijp elke uitzondering die deze code kan gooien en wat die betekent.
• /integrations/gotenberg/integration/ — stuur een NextPDF-weergavepijplijn aan via de service.