Solución de problemas del compilador de retroportación de NextPDF

Herramientas de compilación: NO una dependencia en tiempo de ejecución. Cada síntoma de esta página describe una condición en tiempo de compilación en un host de mantenimiento o de CI. Ninguna de estas condiciones aparece en una aplicación que consume el paquete.

De un vistazo

La compilación ejecuta cinco etapas en orden. Se detiene en el primer fallo e imprime el nombre de la etapa junto con el mensaje. A partir de la etapa indicada, buscar la causa más abajo. Las etapas son fusionar fuentes, ejecutar la degradación de Rector, generar composer.json, copiar los recursos estáticos y validar la salida. Verificado contra scripts/build.php (run() y step()).

Etapa: fusionar fuentes

«Source repo '' not found at: »

La fusión valida cada repositorio de fuentes esperado antes de copiar. Si falta alguno, aborta con el nombre y la ruta del repositorio. El destino PHP 8.1 espera nextpdf, nextpdf-Artisan, nextpdf-compat-legacy, nextpdf-Laravel, nextpdf-Symfony, nextpdf-CodeIgniter y, cuando se incluye Pro, nextpdf-Pro. El destino PHP 7.4 solo espera nextpdf. Verificado contra scripts/merge-sources.php (bucle de validación de run(), mapa de repositorios de __construct()).

Resolución: extraer los repositorios como directorios hermanos bajo la ruta pasada a --source-dir, con los nombres de directorio exactos indicados arriba. Una ejecución de prueba enumera cada repositorio que leería. Usarla para confirmar la estructura antes de una compilación completa.

Etapa: ejecutar la degradación de Rector

Rector termina con código distinto de cero

El orquestador muestra Rector failed on <label> (exit code: N) y se detiene. La etiqueta indica qué pasada falló: public package, pro package, enum pre-processing o full downgrade. Verificado contra scripts/build.php (runRectorPass()).

Bloqueo del resolvedor de parámetros por defecto con valores por defecto de enumeración (PHP 7.4)

Por este motivo, el destino PHP 7.4 usa dos pasadas. El resolvedor de valores de parámetros por defecto de Rector se bloquea con un caso de enumeración usado como valor por defecto de promoción de constructor. La pasada 1 (rector-php74-enums.php) convierte primero las enumeraciones en clases de lista de constantes. Así, la pasada completa de la pasada 2 nunca llega a ver un valor por defecto de caso de enumeración. Si se omite el orquestador y se ejecuta la configuración completa de PHP 7.4 directamente sobre fuentes que contienen enumeraciones, hay que esperar este bloqueo. Verificado contra scripts/build.php (comentario de runRector() y secuencia de dos pasadas) y rector/config/rector-php74-enums.php.

Los scripts de prueba de rendimiento bloquean Rector

rector-php81.php y rector-php74.php omiten */tests/Benchmark/*. Esos scripts hacen referencia a bibliotecas PDF externas que Rector no puede resolver, lo que bloquea el resolvedor de parámetros por defecto. Si se llega a procesar una ruta de prueba de rendimiento, significa que falta el glob de omisión o que la ruta no coincide. Verificado contra las llamadas a withSkip().

Bloqueo de MHASH_XXH* (PHP 7.4)

rector-php74.php omite DowngradeHashAlgorithmXxHashRector. Esa regla integrada se bloquea con las constantes de xxHash. El código fuente no usa xxHash, por lo que la omisión es segura. Verificado contra rector/config/rector-php74.php (withSkip()).

Etapa: correcciones posteriores a Rector (solo PHP 7.4)

Las correcciones se ejecutan entre las dos pasadas. Reescriben patrones que la regla de enumeración a clase deja atrás. Si la salida de PHP 7.4 presenta un error de análisis relacionado con EnumClass::Case->value, ->name, un antiguo método de enumeración llamado como método de instancia o un argumento con nombre sobre un tipo no resuelto, la corrección no coincidió con ese patrón. La limitación de clone-with también se aplica aquí: la coincidencia de argumentos no es recursiva, por lo que un valor de sustitución con paréntesis anidados no se reescribe. Verificado contra scripts/build.php (postProcessFixups(), fixEnumMethodCallSites(), applyFixups()) y rector/rules/DowngradeCloneWithRector.php (limitación documentada).

Etapa: generar composer.json

Esta etapa mueve los src/ y tests/ procesados desde el directorio temporal de compilación al directorio de salida. Luego escribe el composer.json generado. Un fallo aquí casi siempre se debe a una condición del sistema de archivos: el directorio de salida no permite escritura, o falta el árbol temporal de compilación porque Rector no produjo nada. Verificado contra scripts/build.php (adjustComposer(), moveTree()).

Etapa: copiar los recursos estáticos

Esta etapa copia LICENSE desde el repositorio de fuentes del núcleo y escribe un CHANGELOG.md generado. Cuando la licencia no existe, la copia se omite en silencio y la compilación continúa; el registro de cambios siempre se escribe. Un fallo aquí indica que el directorio de salida dejó de permitir escritura a mitad de la compilación. Verificado contra scripts/build.php (copyStaticAssets()).

Etapa: validar la salida

«Output src/ directory not found» / «No PHP files found in output»

La validación requiere un output/src no vacío. Un árbol vacío indica que la fusión no copió nada, o que el movimiento de archivos falló. Verificado contra scripts/build.php (validateOutput()).

«Syntax validation: skipped (requires PHP runtime)»

Esto es lo esperado, no un error. El host de compilación ejecuta un PHP moderno, no el de destino, por lo que la etapa local solo cuenta archivos e imprime el comando de Docker para una comprobación de sintaxis real. La comprobación de sintaxis autoritativa es el paso posterior a la compilación php -l en el flujo de trabajo de publicación, ejecutado bajo el tiempo de ejecución de destino real. Verificado contra scripts/build.php (validateOutput()) y .github/workflows/build.yml (los pasos de comprobación de sintaxis de PHP 8.1 / PHP 7.4).

Limitaciones conocidas

Son inherentes al enfoque de degradación. Están verificadas contra las reglas y la sección «Known Limitations» del README.md del proyecto:

• Las propiedades readonly se eliminan. readonly se elimina para que la asignación explícita de propiedades de la expansión de clone-with sea válida en el tiempo de ejecución anterior. La inmutabilidad ya no se aplica en tiempo de ejecución en la salida degradada.
• #[Override] no se aplica en PHP 8.1. El atributo puede permanecer, pero el tiempo de ejecución anterior no actúa sobre él.
• El destino PHP 7.4 es solo del núcleo. Los adaptadores de framework, la capa de compatibilidad con tcpdf y Pro no forman parte de la distribución de PHP 7.4, por cómo está construido el script de compilación.
• Pro es un paquete independiente y solo para PHP 8.1. No existe una compilación de Pro para PHP 7.4.
• La coincidencia de argumentos de clone-with no es recursiva. Los valores de sustitución que contienen paréntesis anidados no se transforman y solo las claves de array de tipo cadena se resuelven en nombres de propiedades.

Siguiente

• /integrations/backport/configuration/ — referencia de reglas y opciones.
• /integrations/backport/production-usage/ — la puerta de CI y los canales de publicación.