Configurar o NextPDF Backport Builder

Ferramentas de build — NÃO uma dependência de runtime. Tudo nesta página configura a transformação do código-fonte no momento do build. Nada disso é distribuído para um runtime downstream.

Visão geral

Três arquivos de configuração do Rector em rector/config/ e três regras personalizadas em rector/rules/ conduzem a transformação. A configuração escolhida depende do target. O target PHP 8.1 usa uma única passagem do Rector. O target PHP 7.4 usa um pipeline de duas passagens com um estágio de correção entre elas. A segunda passagem é necessária porque o Rector não consegue resolver valores padrão de casos de enum em uma única travessia.

Configurações do Rector

Arquivo	Finalidade	Usado por
rector/config/rector-php81.php	Downgrade de passagem única para PHP 8.1	Target PHP 8.1
rector/config/rector-php74-enums.php	Passagem 1 — converte enums em classes de lista de constantes	Target PHP 7.4
rector/config/rector-php74.php	Passagem 2 — downgrade completo para PHP 7.4	Target PHP 7.4

Cada configuração chama a cadeia de downgrade-set do Rector (withDowngradeSets(php81: true) ou withDowngradeSets(php74: true)) para os recursos que o Rector trata nativamente. Em seguida, registra regras personalizadas para os recursos restantes. Verificado em relação aos três arquivos em rector/config/.

Regras de skip

