Referencia de la API de Gotenberg

De un vistazo

El paquete de Gotenberg expone un puente de servicio, GotenbergBridge, que convierte documentos de Office (docx, xlsx, pptx, odt, ods, odp) a PDF mediante una solicitud POST a un servicio Gotenberg externo. Ese puente se apoya en los value objects que se leen o se pasan: GotenbergConfig (el descriptor de servicio inmutable y sus límites), OfficeFormat (el enum de formatos admitidos), GotenbergConvertPayload (el cuerpo de la solicitud multipart) y GotenbergConvertResult (la respuesta PDF ya analizada). Un segundo nivel — GotenbergSecurityPolicy, GotenbergResponseParser y PinnedCurlTransport — contiene la maquinaria de validación, análisis y transporte con pinning que el puente gobierna internamente. Solo se usa al escribir código de transporte personalizado o pruebas.

Empieza aquí: crear un GotenbergConfig con la URL HTTPS del servicio y conectarlo a un GotenbergBridge con el cliente PSR-18 y las factories PSR-17. Después, llamar a convertFile() o convertString() y leer pdfData en el GotenbergConvertResult devuelto.

Tareas habituales

Estas son las tareas prácticas más frecuentes con este paquete, cada una con un fragmento ejecutable y verificado.

Convertir a PDF un archivo en disco

Indicar al puente una ruta; el formato se detecta a partir de la extensión.

<?php

declare(strict_types=1);

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: $psrHttpClient,
    requestFactory: $psrRequestFactory,
    streamFactory: $psrStreamFactory,
    responseFactory: $psrResponseFactory,
);

$result = $bridge->convertFile('/path/to/report.docx');

\file_put_contents('/path/to/report.pdf', $result->pdfData);

Qué hace: valida la URL, la ruta, el tamaño y el nombre de archivo, envía una única solicitud multipart y escribe en disco los bytes del PDF devuelto.

Convertir bytes en memoria a PDF

Usar convertString() cuando ya se tienen los bytes; el nombre de archivo determina la detección del formato.

<?php

declare(strict_types=1);

use NextPDF\Gotenberg\GotenbergBridge;

/** @var GotenbergBridge $bridge */
$result = $bridge->convertString($xlsxBytes, 'spreadsheet.xlsx');

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

Qué hace: detecta xlsx a partir del nombre de archivo, convierte los bytes y confirma que el resultado empieza con la firma %PDF antes de usarlo.

Comprobar que el servicio está listo antes de convertir

Condicionar el trabajo a isAvailable(), que valida la URL sin generar tráfico y después envía un HEAD a /health.

<?php

declare(strict_types=1);

use NextPDF\Gotenberg\GotenbergBridge;

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

Qué hace: devuelve false (nunca lanza una excepción) ante una URL vacía, que no sea HTTPS o que apunte a una dirección privada, y ante cualquier error de red, de modo que permite fallar pronto antes de despachar una conversión.

Puente

Esta tabla describe la superficie del puente: sirve como referencia al construir GotenbergBridge o al llamar a sus métodos de conversión y comprobación de disponibilidad.

Símbolo	Parámetros	Comportamiento predeterminado	Devuelve	Lanza o falla con	Notas
`new GotenbergBridge(GotenbergConfig $config, ClientInterface $httpClient, RequestFactoryInterface $requestFactory, StreamFactoryInterface $streamFactory, ?LoggerInterface $logger = null, ?HtmlSecurityPolicyInterface $htmlSecurityPolicy = null, ?ResponseFactoryInterface $responseFactory = null)`	Config, cliente PSR-18, factories PSR-17, logger opcional, política HTML opcional, response factory opcional.	Usa `DefaultHtmlSecurityPolicy` cuando no se proporciona ninguna política.	`GotenbergBridge`	Errores de wiring del contenedor.	La response factory permite usar el transporte cURL con pinning cuando se necesita pinning.
`GotenbergBridge::convertFile(string $filePath)`	Ruta del sistema de archivos a un documento de Office.	Usa la extensión del archivo para detectar el formato.	`GotenbergConvertResult`	`GotenbergConvertException`, `RuntimeException`, `ValueError` para un formato no admitido.	Resuelve la ruta real y comprueba la legibilidad, el tamaño y el nombre de archivo.
`GotenbergBridge::convertString(string $content, string $fileName)`	Bytes en bruto y nombre de archivo original.	Usa la extensión del nombre de archivo para detectar el formato.	`GotenbergConvertResult`	Igual que `convertFile`.	Usarlo cuando la aplicación ya tiene los bytes del archivo.
`GotenbergBridge::isAvailable()`	ninguno.	Solicitud HEAD a `/health` cuando la config es válida.	`bool`	Devuelve `false` ante errores.	Solo es una señal de disponibilidad.
`GotenbergBridge::getHtmlSecurityPolicy()`	ninguno.	Devuelve la política configurada de la capa de análisis.	`HtmlSecurityPolicyInterface`	ninguno esperado.	Complementa la política de seguridad a nivel de transporte.

