Guía de desarrollo para Gotenberg

De un vistazo

El paquete de Gotenberg delega la conversión en un servicio externo. El código de la aplicación debe hacer explícito el límite del servicio: validar la entrada, construir un payload, enviar la solicitud, analizar el resultado y manejar los fallos del servicio.

Usar esta guía al crear flujos de trabajo de conversión de Office a PDF, endpoints de subida, comprobaciones de estado del servicio o políticas de transporte en torno a nextpdf/gotenberg.

Límite arquitectónico

Capa	Propiedad de	Responsabilidad	No incluir aquí
Subida u origen del documento	Aplicación	Autorizar a quien llama, validar el origen y elegir la política de conversión.	Decisiones sobre la URL del servicio o la fijación del transporte.
Detección de formato	`nextpdf/gotenberg`	Asigna las extensiones seguras a `OfficeFormat`.	Confianza en el MIME sin validación de la aplicación.
Puente	`nextpdf/gotenberg`	Construye la solicitud multipart, llama a Gotenberg y analiza la respuesta PDF.	Consultas de dominio o política de almacenamiento.
Servicio Gotenberg	Despliegue	Convierte el documento de Office a PDF.	Autorización de la aplicación PHP.
Motor principal	`nextpdf/nextpdf`	Importar o combinar, opcionalmente, los datos del PDF convertido.	Conversión de Office.

Ciclo de vida en tiempo de ejecución

Etapa	Comportamiento	Acción del desarrollador
Creación de la configuración	Se cargan la URL de la API, el tiempo de espera, el tamaño máximo, la clave de API y los pins.	Mantener la URL del servicio y el token fuera del código fuente.
Validación de la entrada	Se comprueban la ruta, el tamaño, el nombre y la extensión del archivo, además de la seguridad de la URL.	Rechazar la entrada no admitida antes del envío.
Construcción del payload	`GotenbergConvertPayload` construye los datos del formulario multipart.	Conservar el nombre de archivo original solo cuando sea seguro.
Solicitud al servicio	El puente envía la solicitud a `/forms/libreoffice/convert`.	Configurar el tiempo de espera y la política de transporte.
Análisis del resultado	`GotenbergResponseParser::parse()` devuelve los bytes del PDF y los metadatos.	Tratar las respuestas de error o que no sean PDF como fallos de conversión.

Estructura de aplicación recomendada

Ruta	Propósito
`app/Pdf/Conversion/*`	Adaptador de aplicación en torno a `GotenbergBridge`.
`app/Pdf/Uploads/*`	Validación de subidas, almacenamiento y política de nombres de archivo.
`app/Pdf/ConversionPolicy/*`	Política de tamaño, formato y selección de servicio.
`tests/Pdf/Conversion/*`	Pruebas de formato, archivo, servicio y transporte.

Mantener la validación de archivos separada de la conversión. Un servicio de conversión debe recibir una entrada ya autorizada y, aun así, apoyarse en la validación del paquete como defensa en profundidad.

<?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;
    }
}

Patrones de conversión

Patrón	API	Cuándo usarlo	Restricción
Convertir una ruta de archivo	`GotenbergBridge::convertFile()`	El documento ya está almacenado en disco.	La ruta debe ser legible y estar aprobada por la política.
Convertir bytes en memoria	`GotenbergBridge::convertString()`	La aplicación ya tiene bytes provenientes de una subida o de un almacén de objetos.	El nombre de archivo sigue controlando la detección de formato.
Construir el payload directamente	`GotenbergConvertPayload`	Las pruebas o el código de transporte personalizado necesitan bytes multipart.	Mantener la generación del límite fuera de la entrada del usuario.
Analizar la respuesta directamente	`GotenbergResponseParser::parse()`	Una llamada HTTP personalizada que, aun así, necesita el análisis del paquete.	Pasar el `OfficeFormat` esperado.

Salud y disponibilidad

GotenbergBridge::isAvailable() es una señal de disponibilidad. No debe ser la única protección en tiempo de ejecución. Un servicio puede estar disponible durante la comprobación de disponibilidad y, aun así, fallar en la siguiente conversión.

