Inicio rápido de NextPDF Backport Builder

Herramienta de compilación, NO dependencia en tiempo de ejecución. Este recorrido se ejecuta en el host de un mantenedor o en integración continua (CI). El archivo producido es lo que consume un proyecto que depende de él. Los pasos aquí descritos nunca se ejecutan en un servidor de aplicaciones.

De un vistazo

Se ejecutan tres acciones. Primero, la simulación, que demuestra que el flujo está conectado sin tocar ningún archivo. A continuación, una compilación completa con PHP 8.1. Por último, una compilación completa con PHP 7.4. Cada paso consiste en un único comando y se apoya en un script de Composer o en una invocación documentada de scripts/build.php.

Requisitos previos

• Un host de compilación con PHP >=8.4 <9.0, con las dependencias de compilación instaladas (composer install, sin --no-dev). Consultar /integrations/backport/install/.
• Los repositorios de código fuente clonados como directorios hermanos bajo una única raíz de código fuente. La compilación con PHP 8.1 lee nextpdf, nextpdf-Artisan, nextpdf-compat-legacy, nextpdf-Laravel, nextpdf-Symfony, nextpdf-CodeIgniter y nextpdf-Pro (para Pro). La compilación con PHP 7.4 lee únicamente nextpdf. Verificado con scripts/merge-sources.php.

Paso 1 — simulación (dry-run)

La simulación ejecuta cada etapa en modo de solo informe. El proceso de fusión enumera lo que copiaría. La etapa de Rector se anuncia, pero no se ejecuta. Las etapas de generación de Composer, copia de recursos y validación imprimen su intención. No se escribe nada. Ejecutarla primero permite confirmar que la disposición de las fuentes y los indicadores son correctos, ya que es la comprobación más rápida.

composer build:dry

composer build:dry equivale a php scripts/build.php --dry-run. Verificado con composer.jsonscripts y scripts/build.php (la rama dryRun de cada etapa). Con los indicadores predeterminados, el destino es php81 y la raíz de código fuente es la predeterminada del script. Es posible anular cualquiera de los dos, como se muestra en el paso 2.

Si la simulación informa que falta un repositorio de fuentes, falla de inmediato e indica el repositorio. Corregir la disposición de las fuentes antes de continuar; consultar /integrations/backport/troubleshooting/.

Paso 2 — compilación completa con PHP 8.1

La compilación con PHP 8.1 ejecuta varios pasos en orden. Fusiona el núcleo con los adaptadores de framework y la capa de compatibilidad con tcpdf. Ejecuta la configuración de Rector en una sola pasada. Genera el nextpdf/backportcomposer.json. Copia la licencia, escribe un CHANGELOG.md y cuenta los archivos PHP emitidos.

php scripts/build.php \
  --version=2.0.0 \
  --source-dir=/path/to/sources \
  --output-dir=./output

Verificado con el punto de entrada de CLI scripts/build.php. Las cinco etapas se ejecutan en orden: fusionar fuentes, ejecutar la degradación de Rector, generar composer.json, copiar los recursos estáticos y validar la salida. Cada etapa imprime una marca de verificación cuando se completa correctamente. La primera etapa que falla detiene la compilación y muestra su error. Para excluir Pro, añadir --no-pro.

Al completarse correctamente, el orquestador imprime el tiempo transcurrido y la ruta de salida. Cuando se incluye Pro, también imprime la ruta de salida de Pro. El directorio de salida contiene src/, tests/, un composer.json generado que declara el mapa replace y los requisitos de polyfill, LICENSE y CHANGELOG.md.

Paso 3 — compilación completa con PHP 7.4

La compilación con PHP 7.4 se limita al núcleo y ejecuta el flujo de dos pasadas. Las pasadas consisten en el preprocesamiento de enumeraciones, una limpieza de caché, los ajustes posteriores a Rector y, después, la degradación completa.

php scripts/build.php \
  --version=2.0.0 \
  --source-dir=/path/to/sources \
  --output-dir=./output-php74 \
  --target=php74

Verificado con scripts/build.php. Aquí, --target=php74 impone el modo de solo núcleo y deshabilita Pro, y runRector() selecciona la ruta de dos pasadas. El composer.json generado incluye la restricción >=7.4 <8.1, reemplaza únicamente nextpdf/core y añade los polyfills de PHP 8.0 y 8.1 además de los polyfills de 8.2 a 8.5.

Paso 4 — leer la salida

La etapa de validación cuenta los archivos PHP en output/src y falla si el recuento es cero. No ejecuta una comprobación de sintaxis localmente, porque el intérprete local corresponde al PHP moderno del host de compilación, no al de destino. Imprime el comando de Docker para validar en el entorno de ejecución de destino real. Verificado con scripts/build.php (validateOutput()).

Para validar por completo, ejecutar la comprobación de sintaxis con el PHP de destino. El flujo de publicación hace exactamente esto. Comprueba la sintaxis de la salida con PHP 8.1 (o PHP 7.4) y, después, la instala y la prueba en toda la matriz de soporte. Consultar /integrations/backport/production-usage/.

Lo que ha compilado

Artefacto	Compilado por	Restricción	Reemplaza
nextpdf/backport (PHP 8.1)	Paso 2	>=8.1 <8.5	core + artisan + laravel + symfony + codeigniter + compat-legacy
nextpdf/backport-pro (PHP 8.1)	Paso 2, cuando se incluye Pro	>=8.1 <8.5	nextpdf/pro
nextpdf/backport (PHP 7.4)	Paso 3	>=7.4 <8.1	nextpdf/core

Verificado con scripts/adjust-composer.php.

Siguiente

• /integrations/backport/production-usage/ — conectar esto al flujo de publicación basado en eventos.
• /integrations/backport/configuration/ — la referencia de reglas e indicadores que hay detrás de estos comandos.
• /integrations/backport/troubleshooting/ — cada fallo de etapa y qué significa.