Gotenberg developer guide

At a glance

The Gotenberg package sends Portable Document Format (PDF) conversion to an external service. In application code, keep that service boundary explicit: validate input, build a payload, send the request, parse the result, and handle service failure.

Use this guide when you build office-to-PDF conversion workflows, upload endpoints, service health checks, or transport policy around nextpdf/gotenberg.

Architecture boundary

Layer	Owned by	Responsibility	Do not put here
Upload or document source	Application	Authorize the caller, validate the source, and choose conversion policy.	Service endpoint or transport pinning decisions.
Format detection	nextpdf/gotenberg	Map safe extensions to OfficeFormat.	Trust in declared media types without application validation.
Bridge	nextpdf/gotenberg	Build the multipart request, call Gotenberg, and parse the PDF response.	Domain queries or storage policy.
Gotenberg service	Deployment	Convert the office document to PDF.	Hypertext Preprocessor (PHP) application authorization.
Core engine	nextpdf/nextpdf	Import or combine converted PDF data when needed.	Office conversion.

Runtime lifecycle

Stage	Behavior	Developer action
Config creation	Application programming interface (API) endpoint, timeout, max size, API key, and pins load from configuration.	Keep the service endpoint and token out of source code.
Input validation	File path, file size, filename, extension, and Uniform Resource Locator (URL) safety are checked.	Reject unsupported input before you dispatch it.
Payload construction	GotenbergConvertPayload builds multipart form data.	Preserve the original filename only when it is safe.
Service request	The bridge sends the request to /forms/libreoffice/convert.	Configure the timeout and transport policy.
Result parsing	GotenbergResponseParser::parse() returns PDF bytes and metadata.	Treat non-PDF responses and error responses as conversion failures.

Recommended application structure

Path	Purpose
app/Pdf/Conversion/*	Application wrapper around GotenbergBridge.
app/Pdf/Uploads/*	Upload validation, storage, and filename policy.
app/Pdf/ConversionPolicy/*	Size, format, and service selection policy.
tests/Pdf/Conversion/*	Format, file, service, and transport tests.

Keep file validation separate from conversion. Your conversion service should receive already-authorized input, then still rely on package validation as defense in depth.

<?php

use NextPDF\Gotenberg\GotenbergBridge;

final readonly class OfficeConversionService
{
    public function __construct(
        private GotenbergBridge $bridge,
    ) {}

    public function convertUploadedFile(string $safePath): string
    {
        $result = $this->bridge->convertFile($safePath);

        if (!$result->isValid()) {
            throw new RuntimeException('The conversion service did not return a valid PDF.');
        }

        return $result->pdfData;
    }
}

Conversion patterns

Pattern	API	Use when	Constraint
Convert file path	GotenbergBridge::convertFile()	The document is already stored on disk.	The path must be readable and policy-approved.
Convert in-memory bytes	GotenbergBridge::convertString()	Your application already has bytes from an upload or object store.	The filename still controls format detection.
Build payload directly	GotenbergConvertPayload	You need multipart bytes for tests or custom transport code.	Keep boundary generation outside user input.
Parse response directly	GotenbergResponseParser::parse()	Custom Hypertext Transfer Protocol (HTTP) calls still need package parsing.	You must pass the expected OfficeFormat.

Health and readiness

GotenbergBridge::isAvailable() is a readiness signal, not your only runtime guard. A service can pass readiness and still fail the next conversion.

Check	Purpose	Operational note
Config validity	Detect a missing API endpoint.	Run this during app boot or deployment checks.
/health availability	Detect whether the service is reachable.	Use this for readiness dashboards.
Small fixture conversion	Detect broken LibreOffice behavior or service regression.	Run this in scheduled smoke tests, not on every request.
Timeout monitoring	Detect slow service behavior.	Track this by format and file size.

Extension points

Extension point	Use it for	Constraint
PHP Standard Recommendation (PSR)-18 ClientInterface	Custom HTTP client behavior.	Must follow PSR-18 response and exception semantics.
PSR-17 factories	Request and stream creation.	Required for bridge construction.
HtmlSecurityPolicyInterface	Parse-layer policy for Hypertext Markup Language (HTML) inputs.	Complements Gotenberg security policy.
ResponseFactoryInterface	Pinned cURL transport response construction.	Required only when you use the package transport path.
GotenbergSecurityPolicy	URL, file size, filename, and pin validation.	Keep application authorization outside this layer.

Development workflow

1. Start with convertString() in tests to keep fixtures explicit.
2. Add convertFile() only after filesystem paths are controlled.
3. Keep the max file size below service and infrastructure limits.
4. Use isAvailable() for readiness signals, not as a replacement for error handling.
5. Log filename, format, size, status, and duration. Do not log document bytes.
6. Add timeout and failure-mode tests before you expose upload endpoints.

Failure handling

Failure	Where it should be handled	Recommended response
Unsupported extension	Format detection.	Reject before you dispatch to the service.
Unsafe filename	Security policy.	Reject it and normalize the upload naming policy.
Oversize file	Upload policy and package validation.	Reject before you read or send large payloads.
Gotenberg unavailable	Bridge boundary.	Return a retryable application error when appropriate.
Non-PDF response	Response parser.	Treat it as a conversion failure and capture service status.
Pin or URL validation failure	Transport policy.	Fail closed and alert operators.

Safe defaults

Concern	Default	When to override
Timeout	30 seconds.	Increase only after you measure real service latency.
Max file size	52,428,800 bytes.	Lower for public or multi-tenant endpoints.
API key	Empty.	Set for private Gotenberg deployments.
Supported formats	docx, xlsx, pptx, odt, ods, odp.	Add formats only when OfficeFormat and the parser support them.
Pin sets	Empty.	Add pins with backup pins and a rotation procedure.

Testing checklist

• Format tests cover supported and unsupported extensions.
• File tests cover missing files, unreadable files, oversize files, and unsafe filenames.
• Service tests cover non-2xx responses, invalid response bodies, and transport exceptions.
• Security tests cover private or invalid service URLs when the policy forbids them.
• Timeout tests assert that the configured timeout is passed to the transport.
• Fixture tests keep sample documents small and non-sensitive.