Referência da API do Backport Builder

Visão geral

O Backport Builder é uma ferramenta de build, não uma biblioteca de runtime. Sua interface pública consiste no conjunto de comandos de build (scripts/build.php e os wrappers composer build*), nas quatro classes de nível de script por trás dessa interface (Build, MergeSources, AdjustComposer, ValidateBuildContract), nos três arquivos de configuração do Rector, nas três regras personalizadas do Rector e no contrato de pacote gerado (nextpdf/backport e nextpdf/backport-pro). Execute-o em um host de build ou de integração contínua (CI) para transformar o código-fonte moderno do NextPDF em uma distribuição rebaixada. Nunca o adicione a uma aplicação.

Se você está começando, use primeiro composer build:dry (que resolve para php scripts/build.php --dry-run). Ele executa cada etapa em modo somente relatório, sem gravar arquivos, para que você possa conferir a organização do código-fonte e as flags antes de um build real. O primeiro exemplo de “Tarefas comuns” mostra o mesmo comando.

Tarefas comuns

Na maioria das vezes, você usará este pacote para executar builds em um host de build. Cada exemplo abaixo é um único comando, conferido com scripts/build.php e composer.json.

Valide o pipeline sem gravar nada (a primeira execução segura):

composer build:dry

O comando resolve para php scripts/build.php --dry-run. Ele executa merge, Rector, geração do composer, cópia de assets e validação em modo somente relatório, sem copiar nada.

Produza a distribuição completa para PHP 8.1 (nextpdf/backport, mais nextpdf/backport-pro quando o código-fonte do Pro está presente):

php scripts/build.php \
  --version=2.0.0 \
  --source-dir=/path/to/sources \
  --output-dir=./output

Isso faz o merge do core, dos adaptadores de framework e da camada de compatibilidade com o tcpdf. Em seguida, executa o passe único do Rector para o alvo PHP 8.1 e grava a árvore do pacote gerado em ./output. Adicione --no-pro para ignorar o pacote Pro.

Produza a distribuição somente do core para PHP 7.4 (o pipeline de enum de dois passes):

php scripts/build.php \
  --version=2.0.0 \
  --source-dir=/path/to/sources \
  --output-dir=./output-php74 \
  --target=php74

--target=php74 força a saída somente do core, desativa o Pro e executa o pré-processamento de enum, os ajustes pós-Rector e o passe completo de rebaixamento para PHP 7.4.

Superfícies de comando

Use esta tabela quando precisar das assinaturas exatas, das flags e do comportamento de saída dos pontos de entrada de build e das classes de nível de script que conduzem o build.

