Release — Derinlemesine başvuru

Bir bakışta

NextPDF\Enterprise\Release ad alanı, bir ürün sürümünü değişmez, türlenmiş değer nesneleri olarak modeller. Genel yüzeyi yedi final sınıf ve beş string tabanlı enum’dan oluşur. ReleaseManifest, yapıt başına ArtifactManifest girişlerini ve tedarik zinciri kanıt yollarını bir araya toplar. BuildProfile, tek bir yapıt varyantı için tek doğruluk kaynağıdır. ArtifactNamer ve PackageMapping, bir profilden deterministik dosya adları ve Composer paket kimliği türetir. PublishingPlan::fromProfiles, her profili doğru kanal ve erişim sınırına sahip türlenmiş PublishingTarget girişlerine çözümler. ReleaseStatus, sürüm yaşam döngüsünü türler. Modül hiçbir I/O, ağ çağrısı veya kriptografi gerçekleştirmez; saf meta veri modellemesidir.

Kullanılabilirlik ve lisanslama

Bu yetenek NextPDF Enterprise (nextpdf/enterprise) içinde sevk edilir ve bir Enterprise düzeyi lisans zarfıyla etkinleşir. Bu yetkilendirmeye sahip olmayan bir dağıtım, yeteneğin sınıflarını yüklemez. Sürümleri karşılaştırın ve bir lisans alın.

Bu yüzey, nextpdf/enterprise paket sınırıyla lisanslanır ve özellik başına ayrı bir yetenek kodu yoktur. Core ve Pro, bir release-modelleme katmanı sevk etmez.

Genel API yüzeyi

composer require nextpdf/enterprise:^3

