Preguntas frecuentes de NextPDF

En resumen

Esta página responde a las preguntas que surgen primero al evaluar NextPDF o al empezar un proyecto nuevo. Cada respuesta es breve y enlaza con la página que la cubre por completo. NextPDF es un motor de PHP 8.4 que genera e inspecciona documentos en formato de documento portátil (PDF) 2.0, el formato de archivo definido por ISO 32000-2.

Si eres totalmente nuevo, lee primero Empezar y luego vuelve aquí para los detalles concretos.

Primeros pasos

¿Qué edición necesito: Core, Pro o Enterprise?

Empieza con Core. El núcleo de código abierto (nextpdf/core) genera salida PDF, representa el HTML admitido en PDF e inspecciona PDF bajo la licencia Apache-2.0 y sin coste. El Core ya produce firmas CMS SignedData para los niveles base B-B y B-T de las firmas electrónicas avanzadas de PDF (PAdES). Elige Pro cuando necesites generación y operaciones avanzadas con documentos, salida de factura electrónica (Factur-X / ZUGFeRD) o flujos de trabajo de firma avanzados como la firma remota, en la nube con KMS y secuencial. Elige Enterprise cuando necesites flujos de trabajo de autoría de archivado PDF/A, los niveles a largo plazo PAdES (B-LT / B-LTA) con un Document Security Store y sellos de tiempo de documento, firma respaldada por hardware mediante un módulo de seguridad de hardware (HSM) o firmas electrónicas cualificadas. Pro y Enterprise son las dos ediciones con licencia de NextPDF Premium, la línea de pago; consulta Elige tu camino.

¿Es realmente Apache-2.0?

Sí, para el núcleo. nextpdf/core declara "license": "Apache-2.0" e incluye el texto completo de la Apache License 2.0 en su archivo LICENSE. Puedes usar, modificar, redistribuir y comercializar el núcleo, sujeto a los requisitos de atribución y NOTICE (Apache-2.0 §4). NextPDF Pro y NextPDF Enterprise son ediciones comerciales propietarias y no están cubiertas por esa licencia. El nombre y el logotipo de NextPDF son marcas comerciales, independientes de la licencia del código. Consulta Licencias.

¿Cuál es la versión mínima de PHP?

PHP 8.4. La restricción del paquete es >=8.4 <9.0, de modo que Composer se niega a instalar en PHP 8.3 o inferior, o en PHP 9. NextPDF apunta a un único entorno de ejecución moderno y usa sus funciones de lenguaje directamente. Consulta Instalar NextPDF.

¿Necesita un binario externo o un navegador headless?

No, no para el motor del núcleo. El motor nativo está implementado en PHP y extensiones estándar de PHP, sin binario de PDF externo y sin navegador headless obligatorio: la API fluida y la canalización de HTML writeHtml() integrada se ejecutan en proceso sin navegador y sin llamadas de red. Un binario de Chrome o Chromium es opcional y solo se necesita para el representador Artisan (writeHtmlChrome()), que instalas por separado como nextpdf/artisan. Los puentes Cloudflare y Gotenberg también son opcionales y recurren a un servicio. Consulta Elige tu camino.

¿Qué extensiones de PHP requiere?

El composer.json del núcleo requiere las extensiones estándar ext-mbstring, ext-zlib, ext-intl, ext-gd, ext-curl y ext-openssl, que son extensiones de PHP comúnmente disponibles; asegúrate de que estén instaladas y habilitadas en tu entorno de ejecución. ext-curl respalda los viajes de ida y vuelta de red opcionales — sellado de tiempo RFC 3161 y obtención de recursos remotos —, de modo que la generación nativa sin conexión no la ejercita, pero Composer la sigue listando como requisito estricto. Las integraciones comprueban las que necesitan durante el arranque y se detienen con un mensaje claro si falta alguna. La lista completa reside en el composer.json del paquete; consulta Instalar NextPDF.