Configuración y payloads

Esta tabla cubre los value objects que se construyen a mano: el descriptor de servicio GotenbergConfig y los portadores de solicitud y respuesta GotenbergConvertPayload/GotenbergConvertResult, cuando se necesita un control más fino que el que ofrecen los dos puntos de entrada de conversión.

Símbolo	Parámetros	Comportamiento predeterminado	Devuelve	Lanza o falla con	Notas
`new GotenbergConfig(string $apiUrl = '', int $timeout = 30, int $maxFileSize = 52428800, string $apiKey = '', array $pinnedPublicKeys = [], array $backupPublicKeys = [])`	URL de la API, tiempo de espera, tamaño máximo de archivo, bearer token, conjuntos de pins.	La URL vacía no es válida; el tamaño máximo predeterminado es 50 MiB.	`GotenbergConfig`	ninguno esperado.	Mantener en secreto la clave de API.
`GotenbergConfig::fromArray(array $config)`	`api_url`, `timeout`, `max_file_size`, `api_key`, arrays de pins.	Los valores opcionales omitidos usan los valores predeterminados del constructor.	`GotenbergConfig`	ninguno esperado.	Las listas de cadenas ignoran los valores que no son cadenas.
`GotenbergConfig::isValid()`	ninguno.	Es válida cuando la URL de la API no está vacía.	`bool`	ninguno esperado.	La seguridad de la URL se valida antes de la E/S de red.
`GotenbergConfig::allPublicKeyPins()`	ninguno.	Combina los pins primarios y los de respaldo.	`list<string>`	ninguno esperado.	Una lista vacía desactiva el pinning.
`new GotenbergConvertPayload(string $fileName, string $fileContent, OfficeFormat $format, bool $landscape = false, string $nativePageRanges = '')`	Nombre de archivo, bytes, formato, indicador de orientación, rangos de páginas.	Vertical; todas las páginas.	`GotenbergConvertPayload`	ninguno esperado.	El payload se convierte en datos de formulario multipart.
`GotenbergConvertPayload::toMultipartBody(string $boundary)`	Boundary multipart.	Incluye el campo de rango de páginas solo cuando no está vacío.	`string`	ninguno esperado.	El boundary lo genera el puente.
`GotenbergConvertPayload::contentType(string $boundary)`	Boundary multipart.	Usa `multipart/form-data`.	`string`	ninguno esperado.	Adjuntarlo como el `Content-Type` de la solicitud.
`new GotenbergConvertResult(string $pdfData, OfficeFormat $sourceFormat, float $renderTimeMs = 0.0)`	Bytes del PDF convertido, formato de origen, duración de renderizado opcional.	La duración de renderizado es `0.0` cuando no se mide.	`GotenbergConvertResult`	ninguno esperado.	Lo devuelve `GotenbergResponseParser::parse()`.
`GotenbergConvertResult::isValid()`	ninguno.	Es válido cuando los bytes del PDF convertido no están vacíos y parecen datos PDF.	`bool`	ninguno esperado.	Comprobarlo antes de persistir o transmitir el resultado.
`GotenbergConvertResult::size()`	ninguno.	Cuenta los bytes del PDF convertido.	`int`	ninguno esperado.	Usarlo para cuotas, telemetría y límites de respuesta.

Formatos de Office

Esta tabla corresponde al enum OfficeFormat. Sirve para mapear una extensión a un formato, leer su tipo MIME de subida o comprobar cuáles de los seis formatos están admitidos.

