Release — Referensi Mendalam

Sekilas

Namespace NextPDF\Enterprise\Release memodelkan sebuah rilis produk sebagai objek nilai bertipe yang immutable. Permukaan publiknya terdiri dari tujuh kelas final dan lima enum yang didukung string. ReleaseManifest mengagregasi entri ArtifactManifest per-artefak plus jalur bukti rantai pasok. BuildProfile adalah satu-satunya sumber kebenaran untuk satu varian artefak. ArtifactNamer dan PackageMapping menurunkan nama berkas deterministik dan identitas paket Composer dari sebuah profil. PublishingPlan::fromProfiles meresolusi setiap profil menjadi entri PublishingTarget bertipe dengan channel dan batas akses yang benar. ReleaseStatus menetapkan tipe siklus hidup rilis. Modul ini tidak melakukan I/O, tidak melakukan panggilan jaringan, dan tidak melakukan kriptografi; ini murni pemodelan metadata.

Ketersediaan & lisensi

Kapabilitas ini dikirimkan dalam NextPDF Enterprise (nextpdf/enterprise) dan diaktifkan dengan envelope lisensi tier Enterprise. Sebuah deployment tanpa entitlement tersebut tidak memuat kelas-kelas kapabilitas ini. Bandingkan edisi dan dapatkan lisensi.

Permukaan ini dilisensikan oleh batas paket nextpdf/enterprise dan tidak memiliki kode kapabilitas per-fitur terpisah. Core dan Pro tidak mengirimkan lapisan pemodelan rilis.

Permukaan API publik

composer require nextpdf/enterprise:^3

