Descripción general del Backport Builder de NextPDF
Herramienta de compilación: NO es una dependencia en tiempo de ejecución. Los mantenedores de NextPDF usan este paquete para generar distribuciones de NextPDF compatibles con PHP 8.1+ y PHP 7.4+. Las aplicaciones no deben añadir nunca este paquete como dependencia en tiempo de ejecución.
En resumen
Sección titulada «En resumen»El Backport Builder de NextPDF es la infraestructura de compilación que produce una distribución retroportada del ecosistema NextPDF para entornos de ejecución de PHP anteriores a la línea base de desarrollo. NextPDF está escrito para una versión moderna de PHP y usa sintaxis que los intérpretes anteriores rechazan. El builder procesa el código fuente con Rector, un motor de transformación de árboles de sintaxis abstracta, y genera paquetes con sintaxis aceptada por entornos de ejecución de PHP 8.1 o PHP 7.4.
El nombre del paquete en Composer es nextpdf/backport-builder. Declara "type": "project" y no incluye ninguna dependencia de NextPDF en tiempo de ejecución. Sus únicos requisitos son el motor de compilación (rector/rector), el análisis estático (phpstan/phpstan), el ejecutor de pruebas (phpunit/phpunit) y un conjunto de paquetes symfony/polyfill-* usados en la salida generada. Esto se verifica contra composer.json en la raíz del repositorio.
Lo que este paquete no es
Sección titulada «Lo que este paquete no es»Este repositorio no contiene el motor de NextPDF. Contiene las reglas y los scripts que transforman ese motor en una forma retroportada. De ahí se derivan tres separaciones:
- No instale esto para renderizar PDF. El artefacto que debe instalar es
nextpdf/backport, producido por este builder. El builder permanece en el host del mantenedor o de CI. - No desarrolle sobre el código generado. La distribución generada es un artefacto de solo lectura producido por una máquina. Envíe los informes de errores y las solicitudes de funcionalidades a los repositorios de origen
nextpdf/*originales. - La salida se distribuye como etiquetas de versión, no como ramas de este repositorio. La canalización de publicación etiqueta el árbol generado y adjunta los archivos a una publicación de GitHub.
Qué produce
Sección titulada «Qué produce»El builder genera paquetes de Composer con los nombres y las licencias que fija scripts/adjust-composer.php:
| Paquete producido | Licencia | Alcance | Se compila cuando |
|---|---|---|---|
nextpdf/backport | Apache-2.0 | Core, junto con los adaptadores de frameworks y la capa de compatibilidad con tcpdf para el destino PHP 8.1 | Siempre |
nextpdf/backport-pro | proprietary | El módulo Pro, emitido como un paquete independiente | Destino PHP 8.1, cuando el código fuente de Pro está presente y Pro no se excluye |
El paquete nextpdf/backport declara entradas replace de Composer para que, una vez instalado, satisfaga las restricciones de los paquetes originales. Para el destino PHP 8.1, los paquetes reemplazados son nextpdf/core, nextpdf/artisan, nextpdf/laravel, nextpdf/symfony, nextpdf/codeigniter y nextpdf/compat-legacy. Para el destino PHP 7.4 solo se reemplaza nextpdf/core, porque la compilación para PHP 7.4 incluye solo core. Esto se verifica contra scripts/adjust-composer.php (buildReplace()).
El autocargador del consumidor resuelve el árbol fusionado mediante un único prefijo PSR-4, NextPDF\ asignado a src/. PSR-4 asigna un prefijo de espacio de nombres a un directorio base y resuelve cada nombre de clase totalmente cualificado a un archivo ubicado debajo de ese directorio; véase PHP-FIG PSR-4. El paquete Pro asigna NextPDF\Pro\ a su propio src/.
Matriz de versiones de PHP compatibles
Sección titulada «Matriz de versiones de PHP compatibles»La siguiente matriz indica únicamente lo que imponen las configuraciones de Rector y los scripts de compilación. El host de compilación siempre se ejecuta con una versión moderna de PHP. La salida apunta a una versión anterior.
| Aspecto | Valor | Evidencia |
|---|---|---|
| PHP del host de compilación | >=8.4 <9.0 | composer.jsonrequire.php |
| PHP de build/test de CI | 8.5 | .github/workflows/0-ci.yml, build.yml (shivammathur/setup-phpphp-version: '8.5') |
| Restricción de salida del destino PHP 8.1 | >=8.1 <8.5 | scripts/adjust-composer.php (generatePublicComposer()) |
| Restricción de salida del destino PHP 7.4 | >=7.4 <8.1 | scripts/adjust-composer.php (generatePublicComposer()) |
| Alcance del destino PHP 8.1 | Core + Artisan + Laravel + Symfony + CodeIgniter + compat-legacy (+ Pro, por separado) | scripts/merge-sources.php, scripts/adjust-composer.php |
| Alcance del destino PHP 7.4 | Solo core | scripts/build.php (--target=php74 fuerza solo core, Pro deshabilitado) |
La compilación para PHP 8.1 se valida en PHP 8.1, 8.2, 8.3 y 8.4. La compilación para PHP 7.4 se valida en PHP 7.4 y 8.0. Esto se verifica contra las matrices de trabajos validate-php81 y validate-php74 de .github/workflows/build.yml. Estos son los entornos de ejecución que ejercita la canalización. Constituyen un conjunto de validación observado, no una declaración de conformidad.
El modelo de doble rama
Sección titulada «El modelo de doble rama»Este repositorio no tiene rama main. PHP74 es la rama predeterminada y PHP81 es la segunda rama permanente. La rama en la que se trabaja determina dos cosas: el destino predeterminado de la compilación local y el conjunto de código fuente que se fusiona. Un cambio que afecta a ambos destinos se aplica a cada rama mediante su propia solicitud de incorporación de cambios. El flujo de trabajo de integración continua se ejecuta tanto en PHP74 como en PHP81. Esto se verifica contra git branch -a y .github/workflows/0-ci.yml (branches: [PHP74, PHP81]).
Cómo se produce una publicación
Sección titulada «Cómo se produce una publicación»La ruta de publicación está impulsada por eventos. Cuando la organización de origen de NextPDF publica una etiqueta de versión, un evento repository-dispatch de tipo source-release activa el flujo de trabajo de compilación. El flujo de trabajo extrae cada repositorio de origen en la etiqueta correspondiente, ejecuta la canalización, comprueba la sintaxis de la salida en el entorno de ejecución de destino, la valida en toda la matriz de compatibilidad y adjunta los archivos a una publicación de GitHub. La etiqueta de versión sigue el versionado semántico: un número de versión es MAJOR.MINOR.PATCH sobre una API pública declarada (Semantic Versioning 2.0.0 §2). Esto se verifica contra .github/workflows/build.yml.
Adónde ir a continuación
Sección titulada «Adónde ir a continuación»- /integrations/backport/install/ — cómo obtener el builder en un host de compilación y cómo un consumidor instala el paquete producido.
- /integrations/backport/configuration/ — las configuraciones de Rector, las reglas personalizadas y los indicadores de compilación.
- /integrations/backport/quickstart/ — una invocación ejecutable de simulación y de compilación completa, respaldada por el código fuente.
- /integrations/backport/production-usage/ — cómo integrar el builder en un flujo de trabajo de publicación.
- /integrations/backport/troubleshooting/ — los modos de fallo frente a los que se protege la canalización y cómo interpretarlos.
- /integrations/backport/security-and-operations/ — la postura ante la cadena de suministro, el límite de confianza y las garantías operativas.
- /integrations/backport/boot-and-discovery/ — cómo el builder descubre los módulos de origen y se inicia.
- /integrations/backport/integration/ — el contrato de integración del host de compilación.