Backport Builder API リファレンス
Backport Builder はランタイムライブラリではなく、ビルドツールです。その公開インターフェイスは、ビルドコマンド一式（scripts/build.php とその composer build* ラッパー）、その背後にある 4 つのスクリプトレベルのクラス（Build、MergeSources、AdjustComposer、ValidateBuildContract）、3 つの Rector 構成ファイル、3 つのカスタム Rector ルール、そして生成パッケージ契約（nextpdf/backport および nextpdf/backport-pro）です。これをビルドホストまたは CI ホスト上で実行し、最新の NextPDF ソースをダウングレード済みディストリビューションに変換します。アプリケーションに追加するものではありません。
初めて使う場合は、まず composer build:dry（これは php scripts/build.php --dry-run）から始めます。これはファイルを書き込まず、レポート専用モードで各ステージをすべて実行するため、実際のビルドの前にソースレイアウトとフラグを確認できます。下の「よく使うタスク」の最初のサンプルが、その例です。
よく使うタスク
「よく使うタスク」という見出しのセクションこのパッケージで最も頻繁に行う操作は、ビルドホスト上でのビルド呼び出しです。下の各サンプルはいずれも単一のコマンドであり、scripts/build.php および composer.json に対応しています。
何も書き込まずにパイプラインを検証します（安全な初回実行）。
composer build:dryこれは php scripts/build.php --dry-run に解決されます。マージ、Rector、composer 生成、アセットコピー、検証をレポート専用モードで実行し、何もコピーしません。
PHP 8.1 の完全なディストリビューションを生成します（nextpdf/backport。Pro ソースが存在する場合は nextpdf/backport-pro も生成）。
php scripts/build.php \ --version=2.0.0 \ --source-dir=/path/to/sources \ --output-dir=./outputコアにフレームワークアダプターと tcpdf 互換レイヤーを加えてマージし、PHP 8.1 ターゲット向けの単一 Rector パスを実行して、生成されたパッケージツリーを ./output に出力します。--no-pro を追加すると、Pro パッケージをスキップします。
コアのみの PHP 7.4 ディストリビューションを生成します（2 パスの enum パイプライン）。
php scripts/build.php \ --version=2.0.0 \ --source-dir=/path/to/sources \ --output-dir=./output-php74 \ --target=php74--target=php74 はコアのみの出力を強制して Pro を無効化し、その後 enum の前処理、Rector 後の修正、PHP 7.4 への完全なダウングレードパスを実行します。
コマンドサーフェス
「コマンドサーフェス」という見出しのセクションビルドのエントリポイントと、ビルドを駆動するスクリプトレベルのクラスについて、正確なシグネチャ、フラグ、終了時の動作が必要な場合は、この表を参照してください。
| シンボル | パラメーター | 既定の動作 | 戻り値 | スローまたは失敗の条件 | 備考 |
|---|---|---|---|---|---|
scripts/build.php | スクリプトに記載されたターゲット、バージョン、ソースパス、出力パス、およびフラグ。 | ブランチ固有のターゲット既定値を使用します。 | 生成されたパッケージツリー。 | 非ゼロの終了コードとステージ固有のエラー出力。 | メインのビルドエントリポイント。アプリケーション内ではなく、ビルドホスト上で実行します。 |
Build::__construct(string $version, string $sourceDir, string $outputDir, string $target = 'php81', bool $includePro = true, bool $dryRun = false) | バージョン、ソースディレクトリ、出力ディレクトリ、ターゲットランタイムレーン、Pro 包含フラグ、ドライランフラグ。 | 既定は PHP 8.1 ターゲットです。PHP 7.4 以外では Pro を含め、ドライランが有効でない限り書き込みます。 | Build | サポートされないターゲットの場合に InvalidArgumentException が発生します。run()。 | 背後にあるスクリプトレベルのクラス：scripts/build.php。 |
Build::run() | なし。 | 契約を検証し、ソースをマージし、composer.json のメタデータを調整して、Rector パスを実行します。 | bool | 返り値として false を返し、想定されるステージ失敗を表します。想定外の filesystem/runtime エラーの場合はスローすることがあります。 | CI では false を失敗として扱います。 |
composer build:dry | Composer スクリプトのラッパー。 | ドライランによるビルド検証。 | 終了ステータスとログ。 | ビルドまたは検証の失敗時に非ゼロで終了します。 | CI ゲートで使用されます。 |
scripts/merge-sources.php | ソースのチェックアウトパスとマージ先。 | ターゲットランタイム向けに、選択したソースパッケージをマージします。 | マージされたソースツリー。 | ソースの欠落、サポートされないターゲット、ファイルシステムの失敗。 | ソース参照をリリースタグに合わせて維持します。 |
MergeSources::__construct(string $sourceBaseDir, string $outputDir, bool $includePro = true, bool $dryRun = false, bool $coreOnly = false) | ソースのベースディレクトリ、出力ディレクトリ、Pro 包含フラグ、ドライランフラグ、コアのみフラグ。 | 構成済みのすべてのリポジトリをマージします。coreOnly が true の場合はコアのみをマージします。 | MergeSources | 実行時にソースパスまたは出力パスが無効な場合。 | 背後にあるスクリプトレベルのクラス：scripts/merge-sources.php。 |
MergeSources::run() | なし。 | 選択したソースツリーをビルドターゲットへコピーし、正規化します。 | bool | 返り値として false を返し、想定されるマージ失敗を表します。 | ログは getLog() で取得します。 |
MergeSources::getLog() | なし。 | 蓄積されたステージのログエントリを返します。 | array | 想定なし。 | CI 診断に使用します。 |
scripts/adjust-composer.php | 生成された composer.json のメタデータとバージョン。 | 生成された出力向けに、パッケージ制約と replace エントリを書き込みます。 | 調整済みの composer.json。 | バージョンが無効な場合、または生成ファイルが欠落している場合。 | 生成パッケージのアイデンティティを管理します。 |
AdjustComposer::__construct(string $version, string $target = 'php81') | バージョン文字列とターゲットレーン。 | PHP 8.1 ターゲット。 | AdjustComposer | 生成パスでターゲットが無効な場合のエラー。 | ビルドスクリプトとテストで使用されます。 |
AdjustComposer::generatePublicComposer() | なし。 | 次のメタデータを生成します：nextpdf/backport。 | array | 想定なし。 | テスト向けの純粋な生成 API。 |
AdjustComposer::generateProComposer() | なし。 | 次のメタデータを生成します：nextpdf/backport-pro。 | array | 想定なし。 | プロプライエタリなビルドレーン向けの純粋な生成 API。 |
AdjustComposer::writePublicComposer(string $outputDir) | 出力ディレクトリ。 | 公開用の composer.json を生成します。 | void | ファイルシステムのエラー。 | 生成された出力ディレクトリ内でのみ使用します。 |
AdjustComposer::writeProComposer(string $proOutputDir) | Pro の出力ディレクトリ。 | Pro 用の composer.json を生成します。 | void | ファイルシステムのエラー。 | Pro の出力ツリーが存在している必要があります。 |
ValidateBuildContract::__construct(string $repoRoot) | リポジトリのルート。 | 指定されたリポジトリルートを契約のベースとして使用します。 | ValidateBuildContract | 想定なし。 | スクリプトレベルの契約バリデーター。 |
ValidateBuildContract::run() | なし。 | 必須の入力とビルドの前提条件を確認します。 | bool | 返り値として false を返し、契約検証の失敗を表します。 | ビルド出力を信頼する前に実行します。 |
Rector の構成
「Rector の構成」という見出しのセクションどの Rector 構成ファイルがどのターゲットレーンを駆動するか、また各パスが PHP 8.1 の単一パス、または PHP 7.4 の 2 パスのパイプラインのどこに位置するかを知りたい場合は、この表を使用してください。
| シンボル | パラメーター | 既定の動作 | 戻り値 | スローまたは失敗の条件 | 備考 |
|---|---|---|---|---|---|
rector/config/rector-php81.php | ソースツリーと Rector ランタイム。 | PHP 8.1 ターゲットへの単一パスダウングレード。 | 変換後のソース。 | Rector の解析または変換の失敗。 | PHP 8.1 ディストリビューションレーンで使用されます。 |
rector/config/rector-php74-enums.php | ソースツリーと Rector ランタイム。 | enum 変換のための最初の PHP 7.4 パス。 | 中間の変換後ソース。 | Rector の解析または変換の失敗。 | 完全な PHP 7.4 パスの前に実行します。 |
rector/config/rector-php74.php | 中間ソースと Rector ランタイム。 | 完全な PHP 7.4 ダウングレードパス。 | PHP 7.4 互換のソース。 | Rector の解析または変換の失敗。 | PHP 7.4 ディストリビューションレーンで使用されます。 |
カスタムルール
「カスタムルール」という見出しのセクションプロジェクト固有の 3 つの Rector ルールを保守または拡張していて、各ルールのメソッド契約と変換対象の構文を確認したい場合は、この表を参照してください。
| シンボル | パラメーター | 既定の動作 | 戻り値 | スローまたは失敗の条件 | 備考 |
|---|---|---|---|---|---|
DowngradeAsymmetricVisibilityRector | 非対称可視性を使用するプロパティまたはプロモートされたパラメーター。 | 古いランタイムと互換性のある通常の可視性。 | 可能な場合は読み取り可視性を保持します。 | Rector ルールの失敗。 | セッターの制限はコンパイル時のみのものであり、生成された出力では削除されます。 |
DowngradeAsymmetricVisibilityRector::getRuleDefinition() | なし。 | Rector ルールのメタデータと例を返します。 | RuleDefinition | 想定なし。 | ルールのドキュメントを Rector ツールから参照できる状態に保ちます。 |
DowngradeAsymmetricVisibilityRector::getNodeTypes() | なし。 | ルールが検査するノードタイプを選択します。 | array<class-string<Node>> | 想定なし。 | 決定的な変換のため、スコープは狭く保ちます。 |
DowngradeAsymmetricVisibilityRector::refactor(Node $node) | AST ノード。 | 非対称可視性が存在する箇所を変換します。 | `Node | null` | Rector ルールの失敗。 |
DowngradeCloneWithRector | clone()（プロパティのオーバーライドを伴う）。 | clone に明示的なプロパティ代入を加えたもの。 | 生成された一時変数を使用します。 | Rector ルールの失敗。 | readonly プロパティのダウングレード後に実行する必要があります。 |
DowngradeCloneWithRector::getRuleDefinition() | なし。 | ルールのメタデータと例を返します。 | RuleDefinition | 想定なし。 | Rector の診断で使用されます。 |
DowngradeCloneWithRector::getNodeTypes() | なし。 | return ノードと式ノードを選択します。 | array<class-string<Node>> | 想定なし。 | ルールを clone-with 構文に絞ります。 |
DowngradeCloneWithRector::refactor(Node $node) | AST ノード。 | clone-with を clone と代入に書き換えます。 | `array | null` | Rector ルールの失敗。 |
DowngradeTraitConstantsRector | トレイト定数およびそれらへの参照。 | 静的プロパティとプロパティ参照。 | 可能な場合は可視性を保持します。 | Rector ルールの失敗。 | 古いプロパティは final にできないため、final を削除します。 |
DowngradeTraitConstantsRector::getRuleDefinition() | なし。 | ルールのメタデータと例を返します。 | RuleDefinition | 想定なし。 | Rector の診断で使用されます。 |
DowngradeTraitConstantsRector::getNodeTypes() | なし。 | トレイトノードとクラス定数取得ノードを選択します。 | array<class-string<Node>> | 想定なし。 | ルールをトレイト定数に限定します。 |
DowngradeTraitConstantsRector::refactor(Node $node) | AST ノード。 | トレイト定数とその参照を互換性のあるプロパティに書き換えます。 | `Node | null` | Rector ルールの失敗。 |
生成パッケージ契約
「生成パッケージ契約」という見出しのセクションビルダーが出力する内容、つまり下流のプロジェクトが実際にインストールするパッケージ名と、どちらが Pro ディストリビューションを含むかを確認するには、この表を使用してください。
| 生成パッケージ | ランタイムでの役割 | 備考 |
|---|---|---|
nextpdf/backport | 生成されたオープンソースのランタイムディストリビューション。 | 対象ランタイム向けに、選択した nextpdf/* パッケージを置き換えます。 |
nextpdf/backport-pro | Pro ソースが存在する場合に生成される、プロプライエタリな Pro ディストリビューション。 | オープンソースパッケージとは別に公開します。 |
開発上の注意
「開発上の注意」という見出しのセクション- ビルダーはソースリリースを取り込み、生成された成果物を出力します。生成された出力を信頼できる情報源として扱い、それにパッチを当ててはいけません。
- 各カスタムルールは、ビルドパイプラインに組み込まれる前にフィクスチャテストを備えている必要があります。
- リリースジョブは、ビルドホスト上だけでなく、ターゲットランタイム上でも生成された出力を検証する必要があります。