Símbolo	Parámetros	Comportamiento predeterminado	Devuelve	Lanza o falla con	Notas
`OfficeFormat::fromExtension(string $ext)`	Extensión de archivo con o sin el punto inicial.	Coincidencia sin distinción entre mayúsculas y minúsculas.	`OfficeFormat`	`ValueError` para una extensión no admitida.	Valores admitidos: `docx`, `xlsx`, `pptx`, `odt`, `ods`, `odp`.
`OfficeFormat::mimeType()`	ninguno.	Mapea cada caso del enum al tipo MIME de subida.	`string`	ninguno esperado.	Se usa en la parte de archivo multipart.
`OfficeFormat::extension()`	ninguno.	Devuelve el valor de respaldo del enum.	`string`	ninguno esperado.	Útil para diagnósticos y nombres de archivo.

Seguridad, análisis y transporte

Esta tabla recoge la maquinaria interna que el puente gobierna. Debe usarse solo al escribir transporte personalizado, una llamada HTTP a medida que aun así necesite el análisis del paquete, o diagnósticos de bajo nivel de seguridad y pinning.

Símbolo	Parámetros	Comportamiento predeterminado	Devuelve	Lanza o falla con	Notas
`GotenbergSecurityPolicy::validateApiUrl(string $url)`	URL base de la API.	Analiza y valida el destino antes de la E/S de red.	`array`	`RuntimeException` para URLs inseguras o no válidas.	Mantiene fuera del código de conversión los errores de endpoint de tipo SSRF.
`GotenbergSecurityPolicy::assertPinsStillValid(string $host, array $pinnedIps)`	Host y lista de IP con pin.	Verifica que se cumplan las expectativas de pin de DNS.	`void`	`RuntimeException` cuando los pins están obsoletos o no son válidos.	Usarlo en despliegues con pinning y en diagnósticos operativos.
`GotenbergSecurityPolicy::validateFileSize(int $size, int $maxSize)`	Tamaño real y máximo configurado.	Acepta archivos iguales o inferiores al límite configurado.	`void`	`RuntimeException` cuando el archivo es demasiado grande.	Aplicarlo antes de construir la solicitud.
`GotenbergSecurityPolicy::validateFileName(string $name)`	Nombre de archivo original.	Rechaza nombres de archivo inseguros o no admitidos.	`void`	`RuntimeException` para nombres no válidos.	Evita nombres de archivo multipart malformados.
`GotenbergResponseParser::parse(ResponseInterface $response, OfficeFormat $format)`	Respuesta PSR-7 y formato de Office esperado.	Extrae los bytes del PDF convertido de una respuesta correcta.	`GotenbergConvertResult`	`GotenbergConvertException` para respuestas fallidas o salida PDF no válida.	Parser central para la conversión tanto de archivo como de cadena.
`new PinnedCurlTransport(ResponseFactoryInterface $responseFactory, StreamFactoryInterface $streamFactory, array $pinnedIps = [], array $pinnedPublicKeys = [], int $timeoutSeconds = 30)`	Factories PSR-17, IP con pin, claves públicas con pin, tiempo de espera.	Sin pins y tiempo de espera de 30 segundos.	`PinnedCurlTransport`	ninguno esperado.	Usarlo solo cuando se requiere pinning a nivel de cURL.
`PinnedCurlTransport::sendRequest(RequestInterface $request)`	Solicitud PSR-7.	Envía mediante cURL con el tiempo de espera configurado y los controles de pinning.	`ResponseInterface`	`GotenbergConvertException` ante un fallo de cURL o de transporte.	Usarlo cuando el pinning no puede delegarse a otro cliente HTTP.
`PinnedCurlTransport::buildCurlOptions(RequestInterface $request, string $host, int $port)`	Solicitud, host y puerto.	Construye el array de opciones de cURL que usa `sendRequest()`.	`array`	Errores de solicitud no válida o de configuración de pins.	Diagnósticos de bajo nivel y hook de pruebas.

Notas de desarrollo

Tratar Gotenberg como un límite de servicio externo. Configurar de forma deliberada el tiempo de espera, el tamaño, la URL y la política de pins.
convertFile() lee el archivo completo en memoria antes de construir la solicitud.
Registrar metadatos como el nombre de archivo y la longitud del contenido, no el contenido del archivo.