NextPDF Backport Builder の設定

これはビルドツールであり、ランタイム依存関係ではありません。このページに記載されている内容はすべて、ビルド時にソースをどのように変換するかを設定するものです。いずれもダウンストリームのランタイムには含まれません。

概要

この変換は、rector/config/ 配下の 3 つの Rector 設定ファイルと、rector/rules/ 配下の 3 つのカスタムルールによって制御されます。使用される設定はターゲットによって異なります。PHP 8.1 ターゲットは単一の Rector パスです。PHP 7.4 ターゲットは、中間の修正ステージを挟む 2 パスのパイプラインです。2 回目のパスが必要なのは、Rector が 1 回の走査では enum ケースのデフォルト値を解決できないためです。

Rector の設定

ファイル	目的	使用元
rector/config/rector-php81.php	PHP 8.1 への単一パスダウングレード	PHP 8.1 ターゲット
rector/config/rector-php74-enums.php	パス 1 — enum から定数リストクラスへの変換	PHP 7.4 ターゲット
rector/config/rector-php74.php	パス 2 — PHP 7.4 への完全ダウングレード	PHP 7.4 ターゲット

各設定では、Rector がネイティブに対応している機能向けに、Rector のダウングレードセットチェーン（withDowngradeSets(php81: true) または withDowngradeSets(php74: true)）を呼び出します。続いて、ネイティブには対応していない機能向けにカスタムルールを登録します。rector/config/ 内の 3 つのファイルで検証済みです。

スキップルール

rector-php81.php と rector-php74.php は、どちらも */tests/Benchmark/* をスキップします。ベンチマークスクリプトは Rector が解決できない外部 PDF ライブラリを参照しており、それによりデフォルトパラメータのリゾルバがクラッシュします。rector-php74.php はさらに DowngradeHashAlgorithmXxHashRector をスキップします。この組み込みルールは、最新の PHP で非推奨となった MHASH_XXH* 定数でクラッシュしますが、ソースは xxHash を使用していません。両ファイル内の withSkip() 呼び出しで検証済みです。

3 つのカスタムルール

リポジトリには、カスタム Rector ルールが 3 つだけ含まれています。3 つすべてが rector-php81.php に登録されており、非対称可視性、clone-with、トレイト定数の各ルールは rector-php74.php にも登録されています。これは tests/Rector/RectorRulesMetadataTest.php で直接アサートされており、各ルールを構築して定義とノード型を検証します。

DowngradeAsymmetricVisibilityRector

非対称可視性の set 修飾子を削除します。public private(set) として宣言されたプロパティまたはプロモートされたパラメータは、単なる public になります。読み取りアクセスは保持され、コンパイル時のセッター制限は破棄されます。読み取り可視性が残らない場合、このルールはデフォルトで public にします。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

オーバーライド配列を伴う clone() 関数形式を、clone、その後の明示的なプロパティ代入、一時変数の return に書き換えます。一時変数のカウンターはファイルごとにリセットされます。このルールは readonly プロパティ削除ルールの後に実行する必要があります。そうしないと、展開された代入が readonly プロパティに対して失敗するためです。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;
    }
}

このルールには文書化された制限があります。引数のマッチングには非再帰的なパターンを使用するため、入れ子になった括弧を含むオーバーライド値は処理されません。文字列の配列キーのみがプロパティ名として解決されます。rector/rules/DowngradeCloneWithRector.php とそのフィクスチャスイートで検証済みです。

DowngradeTraitConstantsRector

トレイト定数を静的プロパティに変換します。トレイト定数は、古いランタイムが「Traits cannot have constants」として拒否する機能です。このルールは、self::CONST および static::CONST の参照も静的プロパティ形式に書き換えます。可視性は保持されますが、古いターゲットではプロパティを final にできないため、final 修飾子は取り除かれます。型付きのクラス定数は型付きのプロパティになります。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;
    }
}

2 パスの PHP 7.4 パイプライン

PHP 7.4 ターゲットは単一のパスでは実行できません。Rector のデフォルトパラメータ値リゾルバは、コンストラクタプロモーション内の enum ケースのデフォルト値でクラッシュします。そのため、ビルドスクリプトは次の処理を実行します。

1. パス 1 — enum の前処理。 rector-php74-enums.php は、組み込みの enum から定数リストクラスへの変換ルールのみを実行します。このパスの後、enum ケースは単なるクラス定数になります。
2. キャッシュクリア。 2 回目のパスが古いツリーを参照しないように、Rector のキャッシュをクリアします。
3. 後処理の修正。 scripts/build.php は、enum からクラスへの変換ルールがカバーしないパターンを書き換えます。元の enum インスタンスメソッドは静的になります。EnumClass::Case->value および ->name のアクセスが解決されます。Rector がバインドできなかった名前付き引数は、位置引数にフラット化されます。これらは、そうしなければ PHP 7.4 でパースエラーになる構文パターンです。
4. パス 2 — 完全ダウングレード。 rector-php74.php は、PHP 7.4 の完全なダウングレードチェーンとカスタムルールを実行します。

scripts/build.php（runRector()、postProcessFixups()）で検証済みです。

ビルドフラグリファレンス

scripts/build.php がオーケストレーターとして機能します。getopt() 呼び出しと Build コンストラクタで検証済みのオプションは次のとおりです。

フラグ	デフォルト	効果
--version=<x.y.z>	2.0.0	生成される composer.json および CHANGELOG.md に書き込まれるバージョン
--source-dir=<path>	c:/Users/admin/Documents	兄弟ソースリポジトリを含むルート
--output-dir=<path>	<repo>/output	生成されたディストリビューションの書き込み先
--target=php74 | --target=php81	php81	ダウングレードターゲット。php74 はコアのみを強制し、Pro を無効化
--dry-run	オフ	全ステージのレポート専用モード実行（コピーと Rector はスキップ）
--no-pro	オフ	Pro パッケージの除外（PHP 8.1 ターゲットのみ。PHP 7.4 ではすでに除外済み）

無効な --target 値は、処理が開始される前に InvalidArgumentException を発生させます。Build::__construct()（VALID_TARGETS ガード）で検証済みです。

Composer スクリプト

スクリプト	コマンド	目的
composer test	phpunit	ルールのフィクスチャスイート実行
composer analyse	phpstan analyse rector/rules scripts --level=10	ビルドコードの静的解析
composer build	php scripts/build.php	フルビルド
composer build:dry	php scripts/build.php --dry-run	ドライランビルド

composer.jsonscripts で検証済みです。

次のステップ

• /integrations/backport/quickstart/ — ドライランとフルビルドの実行。
• /integrations/backport/troubleshooting/ — 各失敗ステージが意味する内容。