リリース — 詳細リファレンス

概要

NextPDF\Enterprise\Release 名前空間は、プロダクトリリースをイミュータブルで型付けされた値オブジェクトとしてモデル化します。その公開サーフェスは、7 個の final クラスと 5 個の文字列バックド enum です。ReleaseManifest は、アーティファクトごとの ArtifactManifest エントリと、サプライチェーン証跡のパスを集約します。BuildProfile は、1 つのアーティファクトバリアントに対する唯一の信頼できる情報源です。ArtifactNamer と PackageMapping は、プロファイルから決定的なファイル名と Composer パッケージ識別子を導出します。PublishingPlan::fromProfiles は、すべてのプロファイルを、正しいチャネルとアクセス境界を持つ型付けされた PublishingTarget エントリに解決します。ReleaseStatus は、リリースのライフサイクルを型付けします。このモジュールは I/O、ネットワーク呼び出し、暗号処理を一切行いません。純粋なメタデータモデリングです。

提供とライセンス

このケイパビリティは NextPDF Enterprise（nextpdf/enterprise）に同梱されており、Enterprise ティアのライセンスエンベロープで有効化されます。その資格を持たないデプロイメントでは、このケイパビリティのクラスはロードされません。エディションを比較してライセンスを取得。

このサーフェスは nextpdf/enterprise パッケージの境界によってライセンスされ、機能ごとに独立したケイパビリティコードはありません。Core と Pro は、リリースモデリングレイヤーを同梱していません。

公開 API サーフェス

composer require nextpdf/enterprise:^3

