NextPDF Backport Builder の概要

これはビルドツールであり、ランタイム依存ではありません。NextPDF のメンテナーは、このパッケージを使用して、PHP 8.1 以上および PHP 7.4 以上に対応する NextPDF ディストリビューションを生成します。アプリケーションにこのパッケージをランタイム依存として追加してはいけません。

概要

NextPDF Backport Builder は、開発時のベースラインより古い PHP ランタイム向けに、NextPDF エコシステムのダウングレード版ディストリビューションを生成するビルドインフラストラクチャーです。NextPDF 自体は最新の PHP バージョンを対象として書かれており、古いインタープリターでは受け付けられない構文を使用しています。ビルダーは、抽象構文木の変換エンジンである Rector でソースを処理し、PHP 8.1 または PHP 7.4 ランタイムが受け付ける構文のパッケージを出力します。

Composer パッケージ名は nextpdf/backport-builder です。このパッケージは "type": "project" を宣言しており、NextPDF のランタイム依存を持ちません。必要とするのは、ビルドエンジン（rector/rector）、静的解析（phpstan/phpstan）、テストランナー（phpunit/phpunit）、および生成された出力で使用される symfony/polyfill-* パッケージ群だけです。この内容は、リポジトリルートの composer.json に対して検証されています。

このパッケージではないもの

このリポジトリには NextPDF エンジンは含まれていません。含まれているのは、エンジンを backport された形式に変換するルールとスクリプトです。そのため、次の 3 つを明確に分けます。

• PDF をレンダリングするために、このパッケージをインストールするのではありません。 インストール対象の成果物は、このビルダーが生成した nextpdf/backport です。ビルダーは、メンテナーまたは CI ホスト上にとどまります。
• 生成されたコードを開発対象にするのではありません。 生成されたディストリビューションは、機械生成の読み取り専用成果物です。バグ報告や機能要望は、元の nextpdf/* ソースリポジトリへ提出してください。
• 出力は、このリポジトリのブランチとしてではなく、バージョンタグとして配布されます。 リリースパイプラインは、生成されたツリーにタグを付け、アーカイブを GitHub リリースに添付します。

生成するもの

ビルダーは、名前とライセンスが scripts/adjust-composer.php によって固定された Composer パッケージを出力します。

生成されるパッケージ	ライセンス	スコープ	ビルドされる条件
nextpdf/backport	Apache-2.0	コアに加えて、PHP 8.1 ターゲット向けのフレームワークアダプターおよび tcpdf 互換レイヤー	常時
nextpdf/backport-pro	proprietary	別パッケージとして出力される Pro モジュール	PHP 8.1 ターゲットで、Pro ソースが存在し、かつ Pro が除外されていない場合

nextpdf/backport パッケージは Composer の replace エントリを宣言し、インストール時に元のパッケージ制約を満たすようにします。PHP 8.1 ターゲットでは、置き換えられるパッケージは nextpdf/core、nextpdf/artisan、nextpdf/laravel、nextpdf/symfony、nextpdf/codeigniter、および nextpdf/compat-legacy です。PHP 7.4 ターゲットでは、PHP 7.4 ビルドがコアのみであるため、nextpdf/core のみが置き換えられます。この内容は、scripts/adjust-composer.php（buildReplace()）に対して検証されています。

コンシューマー側のオートローダーは、マージされたツリーを単一の PSR-4 プレフィックス NextPDF\（src/ にマッピング）を通じて解決します。PSR-4 は、名前空間プレフィックスをベースディレクトリにマッピングし、各完全修飾クラス名をその配下のファイルへ解決します。PHP-FIG PSR-4 を参照してください。Pro パッケージは、NextPDF\Pro\ を自身の src/ にマッピングします。

サポートされる PHP マトリクス

以下のマトリクスは、Rector 設定とビルドスクリプトが強制する内容のみを示しています。ビルドホストは常に最新の PHP を実行します。出力 は、より古いランタイムをターゲットとします。

対象	値	根拠
ビルドホストの PHP	>=8.4 <9.0	composer.jsonrequire.php
CI の build/test PHP	8.5	.github/workflows/0-ci.yml、build.yml（shivammathur/setup-phpphp-version: '8.5'）
PHP 8.1 ターゲットの出力制約	>=8.1 <8.5	scripts/adjust-composer.php（generatePublicComposer()）
PHP 7.4 ターゲットの出力制約	>=7.4 <8.1	scripts/adjust-composer.php（generatePublicComposer()）
PHP 8.1 ターゲットのスコープ	コア + Artisan + Laravel + Symfony + CodeIgniter + compat-legacy（+ Pro、別パッケージ）	scripts/merge-sources.php、scripts/adjust-composer.php
PHP 7.4 ターゲットのスコープ	コアのみ	scripts/build.php（--target=php74 はコアのみを強制し、Pro を無効化）

PHP 8.1 ビルドは、PHP 8.1、8.2、8.3、8.4 で検証されます。PHP 7.4 ビルドは、PHP 7.4 と 8.0 で検証されます。この内容は、.github/workflows/build.yml 内の validate-php81 および validate-php74 ジョブマトリクスに対して検証されています。これらは、パイプラインが実行するランタイムです。あくまで観測済みの検証セットであり、適合性の主張ではありません。

デュアルブランチモデル

このリポジトリには main ブランチがありません。PHP74 がデフォルトブランチで、PHP81 が 2 つ目の恒久ブランチです。ブランチによって、ローカルビルドのデフォルトターゲットと、マージされるソースセットの 2 つが決まります。両方のターゲットに影響する変更は、各ブランチへ個別のプルリクエストを通じて適用されます。継続的インテグレーションのワークフローは、PHP74 と PHP81 の両方で実行されます。この内容は、git branch -a と .github/workflows/0-ci.yml（branches: [PHP74, PHP81]）に対して検証されています。

リリースの流れ

リリース経路はイベント駆動です。NextPDF ソース組織がリリースタグを公開すると、source-release 型のリポジトリディスパッチイベントがビルドワークフローをトリガーします。ワークフローは、すべてのソースリポジトリを一致するタグでチェックアウトし、パイプラインを実行し、ターゲットランタイム上で出力を構文チェックし、サポートマトリクス全体にわたって検証し、アーカイブを GitHub リリースに添付します。バージョンタグはセマンティックバージョニングに従います。バージョン番号は、宣言された公開 API に対する MAJOR.MINOR.PATCH です（Semantic Versioning 2.0.0 §2）。この内容は、.github/workflows/build.yml に対して検証されています。

次に進む先

• /integrations/backport/install/ — ビルドホストでビルダーを取得する方法、およびコンシューマーが生成済みパッケージをインストールする方法。
• /integrations/backport/configuration/ — Rector 設定、カスタムルール、およびビルドフラグ。
• /integrations/backport/quickstart/ — ソースに裏付けられた、実行可能なドライランとフルビルドの呼び出し。
• /integrations/backport/production-usage/ — ビルダーをリリースワークフローに組み込む方法。
• /integrations/backport/troubleshooting/ — パイプラインが防ぐ障害モードと、その読み解き方。
• /integrations/backport/security-and-operations/ — サプライチェーンに対する姿勢、信頼境界、および運用上の保証。
• /integrations/backport/boot-and-discovery/ — ビルダーがソースモジュールを検出し、ブートする方法。
• /integrations/backport/integration/ — ビルドホスト統合契約。