Referencia de la API de Backport Builder
De un vistazo
Sección titulada «De un vistazo»Backport Builder es una herramienta de compilación, no una biblioteca de tiempo de ejecución. Su interfaz pública está formada por el conjunto de comandos de compilación (scripts/build.php y sus envoltorios composer build*), las cuatro clases de nivel de script que lo respaldan (Build, MergeSources, AdjustComposer, ValidateBuildContract), los tres archivos de configuración de Rector, las tres reglas personalizadas de Rector y el contrato del paquete generado (nextpdf/backport y nextpdf/backport-pro). Se ejecuta en un host de compilación o de CI para convertir el código moderno de NextPDF en una distribución degradada. No debe agregarse nunca a una aplicación.
Punto de partida: con poca experiencia, conviene ejecutar composer build:dry (que se resuelve a php scripts/build.php --dry-run). Este comando ejercita cada etapa en modo de solo informe sin escribir archivos, para confirmar la disposición del código fuente y las opciones antes de una compilación real. El primer ejemplo de «Tareas habituales» que aparece más abajo lo muestra exactamente.
Tareas habituales
Sección titulada «Tareas habituales»La operación más frecuente con este paquete es ejecutar invocaciones de compilación en un host de compilación. Cada ejemplo siguiente es un único comando, verificado contra el código fuente de scripts/build.php y composer.json.
Validar la canalización sin escribir nada (la primera ejecución segura):
composer build:drySe resuelve a php scripts/build.php --dry-run: ejecuta la fusión, Rector, la generación de composer, la copia de activos y la validación en modo de solo informe, sin copiar nada.
Producir la distribución completa para PHP 8.1 (nextpdf/backport, más nextpdf/backport-pro cuando el código fuente de Pro está presente):
php scripts/build.php \ --version=2.0.0 \ --source-dir=/path/to/sources \ --output-dir=./outputEl comando fusiona el núcleo, los adaptadores de framework y la capa de compatibilidad con tcpdf, ejecuta la pasada única de Rector para el destino PHP 8.1 y escribe el árbol del paquete generado en ./output. Agregar --no-pro omite el paquete Pro.
Producir la distribución solo del núcleo para PHP 7.4 (la canalización de enums de dos pasadas):
php scripts/build.php \ --version=2.0.0 \ --source-dir=/path/to/sources \ --output-dir=./output-php74 \ --target=php74--target=php74 fuerza la salida solo del núcleo y desactiva Pro; después ejecuta el preprocesamiento de enums, las correcciones posteriores a Rector y la pasada completa de degradación a PHP 7.4.
Superficies de comandos
Sección titulada «Superficies de comandos»Usar esta tabla cuando se necesite la firma exacta, las opciones y el comportamiento de salida de los puntos de entrada de compilación y de las clases de nivel de script que impulsan una compilación.
| Símbolo | Parámetros | Comportamiento predeterminado | Devuelve | Lanza o falla con | Notas |
|---|---|---|---|---|---|
scripts/build.php | Destino, versión, rutas de origen, rutas de salida y opciones según lo documentado por el script. | Usa los destinos predeterminados específicos de cada rama. | Árbol del paquete generado. | Salida distinta de cero y mensajes de error específicos de cada etapa. | Punto de entrada principal de compilación. Ejecutarlo en un host de compilación, no en una aplicación. |
Build::__construct(string $version, string $sourceDir, string $outputDir, string $target = 'php81', bool $includePro = true, bool $dryRun = false) | Versión, directorio de origen, directorio de salida, carril de tiempo de ejecución de destino, opción de inclusión de Pro y opción de ejecución en seco. | Destino PHP 8.1, con Pro incluido excepto para PHP 7.4; escribe a menos que la ejecución en seco esté habilitada. | Build | InvalidArgumentException para un destino no admitido; errores de etapa durante run(). | Clase de nivel de script que respalda scripts/build.php. |
Build::run() | ninguno. | Valida el contrato, fusiona el código fuente, ajusta los metadatos de composer.json y ejecuta las pasadas de Rector. | bool | Devuelve false para fallos de etapa esperados; puede lanzar excepciones ante errores inesperados de filesystem/runtime. | CI debe fallar si recibe false. |
composer build:dry | Envoltorio de script de Composer. | Validación de compilación en seco. | Estado de salida y registros. | Salida distinta de cero si la compilación o la validación fallan. | Usado en las compuertas de CI. |
scripts/merge-sources.php | Rutas de extracción del código fuente y destino de la fusión. | Fusiona los paquetes de origen seleccionados para el tiempo de ejecución de destino. | Árbol de código fuente fusionado. | Código fuente ausente, destino no admitido o fallo del sistema de archivos. | Mantener las referencias de origen alineadas con la etiqueta de versión. |
MergeSources::__construct(string $sourceBaseDir, string $outputDir, bool $includePro = true, bool $dryRun = false, bool $coreOnly = false) | Directorio base de origen, directorio de salida, opción de inclusión de Pro, opción de ejecución en seco y opción de solo núcleo. | Fusiona todos los repositorios configurados, o solo el núcleo cuando coreOnly es verdadero. | MergeSources | Rutas de origen o de salida no válidas durante la ejecución. | Clase de nivel de script que respalda scripts/merge-sources.php. |
MergeSources::run() | ninguno. | Copia y normaliza los árboles de código fuente seleccionados en el destino de compilación. | bool | Devuelve false para fallos de fusión esperados. | Los registros pueden leerse con getLog(). |
MergeSources::getLog() | ninguno. | Devuelve las entradas de registro de etapa acumuladas. | array | ninguno esperado. | Úsalo para diagnósticos de CI. |
scripts/adjust-composer.php | Metadatos y versión de composer.json generados. | Escribe las restricciones de paquete y las entradas replace para la salida generada. | Se ajusta composer.json. | Versión no válida o archivos generados ausentes. | Responsable de la identidad del paquete generado. |
AdjustComposer::__construct(string $version, string $target = 'php81') | Cadena de versión y carril de destino. | Destino PHP 8.1. | AdjustComposer | Errores por destino no válido en las rutas de generación. | Usado por los scripts de compilación y las pruebas. |
AdjustComposer::generatePublicComposer() | ninguno. | Produce los metadatos para nextpdf/backport. | array | ninguno esperado. | API de generación pura para pruebas. |
AdjustComposer::generateProComposer() | ninguno. | Produce los metadatos para nextpdf/backport-pro. | array | ninguno esperado. | API de generación pura para el carril de compilación propietario. |
AdjustComposer::writePublicComposer(string $outputDir) | Directorio de salida. | Escribe el composer.json público generado. | void | Errores del sistema de archivos. | Úsalo solo en directorios de salida generados. |
AdjustComposer::writeProComposer(string $proOutputDir) | Directorio de salida de Pro. | Escribe el composer.json de Pro generado. | void | Errores del sistema de archivos. | Requiere que el árbol de salida de Pro exista. |
ValidateBuildContract::__construct(string $repoRoot) | Raíz del repositorio. | Usa la raíz del repositorio proporcionada como base del contrato. | ValidateBuildContract | ninguno esperado. | Validador de contrato de nivel de script. |
ValidateBuildContract::run() | ninguno. | Comprueba las entradas requeridas y las suposiciones de compilación. | bool | Devuelve false ante un fallo de contrato. | Ejecútalo antes de confiar en la salida de compilación. |
Configuración de Rector
Sección titulada «Configuración de Rector»Usar esta tabla cuando se necesite saber qué archivo de configuración de Rector impulsa cada carril de destino y dónde encaja cada pasada en la canalización de pasada única de PHP 8.1 o de dos pasadas de PHP 7.4.
| Símbolo | Parámetros | Comportamiento predeterminado | Devuelve | Lanza o falla con | Notas |
|---|---|---|---|---|---|
rector/config/rector-php81.php | Árbol de código fuente y tiempo de ejecución de Rector. | Degradación en una sola pasada al destino PHP 8.1. | Código fuente transformado. | Error de análisis o de transformación de Rector. | Se usa para el carril de distribución de PHP 8.1. |
rector/config/rector-php74-enums.php | Árbol de código fuente y tiempo de ejecución de Rector. | Primera pasada de PHP 7.4 para la conversión de enums. | Código fuente transformado intermedio. | Error de análisis o de transformación de Rector. | Se ejecuta antes de la pasada completa de PHP 7.4. |
rector/config/rector-php74.php | Código fuente intermedio y tiempo de ejecución de Rector. | Pasada completa de degradación a PHP 7.4. | Código fuente compatible con PHP 7.4. | Error de análisis o de transformación de Rector. | Se usa para el carril de distribución de PHP 7.4. |
Reglas personalizadas
Sección titulada «Reglas personalizadas»Usar esta tabla al mantener o ampliar las tres reglas de Rector específicas del proyecto y cuando se necesite el contrato de métodos de cada regla y la sintaxis que transforma.
| Símbolo | Parámetros | Comportamiento predeterminado | Devuelve | Lanza o falla con | Notas |
|---|---|---|---|---|---|
DowngradeAsymmetricVisibilityRector | Propiedades o parámetros promovidos que usan visibilidad asimétrica. | Visibilidad simple compatible con tiempos de ejecución más antiguos. | Conserva la visibilidad de lectura donde es posible. | Error de la regla de Rector. | Las restricciones del definidor existen solo en tiempo de compilación y se eliminan en la salida generada. |
DowngradeAsymmetricVisibilityRector::getRuleDefinition() | ninguno. | Devuelve los metadatos de la regla de Rector y ejemplos. | RuleDefinition | ninguno esperado. | Mantiene visible la documentación de la regla para las herramientas de Rector. |
DowngradeAsymmetricVisibilityRector::getNodeTypes() | ninguno. | Selecciona los tipos de nodo que la regla inspecciona. | array<class-string<Node>> | ninguno esperado. | El alcance debe mantenerse acotado para lograr transformaciones deterministas. |
DowngradeAsymmetricVisibilityRector::refactor(Node $node) | Nodo del AST. | Convierte la visibilidad asimétrica donde está presente. | `Node | null` | Error de la regla de Rector. |
DowngradeCloneWithRector | clone() con sobrescrituras de propiedades. | Clonación más asignaciones explícitas de propiedades. | Usa variables temporales generadas. | Error de la regla de Rector. | Debe ejecutarse después de las degradaciones de propiedades readonly. |
DowngradeCloneWithRector::getRuleDefinition() | ninguno. | Devuelve los metadatos de la regla y ejemplos. | RuleDefinition | ninguno esperado. | Usado por los diagnósticos de Rector. |
DowngradeCloneWithRector::getNodeTypes() | ninguno. | Selecciona los nodos de retorno y de expresión. | array<class-string<Node>> | ninguno esperado. | Mantiene la regla centrada en la sintaxis clone-with. |
DowngradeCloneWithRector::refactor(Node $node) | Nodo del AST. | Reescribe clone-with como clonación más asignaciones. | `array | null` | Error de la regla de Rector. |
DowngradeTraitConstantsRector | Constantes de trait y referencias a ellas. | Propiedades estáticas y referencias a propiedades. | Conserva la visibilidad donde es posible. | Error de la regla de Rector. | Elimina final porque las propiedades más antiguas no pueden ser final. |
DowngradeTraitConstantsRector::getRuleDefinition() | ninguno. | Devuelve los metadatos de la regla y ejemplos. | RuleDefinition | ninguno esperado. | Usado por los diagnósticos de Rector. |
DowngradeTraitConstantsRector::getNodeTypes() | ninguno. | Selecciona los nodos de trait y de obtención de constante de clase. | array<class-string<Node>> | ninguno esperado. | Mantiene la regla limitada a las constantes de trait. |
DowngradeTraitConstantsRector::refactor(Node $node) | Nodo del AST. | Reescribe las constantes de trait y sus referencias en propiedades compatibles. | `Node | null` | Error de la regla de Rector. |
Contrato de paquete generado
Sección titulada «Contrato de paquete generado»Usar esta tabla para ver lo que emite el builder: los nombres de paquete que un proyecto descendente instala en realidad y cuál contiene la distribución de Pro.
| Paquete producido | Rol en tiempo de ejecución | Notas |
|---|---|---|
nextpdf/backport | Distribución de tiempo de ejecución de código abierto generada. | Reemplaza los paquetes nextpdf/* seleccionados para el tiempo de ejecución de destino. |
nextpdf/backport-pro | Distribución propietaria de Pro generada cuando el código fuente de Pro está presente. | Se publica por separado del paquete de código abierto. |
Notas de desarrollo
Sección titulada «Notas de desarrollo»- El builder consume las versiones de origen y emite artefactos generados. No parchear la salida generada como si fuera la fuente de verdad.
- Cada regla personalizada debe tener pruebas de fixtures antes de entrar en la canalización de compilación.
- Los trabajos de versión deben validar la salida generada en el tiempo de ejecución de destino, no solo en el host de compilación.