シンボル	パラメータ	デフォルトの挙動	戻り値	スロー/失敗条件	備考
ReleaseManifest::__construct	version, sourceCommit, builtAt, artifacts = [], sbomPath = null, gpgSignature = null, checksumPath = null	イミュータブルな最上位リリースドキュメントを構築	インスタンス	—	final readonly。SCHEMA_VERSION は '1.0'。追加フィールドはマイナー、破壊的変更はメジャー。since 3.0.0
ReleaseManifest::createWithDefaults	string $version, string $sourceCommit, DateTimeImmutable $builtAt, array $artifacts = []	ArtifactNamer を介してデフォルトの SBOM、署名、チェックサムのファイル名を事前設定	self	—	リリースビルダー向けの正規のエントリポイント。個別パスの上書きにはコンストラクタを使用
ReleaseManifest::toArray / ::toJson	なし	すべてのアーティファクトエントリを含めてマニフェストをシリアライズ	array / JSON 文字列	toJson: エンコード失敗時に JsonException	整形出力、スラッシュ非エスケープ。built_at は ATOM 形式
ReleaseManifest::validate	なし	アーティファクトリストが空でなく、各アーティファクトがリリースのバージョンとコミットに一致することを検査	エラーの list<string>。空なら有効	スローしない	呼び出し側は空でないリストを欠陥として扱う必要あり
ArtifactManifest::__construct	filename, version, sourceCommit, edition, deliveryMode, encodingTechnology, channel, phpTarget, sha256, ioncubeExpire, builtAt	ビルドされた 1 つのアーティファクトを記録。何を、どのようにビルドし、どのように検証するか	インスタンス	—	final readonly。有効期限のないアーティファクトでは ioncubeExpire は null
ArtifactManifest::fromProfile	BuildProfile $profile, string $version, string $sourceCommit, string $sha256, ?DateTimeImmutable $builtAt = null	ファイル名とすべてのプロファイル次元を導出	self	—	builtAt は現在時刻がデフォルト
ArtifactManifest::toArray	なし	JSON エンコード向けにシリアライズ	array<string, string|null>	—	enum フィールドはバッキングの文字列値にシリアライズ
BuildProfile::__construct / ::fromArray	プロファイルフィールド / array $data	1 つのアーティファクトバリアントを定義。命名、マニフェスト、プランの唯一の信頼できる情報源	インスタンス / self	fromArray: 必須フィールドの欠落または空の場合に InvalidArgumentException	必須キー: name, edition, delivery, encoding_technology, channel, php_target
BuildProfile::requiresEncoding / ::isEvaluation	なし	プロファイル次元に対する述語ヘルパー	bool	—	エンコーディングには DeliveryMode::Encoded と EncodingTechnology::IonCube の両方が必要
ArtifactNamer::format	BuildProfile $profile, string $version	nextpdf-{edition}-{delivery}-{channel}-php{target}-{version}.zip を出力	non-empty-string	—	決定的。PHP ターゲットからドットを除去（8.4 は php84 になる）
ArtifactNamer::checksumFile / ::signatureFile / ::sbomFile / ::manifestFile	string $version（manifestFile: なし）	SHA256SUMS-{v}.txt、SHA256SUMS-{v}.txt.asc、sbom-{v}.cdx.json、release-manifest.json を出力	non-empty-string	—	SBOM のファイル名は Core の SBOM ジェネレーターが書き出す CycloneDX ドキュメントと一致
PackageMapping::packageName / ::resolvePackageName	BuildProfile / LicenseEdition + LicenseChannel	nextpdf/pro または nextpdf/enterprise にマッピング。評価版チャネルは -evaluation を付加	non-empty-string	未知のエディションの場合に InvalidArgumentException	独立した評価版名前空間により、有料アーティファクトとの混在を防止
PackageMapping::distUrlPattern	BuildProfile $profile, string $version	正規のアーティファクトリポジトリ上のアーティファクトダウンロード URL を解決	non-empty-string	—	エンコード版とクリアテキスト版はパッケージ名を共有するが、dist URL は異なる
PackageMapping::accessBoundary / ::artifactOrigin / ::consumptionChannel / ::allPackageNames	BuildProfile / なし / なし / なし	境界はライセンスチャネルに従う。オリジンと消費チャネルは固定。すべての顧客向けパッケージ名	AccessBoundary / DistributionChannel / DistributionChannel / list<non-empty-string>	—	Core はプレミアムパッケージではなく、名前リストから除外
PublishingPlan::fromProfiles	array $profiles, string $version, PublishingEnvironment $environment = Staging	プロファイルごとに 2 つのターゲット（アーティファクトオリジン 1 つ、消費レイヤー 1 つ）を解決	self	—	環境は Staging がデフォルト。本番は常に明示的な選択
PublishingPlan::targetsByBoundary / ::targetsByChannel / ::packageNames	AccessBoundary / DistributionChannel / なし	解決済みターゲットに対するフィルタと列挙のヘルパー	list<PublishingTarget> / list<PublishingTarget> / list<non-empty-string>	—	packageNames はソートおよび重複排除済み
PublishingPlan::validate	なし	ターゲットが空でなく、バージョンがプランに一致し、評価版パッケージが有料境界に存在しないことを検査	エラーの list<string>。空なら有効	スローしない	いかなるアップロード手順よりも前に実行
PublishingPlan::toArray	なし	ドライラン出力とログ向けにシリアライズ	array<string, mixed>	—	target_count とパッケージリストを含む
PublishingTarget::fromProfile	BuildProfile $profile, string $version, PublishingEnvironment $environment, DistributionChannel $channel	1 つのチャネルに対するパッケージ名、アクセス境界、アーティファクトファイル名を解決	self	—	final readonly。toArray はログ向けにシリアライズ
AccessBoundary	enum: Paid, Evaluation, Internal	isCustomerFacing は Paid と Evaluation のみ true	'paid'、'evaluation'、'internal' がバッキング値	—	requiresAuthentication はすべての境界で true を返す
DistributionChannel	enum: GitHubReleases, PrivatePackagist, DirectDownload	isArtifactOrigin と isConsumptionLayer が 2 つの役割を分離	'github_releases'、'private_packagist'、'direct_download' がバッキング値	—	DirectDownload は将来の署名付き URL チャネル用に予約
EncodingTechnology	enum: IonCube, None	デリバリー形式とは別に、エンコーディングツールを命名	'ioncube'、'none' がバッキング値	—	クリアテキストのアーティファクトは常に None を報告
PublishingEnvironment	enum: Staging, Production	isCustomerFacing は Production のみ true	'staging'、'production' がバッキング値	—	Staging は内部検証用ターゲット
ReleaseStatus	enum: Built, Audited, Staged, Published, Revoked, Superseded	canPromote、nextStatus、isCustomerVisible、isTerminal がライフサイクルを型付け	nextStatus は ?self を返す	—	昇格チェーンは Built → Audited → Staged → Published。Revoked と Superseded は終端