Sembol	Parametreler	Varsayılan davranış	Döndürür	Fırlatır veya şununla başarısız olur	Notlar
ReleaseManifest::__construct	version, sourceCommit, builtAt, artifacts = [], sbomPath = null, gpgSignature = null, checksumPath = null	Değişmez en üst düzey release belgesini oluşturur	örnek	—	final readonly; SCHEMA_VERSION değeri '1.0'; eklemeli alanlar için minör, bozucu değişiklikler için majör; 3.0.0 sürümünden beri
ReleaseManifest::createWithDefaults	string $version, string $sourceCommit, DateTimeImmutable $builtAt, array $artifacts = []	Varsayılan SBOM, imza ve sağlama toplamı dosya adlarını ArtifactNamer aracılığıyla önceden bağlar	self	—	Release derleyicileri için kanonik giriş noktası; tek tek yolları geçersiz kılmak için yapıcıyı kullanın
ReleaseManifest::toArray / ::toJson	yok	Bildirimi tüm yapıt girişleriyle birlikte serileştirir	array / JSON dizesi	toJson: kodlama hatasında JsonException	Düzgün biçimlendirilmiş, kaçışsız eğik çizgiler; ATOM biçiminde built_at
ReleaseManifest::validate	yok	Yapıt listesinin boş olmadığını ve her yapıtın release sürümü ve commit ile eşleştiğini denetler	hataların list<string> değeri; boş, geçerli anlamına gelir	Asla fırlatmaz	Çağıranlar, boş olmayan bir listeyi bir kusur olarak ele almalıdır
ArtifactManifest::__construct	filename, version, sourceCommit, edition, deliveryMode, encodingTechnology, channel, phpTarget, sha256, ioncubeExpire, builtAt	Derlenen bir yapıtı kaydeder: neyin derlendiği, nasıl derlendiği ve nasıl doğrulanacağı	örnek	—	final readonly; süresi dolmayan yapıtlar için ioncubeExpire değeri null’dır
ArtifactManifest::fromProfile	BuildProfile $profile, string $version, string $sourceCommit, string $sha256, ?DateTimeImmutable $builtAt = null	Dosya adını ve tüm profil boyutlarını türetir	self	—	builtAt, varsayılan olarak geçerli zamanı alır
ArtifactManifest::toArray	yok	JSON kodlaması için serileştirir	array<string, string|null>	—	Enum alanları, kendi tabanlı string değerlerine serileştirilir
BuildProfile::__construct / ::fromArray	profil alanları / array $data	Bir yapıt varyantı tanımlar; adlandırma, bildirim ve plan için tek doğruluk kaynağı	örnek / self	fromArray: eksik veya boş bir zorunlu alanda InvalidArgumentException	Zorunlu anahtarlar: name, edition, delivery, encoding_technology, channel, php_target
BuildProfile::requiresEncoding / ::isEvaluation	yok	Profil boyutları üzerinde yüklem yardımcıları	bool	—	Kodlama, DeliveryMode::Encoded ve EncodingTechnology::IonCube değerlerinin bir arada olmasını gerektirir
ArtifactNamer::format	BuildProfile $profile, string $version	nextpdf-{edition}-{delivery}-{channel}-php{target}-{version}.zip üretir	non-empty-string	—	Deterministik; noktalar PHP hedefinden çıkarılır (8.4, php84 olur)
ArtifactNamer::checksumFile / ::signatureFile / ::sbomFile / ::manifestFile	string $version (manifestFile: yok)	SHA256SUMS-{v}.txt, SHA256SUMS-{v}.txt.asc, sbom-{v}.cdx.json, release-manifest.json üretir	non-empty-string	—	SBOM dosya adı, Core’un SBOM üretecinin yazdığı CycloneDX belgesiyle eşleşir
PackageMapping::packageName / ::resolvePackageName	BuildProfile / LicenseEdition + LicenseChannel	nextpdf/pro veya nextpdf/enterprise ile eşler; değerlendirme kanalı -evaluation ekler	non-empty-string	bilinmeyen bir edition’da InvalidArgumentException	Ayrı değerlendirme ad alanı, ücretli yapıtlarla karışmayı önler
PackageMapping::distUrlPattern	BuildProfile $profile, string $version	Kanonik yapıt deposundaki yapıt indirme URL’sini çözümler	non-empty-string	—	Kodlanmış ve düz metin bir paket adını paylaşır; dist URL’leri farklıdır
PackageMapping::accessBoundary / ::artifactOrigin / ::consumptionChannel / ::allPackageNames	BuildProfile / yok / yok / yok	Sınır, lisans kanalını izler; sabit kaynak ve tüketim kanalları; müşteriye yönelik tüm paket adları	AccessBoundary / DistributionChannel / DistributionChannel / list<non-empty-string>	—	Core bir premium paket değildir ve ad listesinden dışlanır
PublishingPlan::fromProfiles	array $profiles, string $version, PublishingEnvironment $environment = Staging	Profil başına iki hedef çözümler: biri yapıt kaynağı, biri tüketim katmanı	self	—	Ortam, varsayılan olarak Staging’dir; production her zaman açık bir seçimdir
PublishingPlan::targetsByBoundary / ::targetsByChannel / ::packageNames	AccessBoundary / DistributionChannel / yok	Çözümlenen hedefler üzerinde filtreleme ve sıralama yardımcıları	list<PublishingTarget> / list<PublishingTarget> / list<non-empty-string>	—	packageNames, sıralanır ve yinelemesi kaldırılır
PublishingPlan::validate	yok	Hedeflerin boş olmadığını, sürümlerin planla eşleştiğini ve hiçbir değerlendirme paketinin ücretli bir sınırda yer almadığını denetler	hataların list<string> değeri; boş, geçerli anlamına gelir	Asla fırlatmaz	Herhangi bir yükleme adımından önce çalıştırın
PublishingPlan::toArray	yok	Kuru çalıştırma çıktısı ve günlükleme için serileştirir	array<string, mixed>	—	target_count ve paket listesini içerir
PublishingTarget::fromProfile	BuildProfile $profile, string $version, PublishingEnvironment $environment, DistributionChannel $channel	Bir kanal için paket adını, erişim sınırını ve yapıt dosya adını çözümler	self	—	final readonly; toArray, günlükleme için serileştirir
AccessBoundary	enum: Paid, Evaluation, Internal	isCustomerFacing, yalnızca Paid ve Evaluation için true’dur	'paid', 'evaluation', 'internal' ile tabanlanır	—	requiresAuthentication, her sınır için true döndürür
DistributionChannel	enum: GitHubReleases, PrivatePackagist, DirectDownload	isArtifactOrigin ve isConsumptionLayer, iki rolü ayırır	'github_releases', 'private_packagist', 'direct_download' ile tabanlanır	—	DirectDownload, gelecekteki imzalı URL kanalı için ayrılmıştır
EncodingTechnology	enum: IonCube, None	Teslim biçiminden ayrı olarak kodlama aracını adlandırır	'ioncube', 'none' ile tabanlanır	—	Bir düz metin yapıtı her zaman None bildirir
PublishingEnvironment	enum: Staging, Production	isCustomerFacing, yalnızca Production için true’dur	'staging', 'production' ile tabanlanır	—	Staging, dahilî bir doğrulama hedefidir
ReleaseStatus	enum: Built, Audited, Staged, Published, Revoked, Superseded	canPromote, nextStatus, isCustomerVisible, isTerminal, yaşam döngüsünü türler	nextStatus, ?self döndürür	—	Yükseltme zinciri Built → Audited → Staged → Published; Revoked ve Superseded sonlandırıcıdır