¿Cómo genero mi primer PDF?

Instala el núcleo y luego construye un documento con la API fluida:

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\Document;

$document = Document::createStandalone();
$document->addPage();
$document->setFont('helvetica', 'B', 24);
$document->cell(0, 15, 'Hello, NextPDF!', newLine: true);
$document->save(__DIR__ . '/first.pdf');

Recórrelo paso a paso en Tu primer PDF.

Ediciones y licencias

¿Tiene el Core algún límite de funciones o marca de agua?

No. El Core es el motor de código abierto para el conjunto de funciones del Core sin marca de agua y sin pantalla de recordatorio. Para el conjunto de funciones del Core — generación, inspección, cifrado, primitivas de salida PDF/A y PDF/UA, y firma B-B/B-T por clave de software (sin los flujos de trabajo Premium de validación a largo plazo y custodia de claves) —, el Core está completo. La marca de agua de evaluación se aplica únicamente a una concesión de evaluación Premium, donde pruebas el conjunto completo de funciones de Pro y Enterprise tras una marca eliminable; una licencia de pago la elimina sin ningún cambio en el código de la aplicación. Consulta Licencias y activación.

¿Necesito cambios de código para actualizar a Pro o Enterprise?

En su mayoría, no. Cuando instalas nextpdf/premium, las integraciones de framework y el servidor lo detectan automáticamente y exponen las capacidades adicionales. La mayoría de las aplicaciones mantienen los mismos puntos de integración de alto nivel; algunos flujos de trabajo Premium pueden requerir configuración o llamadas específicas de la función. Activas un sobre de licencia firmado una vez por despliegue. Consulta Licencias y activación.

¿Puedo usar el núcleo en un producto comercial de código cerrado?

Sí. La Apache License 2.0 no tiene ninguna restricción no comercial. Puedes usar el núcleo en productos comerciales de código cerrado, de pago o internos, siempre que respetes las obligaciones de atribución y NOTICE y no trates la licencia del código como permiso para usar la marca NextPDF. Consulta Licencias y Marca registrada y uso de marca.

Capacidades

¿Puede leer y analizar PDF, o solo escribirlos?

Ambas cosas, con una salvedad. NextPDF escribe PDF y también los lee: el módulo Inspect lee un archivo existente en un InspectResult estructurado con datos de complejidad, fuentes, imágenes y riesgo, y puedes combinar y dividir documentos existentes. Inspect está marcado como experimental, así que la forma de su resultado puede cambiar entre versiones menores; úsalo para diagnósticos y compuertas, no como un contrato de larga vida. Consulta el módulo Inspect.

¿Produce texto seleccionable y buscable?

Sí. Tanto la API fluida como la canalización writeHtml() integrada emiten contenido de texto real, no imágenes rasterizadas, de modo que la salida es seleccionable y buscable. El writeHtmlChrome() del representador Artisan también mantiene el texto seleccionable. Consulta Tu primer PDF.

¿Cómo funciona la representación de HTML y CSS?

El motor del núcleo incluye una canalización de HTML en PHP puro. writeHtml() representa un fragmento de HTML con un subconjunto admitido de CSS directamente en la página, sin navegador y sin llamadas de red. Cuando un diseño necesita la fidelidad completa de un navegador — como flexbox, grid o fuentes web —, instala el representador Artisan y llama a writeHtmlChrome(). Antes de depender de una propiedad, consulta la matriz de compatibilidad de CSS.

¿Cómo funcionan las fuentes?

Los alias de fuentes estándar integrados, como Helvetica, funcionan sin configuración para texto WinAnsi sencillo, así que tu primer documento no necesita archivos de fuente. Las fuentes estándar latinas integradas sirven para texto WinAnsi básico; Symbol y ZapfDingbats usan sus propias codificaciones; para representar otros sistemas de escritura, registras e incrustas una fuente cuyo mapa de caracteres y vía de modelado admitan ese sistema de escritura. Consulta la matriz de compatibilidad de fuentes y el módulo Font.