エントリポイントのシグネチャ（ソースからの逐語）:

public static function createWithDefaults(string $version, string $sourceCommit, DateTimeImmutable $builtAt, array $artifacts = []): self

public static function fromProfile(BuildProfile $profile, string $version, string $sourceCommit, string $sha256, ?DateTimeImmutable $builtAt = null): self

public static function fromArray(array $data): self

public static function format(BuildProfile $profile, string $version): string

public static function fromProfiles(array $profiles, string $version, PublishingEnvironment $environment = PublishingEnvironment::Staging): self

public static function fromProfile(BuildProfile $profile, string $version, PublishingEnvironment $environment, DistributionChannel $channel): self

挙動の契約

• すべてのクラスは final であり、すべての値クラスは readonly です。構築によってすべての状態が確定します。このモジュールは、ファイルシステム、ネットワーク、暗号の操作を一切行いません。
• ReleaseManifest は、あるバージョンに対するイミュータブルな最上位ドキュメントです。セマンティックバージョン、ソースコミット、ビルドタイムスタンプ、アーティファクトリスト、およびオプションのサプライチェーン証跡パス（SBOM、GPG 署名、チェックサム）を保持します。そのスキーマバージョンは、追加に対してはマイナー、破壊的変更に対してはメジャーです。
• BuildProfile は、アーティファクトが何を含み、どのようにパッケージ化されるかについての唯一の信頼できる情報源です。命名、マニフェスト、プランはすべてプロファイルから導出され、二次的な構成ソースは存在しません。
• EncodingTechnology はエンコーディングツールを命名し、DeliveryMode（Licensing モジュール由来）は配信される形式を命名します。この 2 つは意図的に分離されており、クリアテキストのアーティファクトは常に EncodingTechnology::None を報告します。
• DistributionChannel は、アーティファクトのオリジン（バイナリストレージ。アップロード先）を、パッケージの消費レイヤー（composer require が読み取るレジストリ）から分離します。オリジンはバイナリを保管し、消費レイヤーはそれを指し示すメタデータを提供します。
• AccessBoundary は、Paid、Evaluation、Internal を列挙します。すべての境界が認証を必要とします。Internal のアーティファクトは CI、QA、ステージングに供され、顧客向けには決して公開されません。
• PublishingPlan::fromProfiles は、各プロファイルをちょうど 2 つのターゲット（アーティファクトオリジンターゲットと消費レイヤーターゲット）に解決します。アクセス境界はプロファイルのライセンスチャネルから導出され、有料アーティファクトと評価版アーティファクトが正しくルーティングされます。
• このプランは意図されたターゲットを記述したものであり、トランスポートではありません。実際のアップロードは周辺のリリースツールによって実行され、マニフェストはサプライチェーン証跡を記録します（ただし、それ自体が証跡を生成するわけではありません）。
• ReleaseStatus は、ライフサイクルを型付けします。Built → Audited → Staged → Published であり、Revoked と Superseded は Published からの終端出口です。顧客に可視なのは Published のみで、canPromote は Published 以降 false です。
• ReleaseManifest::validate と PublishingPlan::validate は、一貫性エラーを文字列リストとして報告し、決してスローしません。空のリストが唯一の有効な結果です。