Giriş noktası imzaları, kaynaktan birebir:

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

Davranış sözleşmesi

• Her sınıf final’dır; her değer sınıfı readonly’dir. Yapım, tüm durumu sabitler. Modül hiçbir dosya sistemi, ağ veya kriptografik işlem gerçekleştirmez.
• ReleaseManifest, bir sürüm için değişmez en üst düzey belgedir: anlamsal sürüm, kaynak commit, derleme zaman damgası, yapıt listesi ve isteğe bağlı tedarik zinciri kanıt yolları (SBOM, GPG imzası, sağlama toplamları). Şema sürümü, eklemeli için minör ve bozucu için majördür.
• BuildProfile, bir yapıtın ne içerdiği ve nasıl paketlendiği için tek doğruluk kaynağıdır. Adlandırma, bildirim ve plan hepsi profilden türetilir; ikincil bir yapılandırma kaynağı yoktur.
• EncodingTechnology, kodlama aracını adlandırır; DeliveryMode (Licensing modülünden), teslim edilen biçimi adlandırır. İkisi bilinçli olarak ayrıdır ve bir düz metin yapıtı her zaman EncodingTechnology::None bildirir.
• DistributionChannel, bir yapıt kaynağını (ikili depolama; yükleme hedefi) bir paket tüketim katmanından (bir composer require çağrısının okuduğu kayıt defteri) ayırır. Kaynak, ikiliyi saklar; tüketim katmanı, ona işaret eden meta veriyi sunar.
• AccessBoundary, Paid, Evaluation ve Internal değerlerini sıralar. Her sınır kimlik doğrulaması gerektirir. Internal yapıtlar CI, QA ve staging’e hizmet eder ve asla müşteriye yönelik değildir.
• PublishingPlan::fromProfiles, her profili tam olarak iki hedefe çözümler: bir yapıt-kaynağı hedefi ve bir tüketim-katmanı hedefi; erişim sınırı, profilin lisans kanalından türetilir; böylece ücretli ve değerlendirme yapıtları doğru yönlendirilir.
• Plan, amaçlanan hedefleri betimler, taşımayı değil. Gerçek yükleme, çevreleyen release araçları tarafından gerçekleştirilir ve bildirim, tedarik zinciri kanıtını kaydeder — ancak kendisi üretmez.
• ReleaseStatus, yaşam döngüsünü türler: Built → Audited → Staged → Published; Revoked ve Superseded, Published’dan sonlandırıcı çıkışlardır. Yalnızca Published müşteriye görünürdür; canPromote, Published’dan itibaren false’dur.
• ReleaseManifest::validate ve PublishingPlan::validate, tutarlılık hatalarını string listeleri olarak raporlar ve asla fırlatmaz. Boş bir liste, tek geçerli sonuçtur.

Uç durumlar ve başarısızlık modları

