Guías de migración

Las recipes y las guías aparecen aquí a medida que los repositorios upstream las publican. Esta página es un índice de enrutamiento para el contenido creado en los repositorios de origen (nextpdf, nextpdf-Laravel, nextpdf-Symfony y los demás paquetes del ecosistema). Para la documentación disponible hoy, consulta Insider_ (35 artículos, los 17 idiomas) o Elegir una integración.

Guías de migración

NextPDF es un motor PDF 2.0 para PHP. Si ya se generan PDF con otra biblioteca, una guía de migración mapea la API de esa biblioteca a NextPDF y documenta las diferencias de comportamiento que aparecerán. Esta página es el índice multirrepositorio: registra desde qué biblioteca migra cada guía, qué repositorio es propietario de cada una y el único modelo que todas comparten.

Al ser un índice, esta página no hace ninguna afirmación de comportamiento sobre ninguna guía. Cada guía pertenece a su propio repositorio. El aggregator la incorpora a este sitio y, hasta que una guía aparece, el enlace correspondiente apunta a un marcador de posición. Cada afirmación de comportamiento vive en la propia guía, respaldada por una prueba interna del repositorio o por una cláusula fijada de ISO 32000-2 / CSS WG, no aquí.

El único modelo de migración

Cada guía de migración de NextPDF comparte un único modelo honesto, y conviene leerlas teniéndolo presente:

• Compatible con, no idéntico byte a byte. NextPDF y la biblioteca que se deja atrás son implementaciones independientes. Un documento migrado es funcionalmente equivalente en su propósito, no idéntico píxel a píxel ni byte a byte. Ninguna de las guías afirma ser un reemplazo directo ni ofrecer una compatibilidad del 100 %.
• La cobertura es un recuento medido, no una afirmación general. Cuando una guía indica una cifra de cobertura (por ejemplo, el adaptador de TCPDF), esa cifra es una métrica de completitud funcional extraída de una matriz interna del repositorio, en el sentido de la cláusula 43 de ISO/IEC 25023: un recuento medido de métodos cubiertos, no una garantía general.
• Cada guía expone sus diferencias de comportamiento de forma abierta. Cada guía incluye una tabla de diferencias explícita y una sección de «sin compatibilidad / sin equivalente directo». Una diferencia es una propiedad documentada del motor, no un defecto.
• Un cambio de renderer exige una nueva revisión. Migrar implica un cambio de código y una nueva línea base de la salida. Cada guía describe cómo probar la migración; la aceptación visual se realiza por documento y es responsabilidad de quien integra.

Las formas de migración

Las guías se dividen en dos formas. La forma indica cuánto código cambia.

• Las migraciones con reescritura de la API no tienen ningún shim de compatibilidad: cada punto de llamada se reescribe usando el mapeo de verbos y el mapa de opciones de la guía. Las migraciones desde bibliotecas de HTML a PDF (dompdf, mpdf) tienen esta forma: apuntan directamente al pipeline Html de NextPDF.
• Las migraciones de adopción directa y migración posterior proporcionan un adaptador casi compatible con el código fuente, por lo que el paso inicial es un cambio mínimo de dependencia. A partir de ahí, los puntos de llamada se migran a la API moderna de forma incremental y luego se retira el adaptador. La migración de TCPDF tiene esta forma, mediante el adaptador nextpdf/compat-legacy.

Referencia de guías y repositorios propietarios

Cada guía de abajo vive en el docs/public/ del repositorio propietario, y el aggregator la incorpora a este sitio. El repositorio propietario es la autoridad sobre las afirmaciones de comportamiento de esa guía; este índice solo registra el enrutamiento.

Desde	Guía	Forma	Repositorio propietario	Página
Dompdf	Dompdf → pipeline Html de NextPDF	Reescritura de la API	nextpdf (núcleo)	Guía de Dompdf dompdf (planificada upstream)
mPDF	mPDF → núcleo de NextPDF	Reescritura de la API	nextpdf (núcleo)	Guía de mPDF mpdf (planificada upstream)
TCPDF 6.x	TCPDF → NextPDF mediante el adaptador compat-legacy	Adopción directa y migración posterior	nextpdf-compat-tcpdf repositorio, paquete nextpdf/compat-legacy	Guía de TCPDF tcpdf-compat (planificada upstream)

Las guías de dompdf y mpdf residen en el repositorio del núcleo porque apuntan a las API del motor del núcleo, y los examples/ del núcleo las respaldan. La guía tcpdf-compat vive en el repositorio compat-tcpdf porque el paquete nextpdf/compat-legacy posee la superficie de comportamiento de TCPDF y las pruebas del adaptador que respaldan la guía. Este índice reside de forma nativa en docs porque abarca varios repositorios, y no hace ninguna afirmación de comportamiento sobre ninguno de ellos.

Para qué sirve cada guía

• Dompdf → NextPDF (dompdf (planificada upstream)): para bases de código que usan dompdf/dompdf del lado del servidor. Asigna loadHtml/render/output y las claves de Options al pipeline Html de NextPDF, y remite las expectativas de funciones CSS a la matriz de compatibilidad CSS solo-verificada. No hay ningún shim de la clase Dompdf; cada punto de llamada se reescribe.
• mPDF → NextPDF (mpdf (planificada upstream)): para bases de código que usan mpdf/mpdf. Asigna WriteHTML/Output/AddPage y el array de configuración del constructor a la API del núcleo, con una diferencia en el manejo de fuentes: NextPDF resuelve a través de un único directorio de fuentes junto con la coincidencia CSS y siempre genera subconjuntos. No hay shim de la clase Mpdf.
• TCPDF → NextPDF (compat-legacy) (tcpdf-compat (planificada upstream)): para bases de código de TCPDF 6.x que quieren el cambio inicial más pequeño. El flujo consiste en instalar el adaptador, auditar la superficie real con el modo estricto frente a la matriz de cobertura interna del repositorio, migrar los puntos de llamada fuera del adaptador y luego añadir una estructura etiquetada PDF/UA-2 sobre esa base: una capacidad que TCPDF nunca tuvo. El adaptador es un andamiaje, no el destino, y no una garantía de adopción directa.

Cómo se resuelven los enlaces de las guías

Cada marcador de posición [[…]] de arriba es una referencia hacia adelante a una página que vive en el repositorio propietario, en docs/public/migration/, y el aggregator incorpora esa página a este sitio. Los slugs de destino siguen una única convención:

/migration/<source>/

El token <source> es el nombre corto de la biblioteca desde la que se migra: uno de dompdf, mpdf o tcpdf-compat, según se enumera en la tabla de referencia de guías de arriba. Hasta que una página de destino se agregue, su enlace es un marcador de posición y no se resuelve. Este índice no hace ninguna afirmación de comportamiento sobre ninguna guía de destino; solo registra el enrutamiento y el modelo de migración compartido.

Consulta también

• Matriz de compatibilidad CSS: la autoridad solo-verificada a la que las guías de dompdf y mpdf remiten las expectativas de funciones CSS.
• Cookbook de integración: el índice multirrepositorio de los paquetes de integración del ecosistema (una preocupación diferente: conectar el motor, no migrar hacia él).