NextPDF Backport Builder のトラブルシューティング
これはビルドツールであり、ランタイム依存ではありません。このページにあるすべての症状は、メンテナーまたは CI ホスト上でのビルド時の状態です。どの状態も、ダウンストリームのアプリケーションには現れません。
ビルドは、順序付けられた 5 つのステージを実行します。最初の失敗で停止し、ステージ名とメッセージを出力します。まずステージを確認し、次に以下で原因を探してください。各ステージは、ソースのマージ、Rector ダウングレードの実行、composer.json の生成、静的アセットのコピー、出力の検証です。scripts/build.php（run() と step()）に対して検証済み。
ステージ: ソースのマージ
「ステージ: ソースのマージ」という見出しのセクション”Source repo '' not found at: ”
「”Source repo '' not found at: ”」という見出しのセクションマージは、コピーの前に想定されるすべてのソースリポジトリを検証します。見つからないリポジトリの名前とパスを示して中断します。PHP 8.1 ターゲットには、nextpdf、nextpdf-Artisan、nextpdf-compat-legacy、nextpdf-Laravel、nextpdf-Symfony、nextpdf-CodeIgniter、そして — Pro を含める場合は — nextpdf-Pro が必要です。PHP 7.4 ターゲットに必要なのは nextpdf のみです。scripts/merge-sources.php（run() の検証ループ、__construct() のリポジトリマップ）に対して検証済み。
解決方法: 上記の正確なディレクトリ名を使用し、--source-dir に渡したパスの下に兄弟ディレクトリとしてリポジトリをチェックアウトしてください。ドライランでは、読み取り対象となるすべてのリポジトリが一覧表示されます。フルビルドの前にレイアウトを確認するために使用してください。
ステージ: Rector ダウングレードの実行
「ステージ: Rector ダウングレードの実行」という見出しのセクションRector が非ゼロで終了する
「Rector が非ゼロで終了する」という見出しのセクションオーケストレーターは Rector failed on <label> (exit code: N) を報告して停止します。ラベルは、どのパスが失敗したかを示します — public package、pro package、enum pre-processing、または full downgrade です。scripts/build.php（runRectorPass()）に対して検証済み。
enum デフォルト値でのデフォルトパラメーターリゾルバーのクラッシュ（PHP 7.4）
「enum デフォルト値でのデフォルトパラメーターリゾルバーのクラッシュ（PHP 7.4）」という見出しのセクションこれが、PHP 7.4 ターゲットが 2 パス構成になっている理由です。Rector のデフォルトパラメーター値リゾルバーは、コンストラクタープロモーションのデフォルトとして使われた enum ケースでクラッシュします。パス 1（rector-php74-enums.php）で、先に enum を定数リストクラスへ変換します。これにより、パス 2 のフルパスでは enum ケースのデフォルトを処理せずに済みます。オーケストレーターをバイパスし、enum を含むソースに対してフルの PHP 7.4 構成を直接実行すると、このクラッシュが発生します。scripts/build.php（runRector() のコメントおよび 2 パスのシーケンス）と rector/config/rector-php74-enums.php に対して検証済み。
ベンチマークスクリプトが Rector をクラッシュさせる
「ベンチマークスクリプトが Rector をクラッシュさせる」という見出しのセクションrector-php81.php と rector-php74.php は */tests/Benchmark/* をスキップします。これらのスクリプトは、Rector が解決できない外部 PDF ライブラリを参照しており、それによってデフォルトパラメーターリゾルバーがクラッシュします。ベンチマークパスが処理される場合は、スキップ glob が欠落しているか、パスが異なっています。withSkip() の呼び出しに対して検証済み。
MHASH_XXH* のクラッシュ（PHP 7.4）
「MHASH_XXH* のクラッシュ（PHP 7.4）」という見出しのセクションrector-php74.php は DowngradeHashAlgorithmXxHashRector をスキップします。この組み込みルールは、xxHash 定数でクラッシュします。ソースは xxHash を使用していないため、このスキップは安全です。rector/config/rector-php74.php（withSkip()）に対して検証済み。
ステージ: Rector 後の修正処理（PHP 7.4 のみ）
「ステージ: Rector 後の修正処理（PHP 7.4 のみ）」という見出しのセクションこの修正処理は、2 つのパスの間で実行されます。enum からクラスへのルールが残したパターンを書き換えます。PHP 7.4 の出力で、EnumClass::Case->value、->name、インスタンスメソッドとして呼び出された旧 enum メソッド、または未解決の型に対する名前付き引数に関わるパースエラーが出る場合、その修正処理は該当パターンに一致していません。clone-with の制限もここに当てはまります。引数のマッチングは非再帰的であるため、入れ子になった括弧を含むオーバーライド値は書き換えられません。scripts/build.php（postProcessFixups()、fixEnumMethodCallSites()、applyFixups()）と rector/rules/DowngradeCloneWithRector.php（文書化された制限）に対して検証済み。
ステージ: composer.json の生成
「ステージ: composer.json の生成」という見出しのセクションこのステージでは、処理済みの src/ と tests/ を、ビルド一時ディレクトリから出力ディレクトリへ移動します。続いて、生成された composer.json を書き込みます。ここでの失敗は、ほぼ常にファイルシステムの状態が原因です。出力ディレクトリが書き込み可能でないか、Rector が何も生成しなかったためにビルド一時ツリーが存在していません。scripts/build.php（adjustComposer()、moveTree()）に対して検証済み。
ステージ: 静的アセットのコピー
「ステージ: 静的アセットのコピー」という見出しのセクションこのステージでは、コアソースリポジトリから LICENSE をコピーし、生成された CHANGELOG.md を書き込みます。ライセンスが存在しない場合、コピーは黙ってスキップされ、ビルドは続行されます。変更履歴は常に書き込まれます。ここでの失敗は、ビルドの途中で出力ディレクトリが書き込み不可になったことを示します。scripts/build.php（copyStaticAssets()）に対して検証済み。
ステージ: 出力の検証
「ステージ: 出力の検証」という見出しのセクション”Output src/ directory not found” / “No PHP files found in output”
「”Output src/ directory not found” / “No PHP files found in output”」という見出しのセクション検証には、空でない output/src が必要です。空のツリーは、マージが何もコピーしなかったか、ファイル移動が失敗したことを意味します。scripts/build.php（validateOutput()）に対して検証済み。
“Syntax validation: skipped (requires PHP runtime)”
「“Syntax validation: skipped (requires PHP runtime)”」という見出しのセクションこれはエラーではなく、想定どおりの動作です。ビルドホストはターゲットではなく最新の PHP を実行するため、ローカルステージではファイル数を数えるだけで、実際の構文チェック用の Docker コマンドを出力します。正式な構文ゲートは、実際のターゲットランタイムの下で実行される、リリースワークフローのビルド後の php -l ステップです。scripts/build.php（validateOutput()）と .github/workflows/build.yml（PHP 8.1 / PHP 7.4 の構文チェックステップ）に対して検証済み。
既知の制限
「既知の制限」という見出しのセクションこれらは、ダウングレードのアプローチに固有の制限です。ルールおよびプロジェクトの README.md の “Known Limitations” に対して検証済みです。
- readonly プロパティは削除されます。 clone-with 展開での明示的なプロパティ代入が古いランタイムで有効になるように、
readonlyは除去されます。ダウングレードされた出力では、不変性はランタイムによって強制されなくなります。 #[Override]は PHP 8.1 では強制されません。 この属性は残る場合がありますが、古いランタイムはそれに従って動作しません。- PHP 7.4 ターゲットはコアのみです。 フレームワークアダプター、tcpdf 互換レイヤー、および Pro は、ビルドスクリプトの構成上、PHP 7.4 ディストリビューションには含まれません。
- Pro は独立したパッケージで、PHP 8.1 のみです。 PHP 7.4 の Pro ビルドはありません。
- clone-with の引数マッチングは非再帰的です。 入れ子になった括弧を含むオーバーライド値は変換されず、文字列の配列キーのみがプロパティ名に解決されます。
- /integrations/backport/configuration/ — ルールとフラグのリファレンス。
- /integrations/backport/production-usage/ — CI ゲートとリリースレーン。