Simbol	Parameter	Perilaku default	Mengembalikan	Melempar atau gagal dengan	Catatan
ReleaseManifest::__construct	version, sourceCommit, builtAt, artifacts = [], sbomPath = null, gpgSignature = null, checksumPath = null	Membangun dokumen rilis tingkat-atas yang immutable	instance	—	final readonly; SCHEMA_VERSION adalah '1.0'; minor untuk field aditif, major untuk perubahan yang memutus; sejak 3.0.0
ReleaseManifest::createWithDefaults	string $version, string $sourceCommit, DateTimeImmutable $builtAt, array $artifacts = []	Menyiapkan sebelumnya nama berkas SBOM, tanda tangan, dan checksum default via ArtifactNamer	self	—	Titik masuk kanonik untuk pembangun rilis; gunakan konstruktor untuk menimpa jalur individual
ReleaseManifest::toArray / ::toJson	tidak ada	Menserialisasi manifes dengan semua entri artefak	string array / JSON	toJson: JsonException pada kegagalan encoding	Dicetak rapi, slash tanpa escape; built_at dalam format ATOM
ReleaseManifest::validate	tidak ada	Memeriksa daftar artefak tidak kosong dan setiap artefak cocok dengan versi dan commit rilis	list<string> dari error; kosong berarti valid	Tidak pernah melempar	Pemanggil harus memperlakukan daftar yang tidak kosong sebagai cacat
ArtifactManifest::__construct	filename, version, sourceCommit, edition, deliveryMode, encodingTechnology, channel, phpTarget, sha256, ioncubeExpire, builtAt	Mencatat satu artefak yang dibangun: apa yang dibangun, bagaimana, dan bagaimana memverifikasinya	instance	—	final readonly; ioncubeExpire adalah null untuk artefak yang tidak kedaluwarsa
ArtifactManifest::fromProfile	BuildProfile $profile, string $version, string $sourceCommit, string $sha256, ?DateTimeImmutable $builtAt = null	Menurunkan nama berkas dan semua dimensi profil	self	—	builtAt default ke waktu saat ini
ArtifactManifest::toArray	tidak ada	Menserialisasi untuk encoding JSON	array<string, string|null>	—	Field enum menserialisasi ke nilai string pendukungnya
BuildProfile::__construct / ::fromArray	field profil / array $data	Mendefinisikan satu varian artefak; satu-satunya sumber kebenaran untuk penamaan, manifes, dan rencana	instance / self	fromArray: InvalidArgumentException pada field wajib yang hilang atau kosong	Kunci wajib: name, edition, delivery, encoding_technology, channel, php_target
BuildProfile::requiresEncoding / ::isEvaluation	tidak ada	Helper predikat atas dimensi profil	bool	—	Encoding memerlukan DeliveryMode::Encoded dan EncodingTechnology::IonCube bersama-sama
ArtifactNamer::format	BuildProfile $profile, string $version	Menghasilkan nextpdf-{edition}-{delivery}-{channel}-php{target}-{version}.zip	non-empty-string	—	Deterministik; titik dihapus dari target PHP (8.4 menjadi php84)
ArtifactNamer::checksumFile / ::signatureFile / ::sbomFile / ::manifestFile	string $version (manifestFile: tidak ada)	Menghasilkan SHA256SUMS-{v}.txt, SHA256SUMS-{v}.txt.asc, sbom-{v}.cdx.json, release-manifest.json	non-empty-string	—	Nama berkas SBOM cocok dengan dokumen CycloneDX yang ditulis generator SBOM core
PackageMapping::packageName / ::resolvePackageName	BuildProfile / LicenseEdition + LicenseChannel	Memetakan ke nextpdf/pro atau nextpdf/enterprise; channel evaluasi menambahkan -evaluation	non-empty-string	InvalidArgumentException pada edisi yang tidak dikenal	Namespace evaluasi terpisah mencegah pencampuran dengan artefak berbayar
PackageMapping::distUrlPattern	BuildProfile $profile, string $version	Meresolusi URL unduhan artefak pada repositori artefak kanonik	non-empty-string	—	Encoded dan cleartext berbagi nama paket; URL dist-nya berbeda
PackageMapping::accessBoundary / ::artifactOrigin / ::consumptionChannel / ::allPackageNames	BuildProfile / tidak ada / tidak ada / tidak ada	Batas mengikuti channel lisensi; channel origin dan konsumsi tetap; semua nama paket yang menghadap pelanggan	AccessBoundary / DistributionChannel / DistributionChannel / list<non-empty-string>	—	Core bukan paket premium dan dikecualikan dari daftar nama
PublishingPlan::fromProfiles	array $profiles, string $version, PublishingEnvironment $environment = Staging	Meresolusi dua target per profil: satu origin artefak, satu lapisan konsumsi	self	—	Environment default ke Staging; produksi selalu merupakan pilihan eksplisit
PublishingPlan::targetsByBoundary / ::targetsByChannel / ::packageNames	AccessBoundary / DistributionChannel / tidak ada	Helper filter dan enumerasi atas target yang diresolusi	list<PublishingTarget> / list<PublishingTarget> / list<non-empty-string>	—	packageNames diurutkan dan dide-duplikasi
PublishingPlan::validate	tidak ada	Memeriksa target tidak kosong, versi cocok dengan rencana, dan tidak ada paket evaluasi yang berada di batas berbayar	list<string> dari error; kosong berarti valid	Tidak pernah melempar	Jalankan sebelum langkah unggah apa pun
PublishingPlan::toArray	tidak ada	Menserialisasi untuk output dry-run dan logging	array<string, mixed>	—	Menyertakan target_count dan daftar paket
PublishingTarget::fromProfile	BuildProfile $profile, string $version, PublishingEnvironment $environment, DistributionChannel $channel	Meresolusi nama paket, batas akses, dan nama berkas artefak untuk satu channel	self	—	final readonly; toArray menserialisasi untuk logging
AccessBoundary	enum: Paid, Evaluation, Internal	isCustomerFacing adalah true hanya untuk Paid dan Evaluation	didukung oleh 'paid', 'evaluation', 'internal'	—	requiresAuthentication mengembalikan true untuk setiap batas
DistributionChannel	enum: GitHubReleases, PrivatePackagist, DirectDownload	isArtifactOrigin dan isConsumptionLayer membagi dua peran tersebut	didukung oleh 'github_releases', 'private_packagist', 'direct_download'	—	DirectDownload dicadangkan untuk channel signed-URL di masa depan
EncodingTechnology	enum: IonCube, None	Menamai alat encoding, berbeda dari bentuk pengiriman	didukung oleh 'ioncube', 'none'	—	Sebuah artefak cleartext selalu melaporkan None
PublishingEnvironment	enum: Staging, Production	isCustomerFacing adalah true hanya untuk Production	didukung oleh 'staging', 'production'	—	Staging adalah target verifikasi internal
ReleaseStatus	enum: Built, Audited, Staged, Published, Revoked, Superseded	canPromote, nextStatus, isCustomerVisible, isTerminal menetapkan tipe siklus hidup	nextStatus mengembalikan ?self	—	Rantai promosi Built → Audited → Staged → Published; Revoked dan Superseded adalah terminal