Símbolo	Parâmetros	Comportamento padrão	Retorna	Lança ou falha com	Observações
scripts/build.php	Alvo, versão, caminhos de origem, caminhos de saída e flags conforme documentado pelo script.	Usa os padrões de alvo específicos do branch.	Árvore do pacote gerado.	Saída diferente de zero e saída de erro específica da etapa.	Ponto de entrada principal de build. Execute em um host de build, não em uma aplicação.
Build::__construct(string $version, string $sourceDir, string $outputDir, string $target = 'php81', bool $includePro = true, bool $dryRun = false)	Versão, diretório de origem, diretório de saída, faixa de runtime alvo, flag de inclusão do Pro, flag de dry-run.	Usa PHP 8.1 como alvo, inclui o Pro exceto para PHP 7.4 e grava a menos que o dry-run esteja ativado.	Build	InvalidArgumentException para alvo não suportado; erros de etapa durante run().	Classe de nível de script por trás de scripts/build.php.
Build::run()	nenhum.	Valida o contrato, faz o merge das fontes, ajusta os metadados do composer.json e executa os passes do Rector.	bool	Retorna false para falhas de etapa esperadas; pode lançar para erros inesperados de sistema de arquivos ou runtime.	O CI deve falhar em false.
composer build:dry	Wrapper de script do Composer.	Validação de build em dry-run.	Status de saída e logs.	Saída diferente de zero em caso de falha de build ou de validação.	Usado por gates de CI.
scripts/merge-sources.php	Caminhos de checkout das fontes e alvo do merge.	Faz o merge dos pacotes de origem selecionados para o runtime alvo.	Árvore de fontes mesclada.	Origem ausente, alvo não suportado, falha de sistema de arquivos.	Mantenha as refs de origem alinhadas à tag de release.
MergeSources::__construct(string $sourceBaseDir, string $outputDir, bool $includePro = true, bool $dryRun = false, bool $coreOnly = false)	Diretório base de origem, diretório de saída, flag de inclusão do Pro, flag de dry-run, flag de somente core.	Faz o merge de todos os repositórios configurados, ou somente do core quando coreOnly é true.	MergeSources	Caminhos de origem ou de saída inválidos durante a execução.	Classe de nível de script por trás de scripts/merge-sources.php.
MergeSources::run()	nenhum.	Copia e normaliza as árvores de origem selecionadas para o alvo do build.	bool	Retorna false para falhas de merge esperadas.	Os logs podem ser consultados com getLog().
MergeSources::getLog()	nenhum.	Retorna as entradas de log de etapa acumuladas.	array	nenhum esperado.	Use para diagnósticos de CI.
scripts/adjust-composer.php	Metadados e versão do composer.json gerado.	Grava as restrições de pacote e as entradas de replace para a saída gerada.	O composer.json ajustado.	Versão inválida ou arquivos gerados ausentes.	Define a identidade do pacote gerado.
AdjustComposer::__construct(string $version, string $target = 'php81')	String de versão e faixa de alvo.	Alvo PHP 8.1.	AdjustComposer	Erros de alvo inválido nos caminhos de geração.	Usado por scripts de build e testes.
AdjustComposer::generatePublicComposer()	nenhum.	Produz metadados para nextpdf/backport.	array	nenhum esperado.	API de geração pura para testes.
AdjustComposer::generateProComposer()	nenhum.	Produz metadados para nextpdf/backport-pro.	array	nenhum esperado.	API de geração pura para a faixa de build proprietária.
AdjustComposer::writePublicComposer(string $outputDir)	Diretório de saída.	Grava o composer.json público gerado.	void	Erros de sistema de arquivos.	Use somente em diretórios de saída gerados.
AdjustComposer::writeProComposer(string $proOutputDir)	Diretório de saída do Pro.	Grava o composer.json do Pro gerado.	void	Erros de sistema de arquivos.	Requer que a árvore de saída do Pro exista.
ValidateBuildContract::__construct(string $repoRoot)	Raiz do repositório.	Usa a raiz de repositório fornecida como base do contrato.	ValidateBuildContract	nenhum esperado.	Validador de contrato de nível de script.
ValidateBuildContract::run()	nenhum.	Verifica as entradas obrigatórias e as premissas do build.	bool	Retorna false em caso de falha de contrato.	Execute antes de confiar na saída do build.

Configuração do Rector

Use esta tabela para ver qual arquivo de configuração do Rector conduz cada faixa de alvo e onde cada passe se encaixa no pipeline de passe único do PHP 8.1 ou no pipeline de dois passes do PHP 7.4.

Símbolo	Parâmetros	Comportamento padrão	Retorna	Lança ou falha com	Observações
rector/config/rector-php81.php	Árvore de origem e runtime do Rector.	Rebaixamento de passe único para o alvo PHP 8.1.	Código-fonte transformado.	Falha de análise ou de transformação do Rector.	Usado para a faixa de distribuição do PHP 8.1.
rector/config/rector-php74-enums.php	Árvore de origem e runtime do Rector.	Primeiro passe do PHP 7.4 para conversão de enum.	Código-fonte transformado intermediário.	Falha de análise ou de transformação do Rector.	Executa antes do passe completo do PHP 7.4.
rector/config/rector-php74.php	Código-fonte intermediário e runtime do Rector.	Passe completo de rebaixamento para PHP 7.4.	Código-fonte compatível com PHP 7.4.	Falha de análise ou de transformação do Rector.	Usado para a faixa de distribuição do PHP 7.4.