エッジケースと失敗モード

• BuildProfile::fromArray で必須フィールドが欠落、非文字列、または空の場合: 該当フィールドを示す InvalidArgumentException。
• BuildProfile::fromArray で ioncube_expire が空または非文字列の場合: null（有効期限なし）に正規化。encode_paths と exclude_paths 内の非文字列または空のエントリは、警告なく破棄。
• PackageMapping::resolvePackageName で既知のマップ外のエディションの場合: InvalidArgumentException。
• ReleaseManifest::toJson でエンコード不能なデータの場合: JsonException。シリアライズは JSON_THROW_ON_ERROR を使用し、暗黙のフォールバックはありません。
• ReleaseManifest::validate は、空のアーティファクトリストと、バージョンまたはソースコミットがリリースと異なるアーティファクトを、エラーとして報告します。
• PublishingPlan::validate は、空のターゲットリスト、プランと乖離するターゲットバージョン、および有料境界に解決された評価版パッケージを報告します。
• ReleaseStatus::nextStatus は、Published、Revoked、Superseded から null を返します。呼び出し側は null を処理する必要があり、ラップアラウンドはありません。
• オリジンチャネルと消費レイヤーチャネルは別個のものです。composer require をアーティファクトオリジンに向けないでください。
• Internal 境界のアーティファクトは、顧客向けには決して公開されません。それを顧客チャネルにルーティングすることは、明示的なモデリングエラーです。
• このモジュールは暗号操作を一切行いません。GPG 署名とチェックサム生成は外部で行われ、ここでは参照されるのみです。

適合性

このモジュールについて、標準への適合は一切主張しません。これはリリースモデリングレイヤーであり、NextPDF はいかなる認証も保有していません。デフォルトの SBOM ファイル名（sbom-{version}.cdx.json）は、Core の SBOM ジェネレーターが書き出す CycloneDX ドキュメントと一致します。マニフェストはその証跡を参照しますが、検証はしません。GPG 署名とチェックサムは、周辺のリリースパイプラインによって生成および検証されます。証跡パスの記録はケイパビリティであって、証明ではありません。マニフェストはそれ単独では証拠にならず、来歴を証明せず、リリースを認証せず、法的助言を構成しません。

開発上の注意

• 証跡ファイル名が常に ArtifactNamer と一致するよう、ReleaseManifest::createWithDefaults を優先してください。生のコンストラクタは、意図的なパスごとの上書きのために取っておきます。
• 両方の validate() ゲートを、いかなる公開手順よりも前に CI で実行し、空でないエラーリストの場合はパイプラインを失敗させてください。
• PublishingPlan::fromProfiles は PublishingEnvironment::Staging がデフォルトです。Production は明示的に渡してください。このモジュール内には環境を暗黙的に昇格させるものはありません。
• シリアライズされたマニフェストは、enum のバッキング値（paid、encoded、ioncube など）と ATOM タイムスタンプを保持します。これらの文字列をワイヤ契約として扱ってください。
• 評価版アーティファクトは、独立したパッケージ名前空間（-evaluation サフィックス）に存在します。Composer の構成では、有料レジストリと評価版レジストリを別個に保ってください。
• チャネルごとのルーティング、認証情報、ストレージは、オペレーターの責任です。プランはツールにアーティファクトの帰属先を伝えますが、それへの認証方法は伝えません。

公開範囲

このページは、外部から観測可能な挙動とサポートされる公開 API サーフェスのみを文書化しています。内部名前空間パス、ヘルパークラス、メカニズムテーブル、ランブックのファイル名、チケットプレフィックスは対象外です。

関連項目

• リリース（ケイパビリティページ）
• ライセンシング — 詳細リファレンス — プロファイルが利用する LicenseEdition、LicenseChannel、DeliveryMode の各 enum。
• Enterprise 概要
• ライセンスアクティベーション