Instalación del Backport Builder de NextPDF

Herramientas de compilación — NO una dependencia de ejecución. El builder se instala en la estación de trabajo de un mantenedor o en un runner de CI. Una aplicación consumidora nunca instala el builder; instala el paquete que produce el builder.

De un vistazo

Dos públicos distintos instalan componentes diferentes:

Un mantenedor u operador de CI clona este repositorio e instala sus dependencias de compilación. Este es el único contexto en el que se instala nextpdf/backport-builder.
Una aplicación consumidora que se ejecuta en un runtime de PHP más antiguo instala el paquete generado nextpdf/backport desde su canal de publicación. La aplicación nunca toca este repositorio.

Esta página cubre ambos casos. Leer la sección que corresponda al rol correspondiente.

Instalación en el host de compilación

Requisitos

Dependencia	Restricción	Fuente de verdad
PHP	`>=8.4 <9.0`	`composer.jsonrequire.php`
Composer	2.6+	Tabla de entornos de `CONTRIBUTING.md`
`rector/rector`	`^2.0`	`composer.jsonrequire-dev`
`phpstan/phpstan`	`^2.1`	`composer.jsonrequire-dev`
`phpunit/phpunit`	`^13.0`	`composer.jsonrequire-dev`

El flujo de integración continua aprovisiona PHP 8.5 tanto para el job de compilación como para el de ejecución en seco. Un host de compilación con cualquier versión de PHP dentro de >=8.4 <9.0 satisface la restricción de Composer. El analizador sintáctico debe aceptar la sintaxis más reciente que use el código fuente. Verificado contra .github/workflows/0-ci.yml.

Pasos

Clonar el repositorio y hacer checkout de la rama correspondiente al destino que se quiere compilar. PHP74 es la rama predeterminada; produce la distribución para PHP 7.4, solo del núcleo. PHP81 produce la distribución para PHP 8.1 con todos los adaptadores.
Ventana de terminal
```
git clone https://github.com/nextpdf-labs/backport.git
cd backport
git checkout PHP74
```
Instalar las dependencias de compilación. No pasar --no-dev: el motor de Rector, PHPStan y PHPUnit residen en require-dev, y la compilación no puede ejecutarse sin ellos.
Ventana de terminal
```
composer install --prefer-dist --no-progress
```
Confirmar que la cadena de herramientas se resuelve. El script analyse ejecuta PHPStan en el nivel 10 sobre rector/rules y scripts. Una ejecución limpia demuestra que el código de compilación en sí es correcto antes de producir cualquier salida.
Ventana de terminal
```
composer analyse
```
Ejecutar las pruebas de fixtures de las reglas. Cada regla personalizada de Rector tiene un conjunto de fixtures que comprueba la transformación exacta before/after.
Ventana de terminal
```
composer test
```

Después del paso 4, el host está listo para compilar. Continuar en /integrations/backport/quickstart/ para las invocaciones de ejecución en seco y de compilación completa.

Estructura de árbol de fuentes esperada

La compilación fusiona varios repositorios de fuentes en un único árbol. El script de fusión espera que estén disponibles como directorios hermanos bajo una única raíz de fuentes y los referencia por nombre. Para el destino PHP 8.1 lee nextpdf (núcleo), nextpdf-Artisan, nextpdf-compat-legacy, nextpdf-Laravel, nextpdf-Symfony, nextpdf-CodeIgniter y nextpdf-Pro cuando se incluye Pro. Para el destino PHP 7.4 lee únicamente nextpdf. Verificado contra scripts/merge-sources.php (MergeSources::__construct()). Proporcionar la raíz de fuentes con --source-dir. Consultar /integrations/backport/configuration/ para la referencia de los flags.

Consumo del paquete producido en el proyecto consumidor

Un proyecto que se ejecuta en un runtime de PHP más antiguo instala la distribución producida, no este builder.

De PHP 8.1 a 8.3

composer require nextpdf/backport

El paquete instalado declara la restricción >=8.1 <8.5 y reemplaza nextpdf/core, nextpdf/artisan, nextpdf/laravel, nextpdf/symfony, nextpdf/codeigniter y nextpdf/compat-legacy. El código de la aplicación sigue importando el espacio de nombres NextPDF\ sin cambios. El paquete carga automáticamente el árbol fusionado mediante el único prefijo PSR-4 NextPDF\ asignado a src/. Un autoloader PSR-4 añade el nombre de clase relativo a un directorio base registrado para el prefijo (PHP-FIG PSR-4). Verificado contra scripts/adjust-composer.php (buildPublicAutoloadMap(), buildReplace()).

De PHP 7.4 a 8.0

composer require nextpdf/backport

La distribución para PHP 7.4 es solo del núcleo. Declara la restricción >=7.4 <8.1 y reemplaza únicamente nextpdf/core. Los adaptadores de frameworks, la capa de compatibilidad con tcpdf y Pro no forman parte de la distribución para PHP 7.4. Verificado contra scripts/adjust-composer.php y scripts/build.php (el destino PHP 7.4 fuerza solo el núcleo). Un proyecto que necesite un adaptador de framework requiere PHP 8.1 o más reciente.

Pro

composer require nextpdf/backport-pro

La distribución Pro es un paquete independiente, nextpdf/backport-pro, bajo licencia proprietary. Requiere nextpdf/backport en la misma major.minor y añade phpseclib/phpseclib ^3.0. Se produce únicamente para el destino PHP 8.1. Verificado contra scripts/adjust-composer.php (generateProComposer()).

La distribución para PHP 7.4 y la distribución Pro son mutuamente excluyentes: no existe una compilación Pro para PHP 7.4 debido al diseño del script de compilación.

Polyfills en el paquete producido

El composer.json generado requiere paquetes symfony/polyfill-* para que las funciones más recientes de la biblioteca estándar puedan resolverse en el runtime de destino. El destino PHP 8.1 requiere polyfills desde PHP 8.2 hasta 8.5. El destino PHP 7.4 requiere además los polyfills de PHP 8.0 y 8.1. Son dependencias de ejecución del paquete producido, no del builder. Verificado contra scripts/adjust-composer.php (generatePublicComposer()).

/integrations/backport/configuration/ — Configuración de Rector, reglas personalizadas y referencia de flags de compilación.
/integrations/backport/quickstart/ — Primera ejecución en seco y compilación completa.