Regras personalizadas

Use esta tabela quando você mantiver ou estender as três regras do Rector específicas do projeto e precisar do contrato de método de cada regra e da sintaxe que ela transforma.

Símbolo	Parâmetros	Comportamento padrão	Retorna	Lança ou falha com	Observações
DowngradeAsymmetricVisibilityRector	Propriedades ou parâmetros promovidos que usam visibilidade assimétrica.	Visibilidade simples compatível com runtimes mais antigos.	Preserva a visibilidade de leitura onde possível.	Falha de regra do Rector.	As restrições de setter são apenas em tempo de compilação e são removidas na saída gerada.
DowngradeAsymmetricVisibilityRector::getRuleDefinition()	nenhum.	Retorna os metadados e exemplos da regra do Rector.	RuleDefinition	nenhum esperado.	Mantém a documentação da regra visível para as ferramentas do Rector.
DowngradeAsymmetricVisibilityRector::getNodeTypes()	nenhum.	Seleciona os tipos de nó inspecionados pela regra.	array<class-string<Node>>	nenhum esperado.	O escopo deve permanecer restrito para transformações determinísticas.
DowngradeAsymmetricVisibilityRector::refactor(Node $node)	Nó da AST.	Converte a visibilidade assimétrica onde estiver presente.	`Node	null`	Falha de regra do Rector.
DowngradeCloneWithRector	clone() com sobrescritas de propriedade.	Clone mais atribuições explícitas de propriedade.	Usa variáveis temporárias geradas.	Falha de regra do Rector.	Deve ser executada após os rebaixamentos de propriedade readonly.
DowngradeCloneWithRector::getRuleDefinition()	nenhum.	Retorna os metadados e exemplos da regra.	RuleDefinition	nenhum esperado.	Usado pelos diagnósticos do Rector.
DowngradeCloneWithRector::getNodeTypes()	nenhum.	Seleciona os nós de retorno e de expressão.	array<class-string<Node>>	nenhum esperado.	Mantém a regra focada na sintaxe de clone-with.
DowngradeCloneWithRector::refactor(Node $node)	Nó da AST.	Reescreve clone-with em clone mais atribuições.	`array	null`	Falha de regra do Rector.
DowngradeTraitConstantsRector	Constantes de trait e referências a elas.	Propriedades estáticas e referências de propriedade.	Preserva a visibilidade sempre que possível.	Falha de regra do Rector.	Remove final porque propriedades mais antigas não podem ser final.
DowngradeTraitConstantsRector::getRuleDefinition()	nenhum.	Retorna os metadados e exemplos da regra.	RuleDefinition	nenhum esperado.	Usado pelos diagnósticos do Rector.
DowngradeTraitConstantsRector::getNodeTypes()	nenhum.	Seleciona os nós de trait e de class-constant-fetch.	array<class-string<Node>>	nenhum esperado.	Mantém a regra limitada às constantes de trait.
DowngradeTraitConstantsRector::refactor(Node $node)	Nó da AST.	Reescreve as constantes de trait e suas referências como propriedades compatíveis.	`Node	null`	Falha de regra do Rector.

Contrato de pacote gerado

Use esta tabela para ver o que o builder emite: os nomes de pacote que projetos consumidores instalam e o pacote que carrega a distribuição Pro.

Pacote produzido	Papel no runtime	Observações
nextpdf/backport	Distribuição de runtime open-source gerada.	Substitui os pacotes nextpdf/* selecionados para o runtime alvo.
nextpdf/backport-pro	Distribuição Pro proprietária gerada quando o código-fonte do Pro está presente.	Publicado separadamente do pacote open-source.

Notas de desenvolvimento

• O builder consome releases de origem e emite artefatos gerados. Não aplique patches na saída gerada como se ela fosse a fonte da verdade.
• Cada regra personalizada deve ter testes de fixture antes de entrar no pipeline de build.
• Os jobs de release devem validar a saída gerada no runtime alvo, não apenas no host de build.