Configuración de NextPDF Gotenberg

De un vistazo

La configuración se define en dos lugares. El primero es el objeto de valor inmutable GotenbergConfig, que describe el servicio y sus límites. El segundo es el constructor GotenbergBridge, que conecta los colaboradores HTTP de PSR. Ambos usan inyección de dependencias explícita por constructor. No hay estado global, ni lectura de variables de entorno dentro del paquete, ni ningún endpoint predeterminado oculto.

El objeto de configuración

GotenbergConfig es un objeto de valor final readonly. Se puede construir directamente con argumentos con nombre o crear a partir de un array asociativo mediante GotenbergConfig::fromArray().

Campos

Campo	Tipo	Predeterminado	Efecto
apiUrl	string	''	URL base del servicio Gotenberg. Es obligatoria: un valor vacío hace que la configuración sea inválida y que cada conversión falle de inmediato. Debe ser HTTPS.
timeout	int	30	Tiempo de espera de transferencia estricto en segundos. El transporte cURL con fijación lo aplica cuando ese transporte está seleccionado.
maxFileSize	int	52_428_800	Tamaño máximo de entrada en bytes (50 MiB). Las entradas que superan este valor se rechazan antes de cualquier solicitud.
apiKey	string	''	Token Bearer. Cuando no está vacío, se envía como una cabecera Authorization: Bearer <token>. Está marcado como #[\SensitiveParameter] para ocultarlo en los rastreos de pila.
pinnedPublicKeys	list<string>	[]	Fijaciones SPKI de TLS primarias en formato sha256/<base64>. Un valor vacío deshabilita la fijación.
backupPublicKeys	list<string>	[]	Fijaciones SPKI de TLS de respaldo, mantenidas por separado para validar la rotación de forma independiente.

Construir directamente

<?php

declare(strict_types=1);

use NextPDF\Gotenberg\GotenbergConfig;

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

Construir a partir de un array

fromArray() acepta claves en snake_case e ignora cualquier elemento mal formado en lugar de lanzar una excepción. Un api_url que no sea cadena se convierte en ''. Un timeout que no sea entero usa 30. Un max_file_size que no sea entero usa el valor predeterminado de 50 MiB. Las listas de fijaciones que no sean arrays se convierten en []. Las entradas que no sean cadenas dentro de los arrays de fijaciones se descartan.

<?php

declare(strict_types=1);

use NextPDF\Gotenberg\GotenbergConfig;

$config = GotenbergConfig::fromArray([
    'api_url' => 'https://gotenberg.example.com',
    'timeout' => 45,
    'max_file_size' => 20_000_000,
    'api_key' => $secretFromYourSecretStore,
    'pinned_public_keys' => ['sha256/YLh1dUR9y6Kja30RrAn7JKnbQG/uEtLMkBgFF2Fuihg='],
    'backup_public_keys' => ['sha256/Vjs8r4z+80wjNcr1YKepWQboSIRi63WsWXhIMN+eWys='],
]);

Este análisis tolerante es deliberado. Permite pasar directamente un array de configuración del framework sin una capa de validación previa y, aun así, producir un objeto bien tipado. No valida que la URL sea accesible ni que las fijaciones sean correctas. Esas comprobaciones se realizan en el momento de la conversión.

Validez

isValid() devuelve true solo cuando apiUrl es una cadena no vacía. No realiza comprobaciones de red ni de esquema. La validación de HTTPS y de direcciones privadas se realiza dentro de la política de seguridad en el momento de la conversión. Si la configuración es inválida, convertFile() y convertString() lanzan una GotenbergConvertException con el mensaje Invalid Gotenberg configuration: apiUrl is empty. Una configuración inválida también hace que isAvailable() devuelva false sin ninguna llamada de red.

El constructor del puente

GotenbergBridge recibe la configuración junto con los colaboradores de PSR:

