Configuración del bundle de NextPDF para Symfony

Vista rápida

Todo el comportamiento del bundle se configura bajo la clave raíz nextpdf en config/packages/nextpdf.yaml. Cada clave tiene un valor predeterminado, por lo que la configuración es opcional. Esta página refleja con exactitud Configuration.php.

Árbol de configuración

El esquema está definido por NextPDF\Symfony\DependencyInjection\Configuration. Los valores no válidos hacen fallar la construcción del contenedor con una InvalidConfigurationException de Symfony.

Claves de nivel superior

Clave	Tipo	Predeterminado	Validación
page_format	enum	A4	uno de A4, A3, A5, Letter, Legal, Tabloid
orientation	enum	P	uno de P, L
unit	enum	mm	uno de pt, mm, cm, in
pdfa	escalar	null	uno de null, 4, 4e, 4f
fonts_path	escalar	%kernel.project_dir%/resources/fonts	—
cache_path	escalar	%kernel.cache_dir%/nextpdf	—
image_cache_mb	entero	50	mínimo 0
font_cache_locking	booleano	true	—
preload_fonts	lista de cadenas	[]	—

icc_profile

Clave	Tipo	Predeterminado
icc_profile.rgb	escalar	null
icc_profile.cmyk	escalar	null

defaults

Se aplica a cada documento producido por PdfFactory.

Clave	Tipo	Predeterminado
defaults.creator	escalar	NextPDF
defaults.author	escalar	(vacío)
defaults.language	escalar	en
defaults.margin_top	flotante	10.0
defaults.margin_right	flotante	10.0
defaults.margin_bottom	flotante	10.0
defaults.margin_left	flotante	10.0
defaults.font_family	escalar	dejavusans
defaults.font_size	flotante	12.0
defaults.trim_box	variable	null
defaults.bleed_box	variable	null

PdfFactory lee creator, author y language de esta sección y los aplica a cada documento nuevo. Las claves restantes se almacenan como parámetros del contenedor para que el motor las consuma.

artisan

Solo tiene efecto cuando nextpdf/artisan está instalado y se detecta.

Clave	Tipo	Predeterminado
artisan.chrome_binary	escalar	null
artisan.render_timeout	entero	30
artisan.default_css	escalar	(vacío)
artisan.no_sandbox	booleano	false
artisan.max_html_size	entero	5000000

signature

Solo tiene efecto cuando nextpdf/premium está instalado. Cuando el bundle y el nivel Pro están presentes, la configuración de firma admitida es el perfil baseline B-B. El nodo level acepta los valores de cadena enumerados a continuación por compatibilidad del esquema con la familia más amplia de configuración de NextPDF. La capacidad de firma que ofrece este bundle es B-B. Los perfiles superiores a B-B se documentan por separado en la documentación de NextPDF Premium y no se afirman en esta página.

Clave	Tipo	Predeterminado	Validación
signature.enabled	booleano	false	—
signature.certificate	escalar	null	—
signature.private_key	escalar	null	—
signature.password	escalar	(vacío)	—
signature.extra_certs	lista de cadenas	[]	—
signature.level	enum	B-B	conjunto aceptado: B-B, B-T, B-LT, B-LTA (B-B entregado; B-T/B-LT/B-LTA son valores de compatibilidad de esquema, no capacidad Pro entregada)

El compiler pass registra un servicio de firma solo cuando signature.enabled es true y signature.certificate está definido; de lo contrario, la sección permanece inerte.

tsa

Configuración del cliente de Time Stamp Authority, utilizada por la firma Pro cuando está configurada.

Clave	Tipo	Predeterminado
tsa.url	escalar	null
tsa.username	escalar	(vacío)
tsa.password	escalar	(vacío)
tsa.cert	escalar	null
tsa.key	escalar	null
tsa.timeout	entero	30
tsa.allow_insecure_http	booleano	false
tsa.pinned_public_keys	lista de cadenas	[]
tsa.warn_on_key_rotation	booleano	true

Se registra un servicio de cliente de TSA solo cuando tsa.url está definido.

ocsp_cache

Clave	Tipo	Predeterminado
ocsp_cache.enabled	booleano	true
ocsp_cache.ttl	entero	86400
ocsp_cache.directory	escalar	null

messenger

Parámetros de generación asíncrona, que se consumen cuando symfony/messenger está instalado.

Clave	Tipo	Predeterminado
messenger.transport	escalar	async
messenger.timeout	entero	120
messenger.retries	entero	3

Configuración de referencia

Archivo de configuración que muestra cada sección con sus valores predeterminados:

