Instalar NextPDF Gotenberg

En resumen

La instalación del puente consta de dos partes. La primera es el paquete de PHP y sus dependencias PSR HTTP, que se instalan con Composer. La segunda es el servicio Gotenberg al que llama el paquete. El puente realiza la conversión delegando el trabajo a ese servicio, por lo que no puede convertir nada hasta que haya una instancia accesible de Gotenberg.

Completar ambas partes antes de escribir cualquier código de conversión.

Requisitos

Requisito	Restricción	Motivo
PHP	>=8.4 <9.0	El paquete declara este rango en composer.json.
NextPDF core	^3.0	Dependencia directa declarada en composer.json.
Cliente HTTP PSR-18	^1.0	El puente envía las solicitudes mediante un Psr\Http\Client\ClientInterface inyectado.
Fábricas HTTP PSR-17	^1.1	El puente construye las solicitudes y los flujos mediante las fábricas PSR-17 inyectadas.
Registrador PSR-3	^3.0 (opcional)	Se puede inyectar un registrador para el registro de depuración por solicitud.
Servicio Gotenberg	Accesible mediante HTTPS	La conversión la realiza el servicio externo, no este paquete.

El puente no incluye un cliente PSR-18 ni fábricas PSR-17. Las implementaciones se eligen en la aplicación. Por ejemplo, se puede combinar un cliente basado en Guzzle con sus fábricas PSR-17, o el cliente HTTP de Symfony con nyholm/psr7. Cualquier implementación que cumpla los contratos PSR pertinentes funciona, porque el puente depende únicamente de las interfaces, no de una biblioteca específica.

Paso 1 — instalar el paquete

Añadir el paquete con Composer:

composer require nextpdf/gotenberg

Con esto se resuelven nextpdf/core ^3.0 y los contratos PSR HTTP: psr/http-client, psr/http-factory y psr/log. No instala un cliente HTTP concreto.

Paso 2 — instalar un cliente PSR-18 y fábricas PSR-17

Instalar un cliente PSR-18 y un conjunto correspondiente de fábricas PSR-17. Con Guzzle:

composer require guzzlehttp/guzzle guzzlehttp/psr7

O bien con el cliente HTTP de Symfony y Nyholm PSR-7:

composer require symfony/http-client nyholm/psr7

El puente recibe estos componentes como argumentos del constructor. Nunca construye un cliente HTTP por sí mismo. Por tanto, la elección queda por completo en la aplicación y se realiza al conectar el puente. Consultar /integrations/gotenberg/configuration/ para conocer la forma del constructor y /integrations/gotenberg/quickstart/ para ver un ejemplo de conexión completo.

Paso 3 — poner en marcha un servicio Gotenberg

El puente llama a la ruta de conversión de LibreOffice de Gotenberg, por lo que necesita una instancia de Gotenberg accesible para el puente. El proyecto original publica una imagen de contenedor. El comando de referencia para el desarrollo local es:

docker run --rm -p 3000:3000 gotenberg/gotenberg:8

Esto expone Gotenberg en el puerto 3000 mediante HTTP sin cifrar, lo que solo resulta adecuado para el desarrollo local. El puente requiere HTTPS para la URL de la API configurada. Rechaza http:// sin cifrar antes de enviar cualquier solicitud. Para cualquier uso más allá de un experimento local, colocar Gotenberg detrás de un proxy inverso o una malla de servicios que termine TLS y, después, apuntar el puente al extremo HTTPS. /integrations/gotenberg/security-and-operations/ describe la forma del despliegue en producción, la exposición de red y la autenticación.

La etiqueta de imagen que se muestra aquí (gotenberg/gotenberg:8) corresponde a la línea principal original de Gotenberg. El README de este proyecto y la base de integración hacen referencia a esa línea. En producción, fijar una etiqueta de parche específica en lugar de seguir una etiqueta principal cambiante. Verificar también las rutas (/forms/libreoffice/convert, /health) con la versión de Gotenberg que se despliegue. El puente asume esas dos rutas y no hace ninguna otra suposición sobre el servicio.

Paso 4 — verificar la conexión

En este punto, ya deben estar instalados el paquete y un cliente HTTP, y Gotenberg debe ser accesible mediante HTTPS. Antes de intentar una conversión real, confirmar que el servicio es visible para el puente con la sonda de estado integrada:

<?php

declare(strict_types=1);

use NextPDF\Gotenberg\GotenbergBridge;
use NextPDF\Gotenberg\GotenbergConfig;

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

$bridge = new GotenbergBridge(
    config: $config,
    httpClient: $psrHttpClient,
    requestFactory: $psrRequestFactory,
    streamFactory: $psrStreamFactory,
);

if (! $bridge->isAvailable()) {
    throw new \RuntimeException('Gotenberg is not reachable — check the URL, TLS, and network path.');
}

isAvailable() valida primero la URL configurada. Devuelve false para una URL vacía, sin HTTPS o con dirección privada sin emitir ningún tráfico de red. A continuación, envía una solicitud HEAD a <apiUrl>/health e informa de que el servicio está disponible cuando el estado es inferior a 500. Un error de red se captura y se comunica como no disponible, en lugar de propagarse.

Nota de versión

Esta documentación describe el paquete en su línea ^3.0. Esa línea coincide con el requisito de composer.json y con la matriz de soporte de SECURITY.md, donde 3.x es compatible y 2.x no lo es. Las referencias anteriores a 0.x en las páginas esqueleto del repositorio preceden a la línea 3.0, y la restricción de composer.json las reemplaza.

Véase también

• /integrations/gotenberg/overview/ — qué hace el puente y los formatos que convierte.
• /integrations/gotenberg/configuration/ — cada argumento del constructor y cada campo de configuración.
• /integrations/gotenberg/quickstart/ — una primera conversión completa y ejecutable.
• /integrations/gotenberg/security-and-operations/ — cómo operar la dependencia de Gotenberg de forma segura.
• /integrations/gotenberg/boot-and-discovery/ — conexión automática del framework.