Tanda tangan titik masuk, verbatim dari sumber:

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

Kontrak perilaku

• Setiap kelas adalah final; setiap kelas nilai adalah readonly. Konstruksi menetapkan semua state. Modul ini tidak melakukan operasi filesystem, jaringan, atau kriptografi.
• ReleaseManifest adalah dokumen tingkat-atas yang immutable untuk sebuah versi: versi semantik, source commit, timestamp build, daftar artefak, dan jalur bukti rantai pasok opsional (SBOM, tanda tangan GPG, checksum). Versi skemanya minor-untuk-aditif dan major-untuk-memutus.
• BuildProfile adalah satu-satunya sumber kebenaran untuk apa yang dikandung sebuah artefak dan bagaimana ia dipaketkan. Penamaan, manifes, dan rencana semuanya diturunkan dari profil; tidak ada sumber konfigurasi sekunder.
• EncodingTechnology menamai alat encoding; DeliveryMode (dari modul Licensing) menamai bentuk yang dikirimkan. Keduanya sengaja dipisahkan, dan sebuah artefak cleartext selalu melaporkan EncodingTechnology::None.
• DistributionChannel memisahkan origin artefak (penyimpanan biner; tujuan unggah) dari lapisan konsumsi paket (registry yang dibaca composer require). Origin menyimpan biner; lapisan konsumsi menyajikan metadata yang menunjuk padanya.
• AccessBoundary menyebutkan Paid, Evaluation, dan Internal. Setiap batas memerlukan autentikasi. Artefak Internal melayani CI, QA, dan staging serta tidak pernah menghadap pelanggan.
• PublishingPlan::fromProfiles meresolusi setiap profil ke tepat dua target: sebuah target origin-artefak dan sebuah target lapisan-konsumsi, dengan batas akses diturunkan dari channel lisensi profil sehingga artefak berbayar dan evaluasi dirutekan dengan benar.
• Rencana bersifat deskriptif atas target yang dimaksudkan, bukan transport. Unggah sebenarnya dilakukan oleh perkakas rilis di sekitarnya, dan manifes mencatat — tetapi tidak sendiri menghasilkan — bukti rantai pasok.
• ReleaseStatus menetapkan tipe siklus hidup: Built → Audited → Staged → Published, dengan Revoked dan Superseded sebagai jalur keluar terminal dari Published. Hanya Published yang terlihat oleh pelanggan; canPromote adalah false mulai dari Published dan seterusnya.
• ReleaseManifest::validate dan PublishingPlan::validate melaporkan error konsistensi sebagai daftar string dan tidak pernah melempar. Daftar kosong adalah satu-satunya hasil yang valid.

Kasus tepi & mode kegagalan

