Guia rápido do Backport Builder do NextPDF

Ferramenta de build — não é uma dependência de runtime. Execute este passo a passo em um host de mantenedor ou de integração contínua (CI). Um projeto downstream consome o arquivo que você produz. Estas etapas nunca são executadas em um servidor de aplicação.

Visão geral

Você executa três comandos. Primeiro, rode a simulação (dry-run) para confirmar que o pipeline está conectado sem tocar em nenhum arquivo. Em seguida, execute um build completo para PHP 8.1. Depois, execute um build completo para PHP 7.4. Cada etapa usa um comando, apoiado por um script do Composer ou por uma invocação documentada de scripts/build.php.

Pré-requisitos

• Um host de build com PHP >=8.4 <9.0, com as dependências de build instaladas (composer install, sem --no-dev). Consulte /integrations/backport/install/.
• Os repositórios de origem clonados como diretórios irmãos em uma única raiz de código-fonte. O build para PHP 8.1 lê nextpdf, nextpdf-Artisan, nextpdf-compat-legacy, nextpdf-Laravel, nextpdf-Symfony, nextpdf-CodeIgniter e nextpdf-Pro (para o Pro). O build para PHP 7.4 lê apenas nextpdf. Verificado em relação a scripts/merge-sources.php.

Etapa 1 — simulação (dry-run)

A simulação (dry-run) executa todos os estágios em modo somente relatório. O estágio de mesclagem lista os arquivos que copiaria. O comando informa o Rector, mas não o executa. Os estágios de geração do composer, cópia de assets e validação imprimem o que pretendem fazer. Nada é gravado. Execute isto primeiro, porque é a forma mais rápida de confirmar a estrutura do código-fonte e as flags.

composer build:dry

composer build:dry resolve para php scripts/build.php --dry-run. Verificado em relação a composer.jsonscripts e scripts/build.php (a ramificação dryRun em cada estágio). Com as flags padrão, o alvo é php81 e a raiz do código-fonte usa o padrão do script. Você pode sobrescrever qualquer um desses valores, como mostrado na etapa 2.

Se a simulação (dry-run) relatar um repositório de origem ausente, ela para imediatamente e identifica esse repositório. Corrija a estrutura do código-fonte antes de continuar. Consulte /integrations/backport/troubleshooting/.

Etapa 2 — build completo para PHP 8.1

O build para PHP 8.1 executa várias etapas em ordem. Ele mescla o core com os adaptadores de framework e a camada de compatibilidade com tcpdf. Ele executa a configuração do Rector em passagem única. Ele gera nextpdf/backportcomposer.json. Ele copia a licença, grava CHANGELOG.md e conta os arquivos PHP gerados.

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

Verificado em relação ao ponto de entrada da interface de linha de comando (CLI) de scripts/build.php. Os cinco estágios são executados em ordem: mesclar fontes, executar o downgrade do Rector, gerar composer.json, copiar assets estáticos e validar a saída. Cada estágio imprime um sinal de verificação quando é bem-sucedido. O primeiro estágio que falha interrompe o build e imprime o respectivo erro. Para excluir o Pro, adicione --no-pro.

Quando é bem-sucedido, o orquestrador imprime o tempo decorrido e o caminho de saída. Quando o Pro é incluído, ele também imprime o caminho de saída do Pro. O diretório de saída então contém src/, tests/, um composer.json gerado que declara o mapa replace e os requisitos de polyfill, LICENSE e CHANGELOG.md.

Etapa 3 — build completo para PHP 7.4

O build para PHP 7.4 inclui apenas o core e usa o pipeline de duas passagens. Ele executa o pré-processamento de enums, limpa o cache, aplica os ajustes pós-Rector e, em seguida, faz o downgrade completo.

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

Verificado em relação a scripts/build.php. Aqui, --target=php74 força apenas o core, desabilita o Pro e faz runRector() selecionar o caminho de duas passagens. O composer.json gerado traz a restrição >=7.4 <8.1. Ele substitui apenas nextpdf/core e adiciona os polyfills do PHP 8.0 e 8.1 sobre os polyfills 8.2–8.5.

Etapa 4 — leia a saída

O estágio de validação conta os arquivos PHP em output/src e falha se a contagem for zero. Ele não executa uma verificação de sintaxe localmente. O interpretador local é o PHP moderno do host de build, não o runtime de destino. Em vez disso, ele imprime o comando do Docker para validar contra o runtime de destino real. Verificado em relação a scripts/build.php (validateOutput()).

Para validar por completo, execute a verificação de sintaxe no PHP de destino. O fluxo de trabalho de release segue o mesmo caminho. Ele verifica a sintaxe da saída no PHP 8.1 (ou PHP 7.4) e, em seguida, a instala e a exercita em toda a matriz de suporte. Consulte /integrations/backport/production-usage/.

O que você construiu

Artefato	Construído por	Restrição	Substitui
nextpdf/backport (PHP 8.1)	Etapa 2	>=8.1 <8.5	core + artisan + laravel + symfony + codeigniter + compat-legacy
nextpdf/backport-pro (PHP 8.1)	Etapa 2, quando o Pro está incluído	>=8.1 <8.5	nextpdf/pro
nextpdf/backport (PHP 7.4)	Etapa 3	>=7.4 <8.1	nextpdf/core

Verificado em relação a scripts/adjust-composer.php.

A seguir

• /integrations/backport/production-usage/ — Integre isto ao fluxo de trabalho de release orientado a eventos.
• /integrations/backport/configuration/ — a referência de regras e flags por trás destes comandos.
• /integrations/backport/troubleshooting/ — cada falha de estágio e seu significado.