Inicio rápido de NextPDF Gotenberg

De un vistazo

En esta guía se convierte un archivo .docx a PDF. Al finalizar, se obtienen tres cosas: una instancia de puente operativa, una conexión de servicio verificada y un PDF en disco. El programa completo se encuentra en el repositorio en examples/convert-office-to-pdf.php. Los fragmentos siguientes son extractos de ese programa.

Esta página es un tutorial, por lo que presenta primero el flujo correcto. Los aspectos de producción —procedencia de los secretos, reintentos, tiempos de espera y observabilidad— se tratan en /integrations/gotenberg/production-usage/.

Antes de empezar

Comprobar estas tres cosas:

1. Que se haya ejecutado composer require nextpdf/gotenberg y que estén instalados un cliente PSR-18 y fábricas PSR-17. Véase /integrations/gotenberg/install/.
2. Que haya un servicio de Gotenberg accesible por HTTPS. El puente rechaza http:// sin cifrar antes de que cualquier solicitud salga del proceso.
3. Que se disponga de un archivo de muestra en uno de estos formatos: .docx, .xlsx, .pptx, .odt, .ods o .odp. Las demás extensiones se rechazan con un ValueError.

Paso 1 — describir el servicio

GotenbergConfig es un objeto de valor inmutable. Como mínimo, se necesita la URL base HTTPS del servicio de Gotenberg:

use NextPDF\Gotenberg\GotenbergConfig;

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

timeout es el tiempo de espera de transferencia, en segundos, aplicado por el transporte cURL con fijación. apiKey, cuando no está vacía, se envía como Authorization: Bearer <token>. Dejar apiKey vacía si la implementación de Gotenberg no requiere un token.

Paso 2 — conectar el puente

El puente recibe la configuración junto con los colaboradores PSR. También se debe inyectar un responseFactory para habilitar el transporte cURL con fijación de DNS y de TLS:

use NextPDF\Gotenberg\GotenbergBridge;

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

El puente nunca construye por sí mismo un cliente HTTP. Usar el cliente PSR-18 y las fábricas PSR-17 que se hayan instalado. El archivo de ejemplo muestra la conexión con Guzzle en un comentario.

Paso 3 — comprobar la disponibilidad

Sondear el servicio antes de convertir nada. El sondeo valida la URL sin generar tráfico de red y, a continuación, envía un HEAD a <apiUrl>/health:

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

isAvailable() devuelve false (nunca lanza una excepción) para una URL vacía, sin HTTPS o con dirección privada, y para cualquier error de red. Un estado inferior a 500 en /health significa que el servicio está disponible.

Paso 4 — convertir

convertFile() recibe una ruta en disco. La ruta se canonicaliza para bloquear el recorrido de directorios. La extensión se asigna a un formato compatible. El tamaño y el nombre de archivo se filtran. A continuación, se envía una solicitud multiparte a <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;
}

Para convertir bytes que ya están en memoria, usar convertString(). Pasar el nombre de archivo original para que el puente pueda detectar la extensión:

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

Paso 5 — usar el resultado

El resultado contiene tres datos: los bytes del PDF, el formato de origen y una comprobación de validez:

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() es verdadero cuando el cuerpo no está vacío y empieza por %PDF. size() es la longitud en bytes. A partir de aquí, el PDF es un flujo común que puede pasarse a NextPDF para el posprocesamiento.

El programa completo

El programa completo y ejecutable se encuentra en examples/convert-office-to-pdf.php en el repositorio del paquete. Incluye el análisis de argumentos, la configuración basada en el entorno, el sondeo de estado, el manejo exhaustivo de errores y la escritura del archivo. Ejecutarlo con:

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

Qué sigue

• /integrations/gotenberg/configuration/ — todas las opciones y las reglas de selección de transporte.
• /integrations/gotenberg/production-usage/ — secretos, reintentos, tiempos de espera, registro, concurrencia.
• /integrations/gotenberg/troubleshooting/ — todas las excepciones que este código puede lanzar y su significado.
• /integrations/gotenberg/integration/ — cómo dirigir un flujo de renderizado de NextPDF a través del servicio.