Visão geral do NextPDF Backport Builder
Ferramenta de build, não dependência de runtime. Os mantenedores do NextPDF usam este pacote para produzir distribuições do NextPDF compatíveis com PHP 8.1+ e PHP 7.4+. As aplicações nunca devem adicioná-lo como dependência de runtime.
Visão geral rápida
Seção intitulada “Visão geral rápida”O NextPDF Backport Builder é a infraestrutura de build que produz uma distribuição do ecossistema NextPDF portada para runtimes de PHP mais antigos que a baseline de desenvolvimento. O NextPDF é escrito para uma versão moderna do PHP e usa sintaxe que interpretadores anteriores rejeitam. O builder passa o código-fonte pelo Rector, um motor que transforma árvores de sintaxe abstrata, e gera pacotes com sintaxe aceita por um runtime de PHP 8.1 ou PHP 7.4.
O nome do pacote Composer é nextpdf/backport-builder. Ele declara "type": "project" e não carrega nenhuma dependência de runtime do NextPDF. Seus requisitos se limitam ao motor de build (rector/rector), à análise estática (phpstan/phpstan), ao executor de testes (phpunit/phpunit) e a um conjunto de pacotes symfony/polyfill-* usados na saída gerada. O composer.json na raiz do repositório confirma isso.
O que este pacote não é
Seção intitulada “O que este pacote não é”Este repositório não contém o motor do NextPDF. Ele contém as regras e os scripts que transformam esse motor em uma forma portada para versões anteriores. Essa separação tem três efeitos práticos:
- Você não instala isto para renderizar PDFs. Instale
nextpdf/backport, o artefato produzido por este builder. Mantenha o builder no host do mantenedor ou de integração contínua (CI). - Você não desenvolve sobre o código gerado. A distribuição gerada é um artefato somente leitura, produzido por máquina. Envie relatórios de bugs e solicitações de funcionalidades para os repositórios de código-fonte originais
nextpdf/*. - A saída é distribuída como tags de versão, não como branches deste repositório. O pipeline de release cria a tag da árvore gerada e anexa os arquivos a um release do GitHub.
O que ele produz
Seção intitulada “O que ele produz”O builder gera pacotes Composer cujos nomes e licenças são definidos por scripts/adjust-composer.php:
| Pacote produzido | Licença | Escopo | Gerado quando |
|---|---|---|---|
nextpdf/backport | Apache-2.0 | Core, adaptadores de framework e a camada de compatibilidade tcpdf para o alvo PHP 8.1 | Sempre |
nextpdf/backport-pro | proprietary | O módulo Pro, gerado como um pacote separado | Alvo PHP 8.1, quando o código-fonte do Pro está presente e o Pro não é excluído |
O pacote nextpdf/backport declara entradas replace do Composer para que, após a instalação, ele satisfaça as restrições dos pacotes originais. Para o alvo PHP 8.1, os pacotes substituídos são nextpdf/core, nextpdf/artisan, nextpdf/laravel, nextpdf/symfony, nextpdf/codeigniter e nextpdf/compat-legacy. Para o alvo PHP 7.4, apenas nextpdf/core é substituído, porque o build de PHP 7.4 é somente core. scripts/adjust-composer.php (buildReplace()) confirma isso.
O autoloader de uma aplicação consumidora resolve a árvore mesclada por meio de um único prefixo PHP Standards Recommendation 4 (PSR-4), NextPDF\, mapeado para src/. O PSR-4 mapeia um prefixo de namespace para um diretório base e resolve cada nome de classe totalmente qualificado para um arquivo abaixo dele; consulte PHP Framework Interop Group (PHP-FIG) PSR-4. O pacote Pro mapeia NextPDF\Pro\ para seu próprio src/.
Matriz de PHP suportada
Seção intitulada “Matriz de PHP suportada”A matriz abaixo cobre apenas o que as configurações do Rector e os scripts de build impõem. O host de build sempre executa uma versão moderna do PHP. A saída mira uma versão mais antiga.
| Aspecto | Valor | Evidência |
|---|---|---|
| PHP do host de build | >=8.4 <9.0 | composer.jsonrequire.php |
| PHP de build/test da CI | 8.5 | .github/workflows/0-ci.yml, build.yml (shivammathur/setup-phpphp-version: '8.5') |
| Restrição de saída do alvo PHP 8.1 | >=8.1 <8.5 | scripts/adjust-composer.php (generatePublicComposer()) |
| Restrição de saída do alvo PHP 7.4 | >=7.4 <8.1 | scripts/adjust-composer.php (generatePublicComposer()) |
| Escopo do alvo PHP 8.1 | Core + Artisan + Laravel + Symfony + CodeIgniter + compat-legacy (+ Pro, separado) | scripts/merge-sources.php, scripts/adjust-composer.php |
| Escopo do alvo PHP 7.4 | Somente core | scripts/build.php (--target=php74 força somente core, Pro desativado) |
O build de PHP 8.1 é validado em PHP 8.1, 8.2, 8.3 e 8.4. O build de PHP 7.4 é validado em PHP 7.4 e 8.0. As matrizes dos jobs validate-php81 e validate-php74 em .github/workflows/build.yml confirmam isso. Esses são os runtimes exercitados pelo pipeline. Eles formam um conjunto de validação observado, não uma alegação de conformidade.
O modelo de dois branches
Seção intitulada “O modelo de dois branches”Este repositório não tem branch main. PHP74 é o branch padrão, e PHP81 é o segundo branch permanente. O branch determina duas coisas: o alvo padrão do build local e o conjunto de fontes mesclado. Aplique qualquer alteração que afete ambos os alvos a cada branch por meio do respectivo pull request. O workflow de CI roda tanto em PHP74 quanto em PHP81. Isso é verificado em relação a git branch -a e a .github/workflows/0-ci.yml (branches: [PHP74, PHP81]).
Como acontece um release
Seção intitulada “Como acontece um release”O caminho de release é orientado a eventos. Quando a organização de código-fonte do NextPDF publica uma tag de release, um evento repository-dispatch do tipo source-release aciona o workflow de build. O workflow faz checkout de cada repositório de código-fonte na tag correspondente, executa o pipeline, verifica a sintaxe da saída no runtime de destino, valida-a em toda a matriz de suporte e anexa os arquivos a um release do GitHub. A tag de versão segue o Semantic Versioning: um número de versão é MAJOR.MINOR.PATCH sobre uma API pública declarada (Semantic Versioning 2.0.0 §2). .github/workflows/build.yml confirma isso.
Para onde ir em seguida
Seção intitulada “Para onde ir em seguida”- /integrations/backport/install/ — como instalar o builder em um host de build e como aplicações consumidoras instalam o pacote produzido.
- /integrations/backport/configuration/ — configurações do Rector, regras personalizadas e flags de build.
- /integrations/backport/quickstart/ — uma simulação (dry run) baseada no código-fonte e a invocação completa do build.
- /integrations/backport/production-usage/ — como integrar o builder a um workflow de release.
- /integrations/backport/troubleshooting/ — modos de falha contra os quais o pipeline protege e como interpretá-los.
- /integrations/backport/security-and-operations/ — postura de cadeia de suprimentos, a fronteira de confiança e as garantias operacionais.
- /integrations/backport/boot-and-discovery/ — como o builder descobre os módulos de origem e faz o boot.
- /integrations/backport/integration/ — o contrato de integração do host de build.