¿Admite PDF/A y accesibilidad (PDF/UA)?

Sí, con un límite claro: admitir un perfil no es conformidad. El núcleo incluye el discriminador de conformidad y las primitivas de etiquetado: enableTaggedPdf() habilita la salida de estructura de PDF etiquetado usada para flujos de trabajo PDF/UA, y enablePdfA() selecciona un perfil de salida PDF/A en el Core; las ediciones Premium añaden flujos de trabajo y herramientas de autoría de archivado de más alto nivel (validación, política y operaciones de producción) por encima. NextPDF emite los artefactos estructurales que requiere un perfil; un validador independiente como veraPDF decide si un archivo dado realmente es conforme. Consulta Conformidad y el módulo Accessibility.

¿Cómo firmo un PDF?

El núcleo puede producir firmas SignedData de la sintaxis de mensajes criptográficos (CMS) y puede aplicar sellos de tiempo RFC 3161 (el nivel B-T), usando algoritmos de clave de software admitidos a través del proveedor de firma configurado. Tu código depende del contrato SignerInterface, así que la misma llamada funciona en todas las ediciones. Los niveles a largo plazo PAdES B-LT y B-LTA, la custodia de claves HSM y PKCS#11, y las firmas cualificadas son capacidades Enterprise; los flujos de trabajo de firma respaldada por la nube y por KMS se incluyen en Pro. El Core produce las estructuras base B-B y B-T. Consulta el módulo Signing.

Producción

¿Es seguro para workers y para hilos?

Un Document es de un solo uso: una vez que has escrito uno, crea una instancia nueva para el siguiente documento en lugar de reutilizarlo. Esto lo hace una opción natural para el modelo por solicitud y por trabajo que usan PHP-FPM, los workers de cola y los frameworks: cada unidad de trabajo construye su propio documento. Cuando analizas o compones entradas no confiables, ejecuta ese trabajo en un worker restringido y mantén ajustadas las salvaguardas de recursos (maxFiles, maxTotalBytes, maxBytes). Consulta el módulo Document y el modelo de amenazas del motor.

¿Es la salida determinista?

Es estructuralmente determinista, pero no idéntica byte a byte de forma predeterminada. Dos ejecuciones de la misma entrada producen PDF estructuralmente iguales, pero cada uno lleva un tráiler nuevo y un /ID de documento nuevo, de modo que los bytes difieren. La firma y los sellos de tiempo añaden por diseño más variación por ejecución. Planifica las comparaciones en torno a la igualdad estructural, o normaliza los campos volátiles, en lugar de esperar bytes idénticos entre ejecuciones.

¿Cómo lo despliego?

Confirma composer.lock para que cada worker desplegado resuelva la misma versión del motor, luego despliégalo como harías con cualquier biblioteca de PHP: la generación nativa no necesita demonio, navegador ni red; el sellado de tiempo (B-T), los recursos remotos o el puente de navegador opcional requieren acceso de red configurado. Si servicios que no son de PHP necesitan el motor, ejecuta NextPDF Server, que lo expone sobre el protocolo de contexto de modelo (MCP), REST y gRPC. Para Premium, coloca el sobre de licencia firmado donde el despliegue lo cargue y ejecuta el paso de activación único; el estado de licencia en caché significa que el procesamiento normal no necesita ningún servicio de licencias, de modo que se admiten despliegues aislados de la red. Consulta Instalar NextPDF y Licencias y activación.

¿A dónde llevo un fallo cuando algo sale mal?

NextPDF informa de los errores por clase de excepción de PHP, no por un código de error de cadena, y las excepciones conscientes del contexto llevan campos de diagnóstico estructurados. La base de conocimientos de resolución de problemas asigna fallos comunes de firma, PDF/A, PDF/UA, fuentes, etiquetado y cifrado a su causa y resolución.