nextpdf:
    page_format: A4
    orientation: P
    unit: mm
    pdfa: ~
    fonts_path: '%kernel.project_dir%/resources/fonts'
    cache_path: '%kernel.cache_dir%/nextpdf'
    image_cache_mb: 50
    font_cache_locking: true
    preload_fonts: []
    icc_profile:
        rgb: ~
        cmyk: ~
    defaults:
        creator: NextPDF
        author: ''
        language: en
        margin_top: 10.0
        margin_right: 10.0
        margin_bottom: 10.0
        margin_left: 10.0
        font_family: dejavusans
        font_size: 12.0
        trim_box: ~
        bleed_box: ~
    artisan:
        chrome_binary: ~
        render_timeout: 30
        default_css: ''
        no_sandbox: false
        max_html_size: 5000000
    signature:
        enabled: false
        certificate: ~
        private_key: ~
        password: ''
        extra_certs: []
        level: B-B
    tsa:
        url: ~
        username: ''
        password: ''
        cert: ~
        key: ~
        timeout: 30
        allow_insecure_http: false
        pinned_public_keys: []
        warn_on_key_rotation: true
    ocsp_cache:
        enabled: true
        ttl: 86400
        directory: ~
    messenger:
        transport: async
        timeout: 120
        retries: 3

Servicios y alias del contenedor

El bundle carga sus definiciones de servicios desde config/services.php. La tabla siguiente refleja ese archivo con exactitud.

Id de servicio	Compartido	Público	Notas
NextPDF\Typography\FontRegistry	sí	—	construido a partir de nextpdf.fonts_path; logger PSR-3 opcional
NextPDF\Contracts\FontRegistryInterface	(alias)	sí	alias de FontRegistry
NextPDF\Graphics\ImageRegistry	sí	—	LRU acotada; etiquetada kernel.reset (reset)
NextPDF\Core\DocumentFactory	sí	—	comparte los dos registros
NextPDF\Contracts\DocumentFactoryInterface	(alias)	sí	alias de DocumentFactory
NextPDF\Symfony\Service\PdfFactory	sí	sí	lee defaults, pdfa, artisan como parámetros
NextPDF\Contracts\PdfDocumentInterface	no	sí	factory [PdfFactory, create]
NextPDF\Core\Document	(alias)	—	alias de PdfDocumentInterface
nextpdf.document	(alias)	sí	alias de PdfDocumentInterface
NextPDF\Symfony\Http\PdfResponse	—	sí	asistente sin estado

Además, el bundle registra los enlaces de contratos de EInvoice (EmbedderInterface, ValidatorInterface, ProfileInterface, SchematronRunnerInterface) solo cuando existen las clases de implementación Premium correspondientes. Cada enlace se registra como no compartido, de modo que sus consumidores reciben una instancia nueva. El estado del analizador de una llamada nunca se filtra a otras solicitudes.

Compartido frente a no compartido

nextpdf.document (y sus alias) es no compartido: cada resolución del contenedor devuelve un documento distinto. Según PSR-11, un contenedor puede devolver un valor diferente en llamadas sucesivas a get() con el mismo identificador — PSR-11 §1.1.2. El registro de fuentes es compartido y, tras el calentamiento, queda bloqueado. Por lo tanto, los datos estructurales de las fuentes se analizan una sola vez por proceso y no se pueden modificar en mitad de una solicitud.

Los servicios FontRegistry e ImageRegistry aceptan un Psr\Log\LoggerInterface opcional, enlazado mediante nullOnInvalid(). El logger es un colaborador opcional e intercambiable, coherente con el contrato de logger de PSR-3 (PSR-3).

Autowiring

PdfFactory, PdfResponse, la interfaz de la factoría de documentos y la interfaz del registro de fuentes son públicas. Se pueden obtener del contenedor o declarar por tipo en controladores y servicios con autowiring. La inyección por constructor de NextPDF\Symfony\Service\PdfFactory es el punto de entrada recomendado.

Casos límite y advertencias

• pdfa definido sin Pro — el valor se almacena, pero se ignora. PdfFactory aplica PDF/A solo cuando la extensión Pro se detecta en tiempo de compilación.
• image_cache_mb: 0 — válido; desactiva la caché LRU de imágenes. Los valores negativos se rechazan al construir.
• signature.enabled: true sin signature.certificate — el servicio de firmante no se registra; la configuración queda silenciosamente inerte por diseño.
• Marcadores de posición %kernel.*% — los valores predeterminados de fonts_path y cache_path usan parámetros del contenedor de Symfony; sustituirlos por rutas absolutas solo cuando se requiera la ruta literal.

Conformidad

Cada fila corresponde a una afirmación normativa de esta página, anclada a un reference_id completo de 64 caracteres hexadecimales del corpus SDO controlado. La procedencia (manifiesto del corpus, transporte de recuperación) se encuentra en _sidecars/rag-citations.yaml.

Especificación	Cláusula	reference_id	Afirmación
PSR-11	psr_11_container#1.1.2.p3.b		get() puede devolver valores diferentes por resolución
PSR-3	psr_3_logger#x3.p17		Colaborador LoggerInterface opcional

Contexto comercial

Las secciones signature y tsa solo tienen efecto cuando nextpdf/premium (Pro) está instalado. Se trata de una capacidad Pro opcional; el bundle Core documentado aquí no necesita ningún cambio de código para adoptarla. Consultar </get-license/?intent=symfony-pro>.

Véase también

• /integrations/symfony/install/ — instalación y registro del bundle.
• /integrations/symfony/overview/ — resumen de capacidades.
• /integrations/symfony/production-usage/ — seguridad de los workers y patrones asíncronos.
• /integrations/symfony/boot-and-discovery/ — cómo se resuelve la configuración durante el arranque.