Como instalar o NextPDF Backport Builder

Instale estas ferramentas de build em uma estação de trabalho de mantenedor ou em um runner de integração contínua (CI). Elas NÃO são dependências de runtime. Uma aplicação downstream nunca instala o builder; ela instala o pacote produzido por ele.

Visão geral

Dois públicos instalam componentes diferentes:

Um mantenedor ou operador de CI clona este repositório e instala suas dependências de build. Instale o nextpdf/backport-builder somente neste contexto.
Uma aplicação downstream em um runtime de PHP mais antigo instala o pacote nextpdf/backport gerado a partir do respectivo canal de release. Ela nunca acessa este repositório.

Esta página cobre os dois fluxos de trabalho. Leia a seção correspondente à sua função.

Instalação no host de build

Requisitos

Dependência	Constraint	Fonte de verdade
PHP	`>=8.4 <9.0`	`composer.jsonrequire.php`
Composer	2.6+	`CONTRIBUTING.md` tabela de ambiente
`rector/rector`	`^2.0`	`composer.jsonrequire-dev`
`phpstan/phpstan`	`^2.1`	`composer.jsonrequire-dev`
`phpunit/phpunit`	`^13.0`	`composer.jsonrequire-dev`

O workflow de CI provisiona PHP 8.5 tanto para o job de build quanto para o de dry-run. Qualquer host de build executando uma versão de PHP dentro de >=8.4 <9.0 atende à constraint do Composer. O parser do PHP precisa aceitar a sintaxe mais recente usada pelo código-fonte. Verificado em relação a .github/workflows/0-ci.yml.

Passos

Clone o repositório e, em seguida, faça checkout do branch correspondente ao target que você quer construir. PHP74 é o branch padrão e produz a distribuição PHP 7.4, somente core. PHP81 produz a distribuição PHP 8.1 com todos os adapters.
Terminal window
```
git clone https://github.com/nextpdf-labs/backport.git
cd backport
git checkout PHP74
```
Instale as dependências de build. Não passe --no-dev: o engine do Rector, o PHPStan e o PHPUnit ficam em require-dev, e o build não consegue rodar sem eles.
Terminal window
```
composer install --prefer-dist --no-progress
```
Confirme que a toolchain é resolvida corretamente. O script analyse executa o PHPStan no nível 10 sobre rector/rules e scripts. Uma execução limpa mostra que o próprio código de build está consistente antes de você produzir a saída.
Terminal window
```
composer analyse
```
Execute os testes de fixture das regras. Cada regra customizada do Rector tem uma suíte de fixtures que verifica a transformação before/after exata.
Terminal window
```
composer test
```

Após o passo 4, o host está pronto para fazer o build. Acesse /integrations/backport/quickstart/ para ver as invocações de dry-run e build completo.

Estrutura esperada da árvore de fontes

O build mescla vários repositórios de fontes em uma única árvore. Coloque-os como diretórios irmãos sob uma única raiz de fontes; o script de merge referencia cada diretório pelo nome. Para o target PHP 8.1, ele lê nextpdf (core), nextpdf-Artisan, nextpdf-compat-legacy, nextpdf-Laravel, nextpdf-Symfony, nextpdf-CodeIgniter e nextpdf-Pro quando o Pro está incluído. Para o target PHP 7.4, ele lê apenas nextpdf. Verificado em relação a scripts/merge-sources.php (MergeSources::__construct()). Informe a raiz de fontes com --source-dir. Consulte /integrations/backport/configuration/ para ver a referência das flags.

Consumo downstream do pacote produzido

Quando você der suporte a um projeto em um runtime de PHP mais antigo, instale a distribuição produzida, não este builder.

PHP 8.1 a 8.3

composer require nextpdf/backport

O pacote instalado declara a constraint >=8.1 <8.5 e substitui nextpdf/core, nextpdf/artisan, nextpdf/laravel, nextpdf/symfony, nextpdf/codeigniter e nextpdf/compat-legacy. O código da aplicação continua importando o namespace NextPDF\ sem alterações. O pacote faz o autoload da árvore mesclada por meio do único prefixo PHP Standard Recommendation 4 (PSR-4) NextPDF\ mapeado para src/. Um autoloader PSR-4 anexa o nome relativo da classe a um diretório base registrado para o prefixo (PHP-FIG PSR-4). Verificado em relação a scripts/adjust-composer.php (buildPublicAutoloadMap(), buildReplace()).

PHP 7.4 a 8.0

composer require nextpdf/backport

A distribuição PHP 7.4 é somente core. Ela declara a constraint >=7.4 <8.1 e substitui apenas nextpdf/core. Os adapters de framework, a camada de compatibilidade tcpdf e o Pro não estão incluídos na distribuição PHP 7.4. Verificado em relação a scripts/adjust-composer.php e scripts/build.php (o target PHP 7.4 força somente core). Um projeto que precisa de um adapter de framework precisa usar PHP 8.1 ou mais recente.

Pro

composer require nextpdf/backport-pro

A distribuição Pro é um pacote separado, nextpdf/backport-pro, com uma licença proprietary. Ela requer nextpdf/backport no major.minor correspondente e adiciona phpseclib/phpseclib ^3.0. Ela é produzida apenas para o target PHP 8.1. Verificado em relação a scripts/adjust-composer.php (generateProComposer()).

A distribuição PHP 7.4 e a distribuição Pro são mutuamente exclusivas: por construção do script de build, não existe build PHP 7.4 Pro.

Polyfills no pacote produzido

O composer.json gerado requer os pacotes symfony/polyfill-* para que funções mais recentes da biblioteca padrão possam ser resolvidas no runtime de destino. O target PHP 8.1 requer polyfills de PHP 8.2 até 8.5. O target PHP 7.4 também requer os polyfills de PHP 8.0 e 8.1. Essas são dependências de runtime do pacote produzido, não do builder. Verificado em relação a scripts/adjust-composer.php (generatePublicComposer()).

A seguir

/integrations/backport/configuration/ — configuração do Rector, regras customizadas e referência das flags de build.
/integrations/backport/quickstart/ — seu primeiro dry-run e build completo.