NextPDF Backport Builder クイックスタート

これはビルドツールであり、ランタイム依存関係ではありません。このウォークスルーは、メンテナーまたは継続的インテグレーション（CI）のホスト上で実行します。生成されたアーカイブが、ダウンストリームプロジェクトで使用されます。ここに示す手順は、アプリケーションサーバー上では実行しません。

概要

3 つの処理を実行します。まずドライランで、ファイルには触れずにパイプラインが正しく接続されていることを確認します。次に、PHP 8.1 の完全なビルドを行います。続いて、PHP 7.4 の完全なビルドを行います。各ステップは 1 つのコマンドで完了します。いずれも、Composer スクリプト、または文書化された scripts/build.php の呼び出しに基づいています。

前提条件

• PHP >=8.4 <9.0 のビルドホストに、ビルド依存関係がインストールされていること（composer install、--no-dev は付けません）。/integrations/backport/install/. を参照してください。
• ソースリポジトリが、1 つのソースルートの下に兄弟ディレクトリとしてチェックアウトされていること。PHP 8.1 ビルドは nextpdf、nextpdf-Artisan、nextpdf-compat-legacy、nextpdf-Laravel、nextpdf-Symfony、nextpdf-CodeIgniter、および nextpdf-Pro（Pro 用）を読み取ります。PHP 7.4 ビルドは nextpdf のみを読み取ります。scripts/merge-sources.php で検証済みです。

ステップ 1 — ドライラン

ドライランでは、すべてのステージをレポート専用モードで実行します。マージステージは、コピー対象になるものを一覧表示します。Rector のステージは通知だけで、実行されません。composer 生成、アセットコピー、検証の各ステージは、実行予定の処理を出力します。何も書き込まれません。最も手早い確認方法なので、まずこれを実行し、ソースレイアウトとフラグが正しいことを確認してください。

composer build:dry

composer build:dry は php scripts/build.php --dry-run に解決されます。composer.jsonscripts と scripts/build.php（各ステージの dryRun 分岐）で検証済みです。デフォルトのフラグでは、ターゲットは php81 になり、ソースルートはスクリプトのデフォルト値を使います。ステップ 2 に示すように、どちらも上書きできます。

ドライランがソースリポジトリの欠落を報告した場合は、即座に失敗し、該当するリポジトリ名を示します。続行する前にソースレイアウトを修正してください。/integrations/backport/troubleshooting/. を参照してください。

ステップ 2 — PHP 8.1 の完全なビルド

PHP 8.1 ビルドでは、複数のステップを順に実行します。コアに加えて、フレームワークアダプターと tcpdf 互換レイヤーをマージします。シングルパスの Rector 構成を実行します。nextpdf/backportcomposer.json を生成します。ライセンスをコピーし、CHANGELOG.md を書き出し、出力された PHP ファイル数を集計します。

php scripts/build.php \
  --version=2.0.0 \
  --source-dir=/path/to/sources \
  --output-dir=./output

scripts/build.php の CLI エントリーポイントで検証済みです。5 つのステージが順に実行されます。ソースのマージ、Rector ダウングレードの実行、composer.json の生成、静的アセットのコピー、出力の検証です。各ステージは、成功時にチェックマークを出力します。最初に失敗したステージでビルドは停止し、そのエラーが出力されます。Pro を除外するには、--no-pro を追加してください。

成功すると、オーケストレーターは経過時間と出力パスを出力します。Pro が含まれている場合は、Pro の出力パスも併せて出力します。完了後の出力ディレクトリには、src/、tests/、replace マップとポリフィル要件を宣言する生成済みの composer.json、LICENSE、および CHANGELOG.md が含まれます。

ステップ 3 — PHP 7.4 の完全なビルド

PHP 7.4 ビルドはコアのみを対象とし、2 パスのパイプラインを実行します。各パスでは、列挙型の前処理、キャッシュのクリア、Rector 適用後の修正、完全なダウングレードを行います。

php scripts/build.php \
  --version=2.0.0 \
  --source-dir=/path/to/sources \
  --output-dir=./output-php74 \
  --target=php74

scripts/build.php で検証済みです。ここでは、--target=php74 によってコアのみが強制され、Pro が無効化され、runRector() が 2 パス用の処理経路を選択します。生成される composer.json は、制約 >=7.4 <8.1 を持ち、nextpdf/core のみを置き換え、8.2〜8.5 のポリフィルに加えて PHP 8.0 と 8.1 のポリフィルを追加します。

ステップ 4 — 出力を読み取る

検証ステージは output/src 内の PHP ファイルを集計し、その数が 0 の場合は失敗します。ローカルのインタープリターはターゲットではなくビルドホスト上の新しい PHP であるため、構文チェックはローカルでは実行されません。実際のターゲットランタイムで検証するための Docker コマンドを出力します。scripts/build.php（validateOutput()）で検証済みです。

完全に検証するには、ターゲットの PHP で構文チェックを実行してください。リリースワークフローは、まさにこの処理を行います。PHP 8.1（または PHP 7.4）で出力の構文チェックを行い、その後サポートマトリックス全体でインストールして動作を確認します。/integrations/backport/production-usage/. を参照してください。

作成された成果物

成果物	作成元	制約	置き換え対象
nextpdf/backport（PHP 8.1）	ステップ 2	>=8.1 <8.5	core + artisan + laravel + symfony + codeigniter + compat-legacy
nextpdf/backport-pro（PHP 8.1）	ステップ 2（Pro を含む場合）	>=8.1 <8.5	nextpdf/pro
nextpdf/backport（PHP 7.4）	ステップ 3	>=7.4 <8.1	nextpdf/core

scripts/adjust-composer.php で検証済みです。

次のステップ

• /integrations/backport/production-usage/ — これをイベント駆動のリリースワークフローに組み込みます。
• /integrations/backport/configuration/ — これらのコマンドの背後にあるルールとフラグのリファレンス。
• /integrations/backport/troubleshooting/ — 各ステージの失敗とその意味。