• BuildProfile::fromArray dengan field wajib yang hilang, non-string, atau kosong: InvalidArgumentException yang menyebut field tersebut.
• BuildProfile::fromArray dengan ioncube_expire yang kosong atau non-string: dinormalisasi ke null (tidak kedaluwarsa). Entri non-string atau kosong dalam encode_paths dan exclude_paths dibuang secara diam-diam.
• PackageMapping::resolvePackageName dengan edisi di luar peta yang dikenal: InvalidArgumentException.
• ReleaseManifest::toJson pada data yang tidak dapat di-encode: JsonException. Serialisasi menggunakan JSON_THROW_ON_ERROR; tidak ada fallback diam-diam.
• ReleaseManifest::validate melaporkan daftar artefak yang kosong, dan artefak apa pun yang versi atau source commit-nya berbeda dari rilis, sebagai error.
• PublishingPlan::validate melaporkan daftar target yang kosong, target apa pun yang versinya menyimpang dari rencana, dan paket evaluasi apa pun yang diresolusi ke dalam batas berbayar.
• ReleaseStatus::nextStatus mengembalikan null dari Published, Revoked, dan Superseded. Pemanggil harus menangani null; tidak ada wrap-around.
• Channel origin dan lapisan-konsumsi berbeda; jangan arahkan composer require ke origin artefak.
• Artefak batas-Internal tidak pernah menghadap pelanggan; merutekannya ke channel pelanggan adalah kesalahan pemodelan yang eksplisit.
• Modul ini tidak melakukan operasi kriptografi. Penandatanganan GPG dan pembuatan checksum bersifat eksternal dan hanya dirujuk di sini.

Konformansi

Tidak ada klaim konformansi standar untuk modul ini; ini adalah lapisan pemodelan rilis, dan NextPDF tidak memegang sertifikasi. Nama berkas SBOM default (sbom-{version}.cdx.json) cocok dengan dokumen CycloneDX yang ditulis generator SBOM core; manifes merujuk bukti itu dan tidak memvalidasinya. Tanda tangan GPG dan checksum dihasilkan dan diverifikasi oleh pipeline rilis di sekitarnya. Mencatat sebuah jalur bukti adalah kapabilitas, bukan atestasi: sebuah manifes bukanlah bukti dengan sendirinya, tidak mengatestasi provenans, tidak mensertifikasi sebuah rilis, dan bukan merupakan nasihat hukum.

Catatan pengembangan

• Utamakan ReleaseManifest::createWithDefaults agar nama berkas bukti selalu sesuai dengan ArtifactNamer. Cadangkan konstruktor mentah untuk penimpaan per-jalur yang disengaja.
• Jalankan kedua gate validate() di CI sebelum langkah publikasi apa pun dan gagalkan pipeline pada daftar error yang tidak kosong.
• PublishingPlan::fromProfiles default ke PublishingEnvironment::Staging. Berikan Production secara eksplisit; tidak ada apa pun dalam modul ini yang mempromosikan sebuah environment secara implisit.
• Manifes terserialisasi membawa nilai pendukung enum (paid, encoded, ioncube, dan sebagainya) dan timestamp ATOM; perlakukan string tersebut sebagai kontrak wire.
• Artefak evaluasi berada di namespace paket terpisah (sufiks -evaluation). Jaga registry berbayar dan evaluasi tetap berbeda dalam konfigurasi Composer Anda.
• Perutean per-channel, kredensial, dan penyimpanan adalah tanggung jawab operator. Rencana memberi tahu perkakas di mana sebuah artefak berada, bukan bagaimana mengautentikasi ke sana.

Batas publikasi

Halaman ini mendokumentasikan hanya perilaku yang dapat diamati secara eksternal dan permukaan API publik yang didukung. Jalur namespace internal, kelas helper, tabel mekanisme, nama berkas runbook, dan prefiks tiket berada di luar cakupan.

Lihat juga

• Release (halaman kapabilitas)
• Licensing — Referensi Mendalam — enum LicenseEdition, LicenseChannel, dan DeliveryMode yang dikonsumsi profil.
• Ikhtisar Enterprise
• Aktivasi lisensi