• Eksik, string olmayan veya boş bir zorunlu alanla BuildProfile::fromArray: alanı adlandıran InvalidArgumentException.
• Boş veya string olmayan bir ioncube_expire ile BuildProfile::fromArray: null (süresi dolmayan) olarak normalleştirilir. encode_paths ve exclude_paths içindeki string olmayan veya boş girişler sessizce düşürülür.
• Bilinen haritanın dışında bir edition ile PackageMapping::resolvePackageName: InvalidArgumentException.
• Kodlanamayan veride ReleaseManifest::toJson: JsonException. Serileştirme JSON_THROW_ON_ERROR kullanır; sessiz bir geri dönüş yoktur.
• ReleaseManifest::validate, boş bir yapıt listesini ve sürümü veya kaynak commit’i release’den farklı olan herhangi bir yapıtı hata olarak raporlar.
• PublishingPlan::validate, boş bir hedef listesini, plandan sapan herhangi bir hedef sürümünü ve ücretli bir sınıra çözümlenen herhangi bir değerlendirme paketini raporlar.
• ReleaseStatus::nextStatus, Published, Revoked ve Superseded’dan null döndürür. Çağıranlar null’ı ele almalıdır; sarmalama yoktur.
• Kaynak ve tüketim-katmanı kanalları farklıdır; bir composer require çağrısını yapıt kaynağına yöneltmeyin.
• Internal-sınırlı yapıtlar asla müşteriye yönelik değildir; bunları bir müşteri kanalına yönlendirmek açık bir modelleme hatasıdır.
• Bu modül hiçbir kriptografik işlem gerçekleştirmez. GPG imzalama ve sağlama toplamı üretimi haricidir ve burada yalnızca referans alınır.

Uygunluk

Bu modül için hiçbir standart uygunluğu iddia edilmez; bir release-modelleme katmanıdır ve NextPDF hiçbir sertifikaya sahip değildir. Varsayılan SBOM dosya adı (sbom-{version}.cdx.json), Core’un SBOM üretecinin yazdığı CycloneDX belgesiyle eşleşir; bildirim, o kanıtı referans alır ve doğrulamaz. GPG imzaları ve sağlama toplamları, çevreleyen release işlem hattı tarafından üretilir ve doğrulanır. Bir kanıt yolunu kaydetmek yetenektir, beyan değil: bir bildirim tek başına kanıt değildir, köken beyan etmez, bir sürümü sertifikalandırmaz ve hukuki tavsiye oluşturmaz.

Geliştirme notları

• ReleaseManifest::createWithDefaults’ı tercih edin; böylece kanıt dosya adları her zaman ArtifactNamer ile uyumlu olur. Ham yapıcıyı, kasıtlı yol başına geçersiz kılmalar için ayırın.
• Herhangi bir yayımlama adımından önce her iki validate() geçidini CI’de çalıştırın ve boş olmayan bir hata listesinde işlem hattını başarısız kılın.
• PublishingPlan::fromProfiles, varsayılan olarak PublishingEnvironment::Staging’i alır. Production’ı açıkça geçirin; bu modülde hiçbir şey bir ortamı örtük olarak yükseltmez.
• Serileştirilmiş bildirimler enum tabanlı değerler (paid, encoded, ioncube vb.) ve ATOM zaman damgaları taşır; o stringleri tel sözleşmesi olarak ele alın.
• Değerlendirme yapıtları ayrı bir paket ad alanında (-evaluation soneki) bulunur. Composer yapılandırmanızda ücretli ve değerlendirme kayıt defterlerini ayrı tutun.
• Kanal başına yönlendirme, kimlik bilgileri ve depolama operatörün sorumluluğundadır. Plan, araçlara bir yapıtın nereye ait olduğunu söyler, ona nasıl kimlik doğrulanacağını değil.

Yayımlama sınırı

Bu sayfa yalnızca dışarıdan gözlemlenebilir davranışı ve desteklenen genel API yüzeyini belgeler. Dahilî ad alanı yolları, yardımcı sınıflar, mekanizma tabloları, runbook dosya adları ve bilet önekleri kapsam dışıdır.

Ayrıca bakınız

• Release (yetenek sayfası)
• Licensing — Derin referans — profillerin tükettiği LicenseEdition, LicenseChannel ve DeliveryMode enum’ları.
• Enterprise genel bakışı
• Lisans etkinleştirme