Comprobación	Propósito	Nota operativa
Validez de la configuración	Detecta la falta de la URL de la API.	Ejecutarla durante el arranque de la aplicación o las comprobaciones de despliegue.
`/health` disponible	Detecta si el servicio es accesible.	Usarla para los paneles de disponibilidad.
Conversión de un fixture pequeño	Detecta una instalación de LibreOffice averiada o una regresión del servicio.	Ejecutarla en pruebas de humo programadas, no en cada solicitud.
Monitoreo del tiempo de espera	Detecta el comportamiento lento del servicio.	Hacer seguimiento por formato y tamaño de archivo.

Puntos de extensión

Punto de extensión	Usar para	Restricción
PSR-18 `ClientInterface`	Comportamiento personalizado del cliente HTTP.	Debe seguir la semántica de response/exception de PSR-18.
Factorías de PSR-17	Creación de solicitudes y streams.	Necesaria para construir el puente.
`HtmlSecurityPolicyInterface`	Política de la capa de análisis para entradas HTML.	Complementa la política de seguridad de Gotenberg.
`ResponseFactoryInterface`	Construcción de la respuesta del transporte cURL fijado.	Necesaria solo cuando se usa la ruta de transporte del paquete.
`GotenbergSecurityPolicy`	Validación de la URL, el tamaño del archivo, el nombre del archivo y los pins.	Mantener la autorización de la aplicación fuera de esta capa.

Flujo de trabajo de desarrollo

Empezar con convertString() en las pruebas para que los fixtures sean explícitos.
Agregar convertFile() solo después de que las rutas del sistema de archivos estén controladas.
Mantener el tamaño máximo de archivo por debajo de los límites del servicio y de la infraestructura.
Usar isAvailable() para las señales de disponibilidad, no como sustituto del manejo de errores.
Registrar el nombre de archivo, el formato, el tamaño, el estado y la duración. No registrar los bytes del documento.
Agregar pruebas de tiempo de espera y de modos de fallo antes de exponer los endpoints de subida.

Manejo de fallos

Fallo	Dónde debe manejarse	Respuesta recomendada
Extensión no admitida	Detección de formato.	Rechazar antes del envío al servicio.
Nombre de archivo no seguro	Política de seguridad.	Rechazar y normalizar la política de nombres de las subidas.
Archivo demasiado grande	Política de subidas y validación del paquete.	Rechazar antes de leer o enviar payloads grandes.
Gotenberg no disponible	Límite del puente.	Devolver un error de aplicación reintentable cuando corresponda.
Respuesta que no es PDF	Analizador de respuestas.	Tratarla como un fallo de conversión y capturar el estado del servicio.
Fallo de validación del pin o de la URL	Política de transporte.	Fallar de forma cerrada y alertar a los operadores.

Valores predeterminados seguros

Aspecto	Predeterminado	Cuándo cambiarlo
Tiempo de espera	`30` segundos.	Aumentarlo solo después de medir la latencia real del servicio.
Tamaño máximo de archivo	`52,428,800` bytes.	Reducirlo para endpoints públicos o multiinquilino.
Clave de API	Vacía.	Configurarla para despliegues privados de Gotenberg.
Formatos admitidos	`docx`, `xlsx`, `pptx`, `odt`, `ods`, `odp`.	Agregar formatos solo cuando `OfficeFormat` y el analizador los admitan.
Conjuntos de pins	Vacíos.	Agregar pins con pins de respaldo y un procedimiento de rotación.

Lista de verificación de pruebas

Las pruebas de formato deben cubrir las extensiones admitidas y no admitidas.
Las pruebas de archivos deben cubrir nombres de archivo faltantes, ilegibles, demasiado grandes y no seguros.
Las pruebas de servicio deben cubrir respuestas que no son 2xx, cuerpos de respuesta no válidos y excepciones de transporte.
Las pruebas de seguridad deben cubrir URLs de servicio privadas o no válidas cuando la política las prohíbe.
Las pruebas de tiempo de espera deben comprobar que el tiempo de espera configurado se pasa al transporte.
Las pruebas de fixtures deben mantener los documentos de muestra pequeños y no sensibles.