Solução de problemas do NextPDF Backport Builder

Ferramenta de build — NÃO é uma dependência de runtime. Todo sintoma nesta página é uma condição em tempo de build em um host de mantenedor ou de integração contínua (CI). Nenhuma dessas condições aparece em uma aplicação downstream.

Visão geral

O build executa cinco estágios em ordem. Ele para na primeira falha e exibe o nome do estágio e a mensagem. Leia o nome do estágio e, em seguida, encontre a causa correspondente abaixo. Os estágios são mesclar fontes, executar o downgrade do Rector, gerar composer.json, copiar ativos estáticos e validar a saída. Verificado em relação a scripts/build.php (run() e step()).

Estágio: mesclar fontes

”Source repo '' not found at: ”

A mesclagem valida todos os repositórios de fontes esperados antes de copiar arquivos. Se um repositório estiver ausente, o build é abortado e exibe o nome e o caminho dele. O target do PHP 8.1 espera nextpdf, nextpdf-Artisan, nextpdf-compat-legacy, nextpdf-Laravel, nextpdf-Symfony, nextpdf-CodeIgniter e — quando o Pro está incluído — nextpdf-Pro. O target do PHP 7.4 espera apenas nextpdf. Verificado em relação a scripts/merge-sources.php (loop de validação de run(), mapa de repositórios em __construct()).

Resolução: faça o checkout dos repositórios como diretórios irmãos no caminho passado para --source-dir e use exatamente os nomes de diretório acima. Uma execução de teste (dry run) lista todos os repositórios que seriam lidos. Use-a para confirmar o layout antes de executar um build completo.

Estágio: executar o downgrade do Rector

O Rector sai com código diferente de zero

O orquestrador reporta Rector failed on <label> (exit code: N) e para. O label identifica a passagem que falhou: public package, pro package, enum pre-processing ou full downgrade. Verificado em relação a scripts/build.php (runRectorPass()).

Falha do resolvedor de parâmetros padrão em valores padrão de enum (PHP 7.4)

É por isso que o target do PHP 7.4 usa duas passagens. O resolvedor de valores de parâmetro padrão do Rector falha quando um case de enum é usado como valor padrão em uma promoção de construtor. A Passagem 1 (rector-php74-enums.php) converte primeiro os enums em classes de lista de constantes. Assim, a passagem completa na Passagem 2 nunca encontra um valor padrão de case de enum. Se você ignorar o orquestrador e executar a configuração completa do PHP 7.4 diretamente sobre um código-fonte que contém enums, espere essa falha. Verificado em relação a scripts/build.php (comentário em runRector() e sequência de duas passagens) e rector/config/rector-php74-enums.php.

Scripts de benchmark fazem o Rector falhar

rector-php81.php e rector-php74.php ignoram */tests/Benchmark/*. Esses scripts referenciam bibliotecas externas de Portable Document Format (PDF) que o Rector não consegue resolver, o que faz o resolvedor de parâmetros padrão falhar. Se um caminho de benchmark for processado, o glob de exclusão está ausente ou o caminho é diferente. Verificado em relação às chamadas withSkip().

MHASH_XXH* falha (PHP 7.4)

rector-php74.php ignora DowngradeHashAlgorithmXxHashRector. Essa regra integrada falha nas constantes xxHash. O código-fonte não usa xxHash, portanto a exclusão é segura. Verificado em relação a rector/config/rector-php74.php (withSkip()).

Estágio: correções pós-Rector (somente PHP 7.4)

As correções são executadas entre as duas passagens. Elas reescrevem padrões deixados pela regra de conversão de enum em classe. Se a saída do PHP 7.4 tiver um erro de análise envolvendo EnumClass::Case->value, ->name, um antigo método de enum chamado como método de instância ou um argumento nomeado em um tipo não resolvido, a correção não correspondeu a esse padrão. A limitação do clone-with também se aplica aqui: a correspondência de argumentos não é recursiva, portanto um valor de substituição com parênteses aninhados não é reescrito. Verificado em relação a scripts/build.php (postProcessFixups(), fixEnumMethodCallSites(), applyFixups()) e rector/rules/DowngradeCloneWithRector.php (limitação documentada).

Estágio: gerar composer.json

Este estágio move os diretórios processados src/ e tests/ do diretório build-temp para o diretório de saída. Em seguida, grava o composer.json gerado. Uma falha aqui quase sempre é uma condição do sistema de arquivos: o diretório de saída não permite escrita ou a árvore build-temp está ausente porque o Rector não produziu nada. Verificado em relação a scripts/build.php (adjustComposer(), moveTree()).

Estágio: copiar ativos estáticos

Este estágio copia LICENSE do repositório de fontes do core e grava um CHANGELOG.md gerado. Se LICENSE estiver ausente, a cópia é ignorada silenciosamente e o build continua; o changelog é sempre gravado. Uma falha aqui significa que o diretório de saída deixou de permitir escrita durante o build. Verificado em relação a scripts/build.php (copyStaticAssets()).

Estágio: validar a saída

”Output src/ directory not found” / “No PHP files found in output”

A validação exige um output/src não vazio. Uma árvore vazia significa que a mesclagem não copiou nada ou que a movimentação de arquivos falhou. Verificado em relação a scripts/build.php (validateOutput()).

”Syntax validation: skipped (requires PHP runtime)”

Isso é esperado, não é um erro. O host de build executa um PHP moderno, não o runtime de destino, portanto o estágio local apenas conta os arquivos e exibe o comando do Docker para uma verificação de sintaxe real. O gate de sintaxe oficial é a etapa php -l pós-build no workflow de release, executada no runtime de destino real. Verificado em relação a scripts/build.php (validateOutput()) e .github/workflows/build.yml (as etapas de verificação de sintaxe do PHP 8.1 / PHP 7.4).

Limitações conhecidas

Essas limitações são inerentes à abordagem de downgrade. Elas são verificadas em relação às regras e à seção “Known Limitations” do README.md do projeto:

• As propriedades readonly são removidas. O build remove readonly para que a expansão do clone-with possa atribuir propriedades explicitamente no runtime mais antigo. A saída com downgrade não tem mais imutabilidade imposta em runtime.
• #[Override] não é imposto no PHP 8.1. O atributo pode permanecer, mas o runtime mais antigo não age sobre ele.
• O target do PHP 7.4 é somente core. Os adaptadores de framework, a camada de compatibilidade com tcpdf e o Pro são excluídos da distribuição do PHP 7.4 por construção do script de build.
• O Pro é um pacote separado e somente PHP 8.1. Não há build do Pro para PHP 7.4.
• A correspondência de argumentos do clone-with não é recursiva. Valores de substituição que contêm parênteses aninhados não são transformados, e apenas chaves de array do tipo string são resolvidas em nomes de propriedade.

A seguir

• /integrations/backport/configuration/ — referência de regras e flags.
• /integrations/backport/production-usage/ — gate de CI e faixas de release.