rector-php81.php e rector-php74.php ambos ignoram */tests/Benchmark/*. Os scripts de benchmark fazem referência a bibliotecas externas de Portable Document Format (PDF) que o Rector não consegue resolver, o que faz seu resolvedor padrão de parâmetros travar. rector-php74.php também ignora DowngradeHashAlgorithmXxHashRector. Essa regra interna trava nas constantes MHASH_XXH*, descontinuadas no PHP moderno, e o código-fonte não usa xxHash. Verificado em relação às chamadas withSkip() em ambos os arquivos.

As três regras personalizadas

O repositório distribui exatamente três regras personalizadas do Rector. Todas as três são registradas em rector-php81.php; as regras de visibilidade assimétrica, clone-with e constantes de trait também são registradas em rector-php74.php. tests/Rector/RectorRulesMetadataTest.php verifica isso diretamente ao construir cada regra e checar sua definição e seus tipos de nó.

DowngradeAsymmetricVisibilityRector

Remove o modificador set de visibilidade assimétrica. Uma propriedade ou parâmetro promovido declarado como public private(set) torna-se apenas public. O acesso de leitura é preservado; a restrição de setter em tempo de compilação é removida. Quando nenhuma visibilidade de leitura permanece, a regra usa public como padrão. Transformação comprovada pelo código-fonte em tests/Rector/Fixtures/DowngradeAsymmetricVisibility/public_private_set.php.inc:

before

<?php

class Config {
    public private(set) float $x = 0.0;
    public private(set) string $name = '';
    public private(set) int $count = 0;
}

after

<?php

class Config {
    public float $x = 0.0;
    public string $name = '';
    public int $count = 0;
}

DowngradeCloneWithRector

Reescreve a forma de função clone() com um array de overrides como uma operação de clone, atribuições explícitas de propriedade e o retorno de uma variável temporária. O contador de variáveis temporárias é reiniciado a cada arquivo. Esta regra deve ser executada depois da regra de remoção de propriedades readonly, porque, caso contrário, a atribuição expandida falharia contra uma propriedade readonly. Transformação comprovada pelo código-fonte em tests/Rector/Fixtures/DowngradeCloneWith/return_clone_with.php.inc:

before

<?php

class PageSize {
    public float $width = 0.0;
    public float $height = 0.0;

    public function withDimensions(float $width, float $height): self {
        return clone($this, ['width' => $width, 'height' => $height]);
    }
}

after

<?php

class PageSize {
    public float $width = 0.0;
    public float $height = 0.0;

    public function withDimensions(float $width, float $height): self
    {
        $__cloneResult1 = clone $this;
        $__cloneResult1->width = $width;
        $__cloneResult1->height = $height;
        return $__cloneResult1;
    }
}

A regra tem limitações documentadas. A correspondência de argumentos usa um padrão não recursivo; portanto, valores de override com parênteses aninhados não são tratados. Apenas chaves de array do tipo string são resolvidas para nomes de propriedade. Verificado em relação a rector/rules/DowngradeCloneWithRector.php e sua suíte de fixtures.

DowngradeTraitConstantsRector

Converte constantes de trait em propriedades estáticas. Runtimes mais antigos rejeitam constantes de trait com “Traits cannot have constants”. A regra também reescreve referências self::CONST e static::CONST para a forma de propriedade estática. A visibilidade é preservada; o modificador final é removido porque propriedades não podem ser final no target mais antigo. Uma constante de classe tipada passa a ser uma propriedade tipada. Transformação comprovada pelo código-fonte em tests/Rector/Fixtures/DowngradeTraitConstants/private_constant.php.inc:

before

<?php

trait HasLimit
{
    private const MAX_SIZE = 1024;

    public function getLimit(): int
    {
        return self::MAX_SIZE;
    }
}

after

<?php

trait HasLimit
{
    private static $MAX_SIZE = 1024;

    public function getLimit(): int
    {
        return self::$MAX_SIZE;
    }
}

O pipeline de duas passagens para PHP 7.4

O target PHP 7.4 não pode ser executado em uma única passagem. O resolvedor de valores padrão de parâmetro do Rector trava ao processar valores padrão de casos de enum na promoção de construtor. Por isso, o script de build executa:

1. Passagem 1 — pré-processamento de enums. rector-php74-enums.php executa apenas a regra interna de conversão de enum em classe de lista de constantes. Depois desta passagem, os casos de enum são constantes de classe simples.
2. Limpeza de cache. O cache do Rector é limpo para que a segunda passagem não veja uma árvore desatualizada.
3. Correções de pós-processamento. scripts/build.php reescreve padrões que a regra de conversão de enum em classe não cobre. Os antigos métodos de instância do enum passam a ser estáticos. Os acessos EnumClass::Case->value e ->name são resolvidos. Argumentos nomeados que o Rector não conseguiu vincular são convertidos em argumentos posicionais. Caso contrário, esses padrões de sintaxe causariam erros de parse no PHP 7.4.
4. Passagem 2 — downgrade completo. rector-php74.php executa toda a cadeia de downgrade para PHP 7.4 mais as regras personalizadas.

Verificado em relação a scripts/build.php (runRector(), postProcessFixups()).

Referência de flags de build

scripts/build.php orquestra o build. Suas opções são verificadas em relação à chamada getopt() e ao construtor Build:

Flag	Padrão	Efeito
--version=<x.y.z>	2.0.0	Versão gravada nos arquivos gerados composer.json e CHANGELOG.md
--source-dir=<path>	c:/Users/admin/Documents	Raiz que contém os repositórios de código-fonte irmãos
--output-dir=<path>	<repo>/output	Local onde a distribuição gerada é gravada
--target=php74 | --target=php81	php81	Target de downgrade. php74 força somente o core e desativa o Pro
--dry-run	off	Executa cada estágio em modo somente relatório; cópias e o Rector são ignorados
--no-pro	off	Exclui o pacote Pro (apenas no target PHP 8.1; o PHP 7.4 já o exclui)

Um valor inválido de --target lança InvalidArgumentException antes de qualquer trabalho começar. Verificado em relação a Build::__construct() (guarda VALID_TARGETS).

Scripts do Composer

Script	Comando	Finalidade
composer test	phpunit	Executa as suítes de fixtures das regras
composer analyse	phpstan analyse rector/rules scripts --level=10	Executa a análise estática do código de build
composer build	php scripts/build.php	Build completo
composer build:dry	php scripts/build.php --dry-run	Build em modo dry-run

Verificado em relação a composer.jsonscripts.

Próximos passos

• /integrations/backport/quickstart/ — execute o dry-run e o build completo.
• /integrations/backport/troubleshooting/ — o que cada estágio de falha significa.