Argumento	Tipo	Obligatorio	Efecto
config	GotenbergConfig	sí	El descriptor del servicio y los límites descritos anteriormente.
httpClient	Psr\Http\Client\ClientInterface	sí	El cliente PSR-18 utilizado para la comprobación de estado y como transporte de reserva.
requestFactory	Psr\Http\Message\RequestFactoryInterface	sí	Construye la solicitud PSR-7.
streamFactory	Psr\Http\Message\StreamFactoryInterface	sí	Construye el flujo del cuerpo de la solicitud.
logger	Psr\Log\LoggerInterface|null	no (predeterminado null)	Cuando se proporciona, se registra una entrada de nivel debug por cada solicitud de conversión.
htmlSecurityPolicy	HtmlSecurityPolicyInterface|null	no	Si no se proporciona, se usa la política de seguridad HTML predeterminada del núcleo. Es una política de la capa de análisis, complementaria a la política de la capa de transporte.
responseFactory	Psr\Http\Message\ResponseFactoryInterface|null	no (predeterminado null)	Se necesita para activar el transporte cURL con fijación. Sin él, el puente siempre usa el cliente PSR-18 inyectado.

<?php

declare(strict_types=1);

use NextPDF\Gotenberg\GotenbergBridge;

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

Selección de transporte

El puente dispone de dos transportes y elige uno para cada solicitud de conversión:

• Transporte cURL con fijación — se usa cuando se ha inyectado un responseFactory y existe algo que fijar (la URL se resolvió a una o varias IP, o hay fijaciones SPKI configuradas). Este transporte vincula el conjunto de direcciones resueltas con CURLOPT_RESOLVE. Aplica la fijación SPKI con CURLOPT_PINNEDPUBLICKEY cuando hay fijaciones presentes. Verifica el par y el host (CURLOPT_SSL_VERIFYPEER, CURLOPT_SSL_VERIFYHOST = 2). Aplica el tiempo de espera configurado y deshabilita el seguimiento de redirecciones (CURLOPT_FOLLOWLOCATION = false, CURLOPT_MAXREDIRS = 0).
• Cliente PSR-18 inyectado — se usa en todos los demás casos, incluso cuando la URL de la API es un literal de IP pública directo (sin DNS que fijar) y no hay fijaciones SPKI configuradas, o cuando no se ha proporcionado ningún responseFactory.

La consecuencia práctica es que, para obtener conexiones resistentes al reenlace de DNS y con fijación de TLS, hay que inyectar un responseFactory y configurar fijaciones. La comprobación de estado siempre usa el cliente PSR-18 inyectado, independientemente de la selección de transporte.

Fijación de clave pública de TLS

La fijación sigue el modelo de huella SPKI SHA-256. Cada fijación es una cadena de la forma sha256/<base64-encoded-spki-hash>. El transporte también acepta la forma nativa de cURL sha256//<base64> y convierte a ella la variante de una sola barra. Cualquier otro prefijo genera una InvalidSpkiPinException.

allPublicKeyPins() devuelve la unión sin duplicados de pinnedPublicKeys y backupPublicKeys. La capa de TLS acepta un certificado cuya huella SPKI coincida con cualquier miembro de ese conjunto combinado. Operativamente, conviene configurar al menos una fijación de respaldo para que una rotación planificada de certificado o clave no bloquee el acceso del puente al servicio mientras se propaga la nueva clave. Mantener la lista de respaldo separada de la lista primaria permite validar y rotar la fijación de respaldo de forma independiente de la activa. Para el procedimiento de rotación, ver /integrations/gotenberg/security-and-operations/.

Opciones de conversión por solicitud

El tipo de carga útil multiparte (GotenbergConvertPayload) incluye dos opciones de conversión de Gotenberg opcionales además del archivo:

• landscape (bool, predeterminado false) — se envía como un campo de formulario landscape, "true" o "false".
• nativePageRanges (string, predeterminado '') — se envía como un campo de formulario nativePageRanges solo cuando no está vacío; acepta la sintaxis de rangos de Gotenberg como 1-3 o 1,3,5-9.

Los puntos de entrada públicos convertFile() y convertString() construyen la carga útil con los valores predeterminados de estos dos campos. Estos campos forman parte del contrato de la carga útil y se comprueban en la batería de pruebas. Si se necesita salida apaisada o selección de páginas, deben exponerse desde la capa de integración propia.

Véase también

• /integrations/gotenberg/install/ — instalación y línea base de Gotenberg.
• /integrations/gotenberg/quickstart/ — ejemplo ejecutable de extremo a extremo.
• /integrations/gotenberg/production-usage/ — fuente de configuración, secretos, tiempos de espera, reintentos.
• /integrations/gotenberg/security-and-operations/ — el modelo de seguridad completo y la rotación de fijaciones.
• /integrations/gotenberg/troubleshooting/ — significado de cada excepción relacionada con la configuración.