NextPDF: integración con Gotenberg

De un vistazo

Esta página muestra cómo conectar el puente con el resto de una aplicación: instalarlo, cablearlo y, después, unir el PDF convertido a una canalización de posprocesamiento de NextPDF. El puente convierte un documento de Office en un PDF, y la canalización se encarga de todo lo que viene después. Esta página es el complemento orientado a tareas de /integrations/gotenberg/boot-and-discovery/, que explica por qué el cableado se estructura así.

Instalación

composer require nextpdf/gotenberg

Esto incorpora nextpdf/core ^3.0 y los contratos HTTP de PSR. Deben instalarse por separado un cliente PSR-18 y factorías PSR-17, como paquetes independientes. El puente depende únicamente de las interfaces, por lo que las bibliotecas concretas quedan a elección de la aplicación. Para una instalación completa, incluidas las instrucciones para poner en marcha el servicio de Gotenberg sobre HTTPS, consulte /integrations/gotenberg/install/.

Cableado

Construir el puente con un objeto de configuración y los colaboradores PSR. Inyectar también una factoría de respuestas para habilitar el transporte con fijación de DNS y fijación de TLS:

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: $httpClient,
    requestFactory: $requestFactory,
    streamFactory: $streamFactory,
    responseFactory: $responseFactory,
);

El puente requiere HTTPS para la URL configurada. Rechaza el http:// sin cifrar antes de emitir cualquier solicitud. Ejecutar Gotenberg detrás de una terminación TLS y apuntar el puente al extremo HTTPS.

Enlaces del contenedor

Registrar tres elementos en el contenedor anfitrión. El primero es el GotenbergConfig construido a partir de la fuente de configuración. El segundo es el cliente PSR-18 junto con sus factorías PSR-17. El tercero es GotenbergBridge, cableado con los anteriores. Este paquete no incluye enlaces propios. El registro nativo del framework corresponde a los paquetes dedicados de integración con framework. Consulte /integrations/gotenberg/boot-and-discovery/.

Configuración

El descriptor del servicio y sus límites se configuran mediante campos de GotenbergConfig. Abarcan la URL de la API, el tiempo de espera, el límite de tamaño, el token de portador y las fijaciones de TLS. En cambio, las opciones por solicitud, landscape y nativePageRanges, pertenecen al tipo de carga útil. /integrations/gotenberg/configuration/ documenta cada campo, con su tipo, valor predeterminado y efecto.

Unir el PDF convertido a una canalización de NextPDF

Flujo típico de extremo a extremo:

1. Convertir el documento de Office con convertFile() o convertString().
2. Tomar $result->pdfData, que contiene los bytes PDF sin procesar, y cargarlo en un documento de NextPDF.
3. Aplicar posprocesamiento, como ensamblaje de páginas, marca de agua, conversión a PDF/A o firmas digitales.

El paso 3 corresponde a NextPDF, no al puente. El paquete nextpdf/premium proporciona firma, perfiles PDF/A y marca de agua. Mantener la conversión y el posprocesamiento como etapas separadas permite diagnosticar cada fallo por separado.

use NextPDF\Gotenberg\GotenbergConvertException;

try {
    $result = $bridge->convertFile('/path/to/report.docx');
} catch (GotenbergConvertException $e) {
    // Conversion-layer failure — handle per your retry policy.
    throw $e;
}

// $result->pdfData is now an ordinary PDF byte stream ready for
// NextPDF post-processing.

La compatibilidad con PAdES de la edición Pro se limita a la línea base B-B. No proporciona B-T, B-LT ni B-LTA. Convertir un documento a través de este puente no implica ninguna capacidad de marca de tiempo ni de validación a largo plazo.

Prueba de humo

Después del cableado, confirmar la integración. Puede hacerse sin convertir un documento real:

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

isAvailable() valida la URL sin tráfico de red. Luego envía un HEAD a <apiUrl>/health. Después, convertir un documento pequeño que se sepa que es válido. Esto prueba la ruta multiparte completa hasta <apiUrl>/forms/libreoffice/convert, junto con la validación de la respuesta.

Puntos de entrada de la API pública

La superficie pública utilizada por esta integración:

• GotenbergConfig: descriptor de servicio y límites inmutables; fromArray() lo construye a partir de un array de configuración.
• GotenbergBridge::convertFile(string $path): convierte un archivo en disco.
• GotenbergBridge::convertString(string $bytes, string $fileName): convierte bytes almacenados en memoria.
• GotenbergBridge::isAvailable(): comprobación de disponibilidad que no lanza excepciones.
• GotenbergConvertResult: contiene pdfData, sourceFormat, isValid() y size().
• GotenbergConvertException: el tipo de excepción de la capa de conversión.

El contrato completo está en /integrations/gotenberg/configuration/ y /integrations/gotenberg/troubleshooting/. Cubre la selección de transporte y el catálogo de excepciones.

Véase también

• /integrations/gotenberg/boot-and-discovery/: por qué el cableado se estructura así.
• /integrations/gotenberg/quickstart/: una primera conversión guiada.
• /integrations/gotenberg/production-usage/: secretos, reintentos, tiempos de espera y observabilidad.
• /integrations/gotenberg/install/: instalación del paquete y del servicio de Gotenberg.