Release — Riferimento approfondito

In sintesi

Il namespace NextPDF\Enterprise\Release modella una release di prodotto come oggetti valore immutabili e tipizzati. La sua superficie pubblica è composta da sette classi final e cinque enum con backing di tipo stringa. ReleaseManifest aggrega le voci ArtifactManifest per-artefatto più i percorsi delle prove di supply chain. BuildProfile è l’unica fonte di verità per una variante di artefatto. ArtifactNamer e PackageMapping derivano nomi di file deterministici e l’identità del pacchetto Composer da un profilo. PublishingPlan::fromProfiles risolve ogni profilo in voci PublishingTarget tipizzate con il canale e il confine di accesso corretti. ReleaseStatus tipizza il ciclo di vita della release. Il modulo non esegue I/O, chiamate di rete né crittografia; è pura modellazione di metadati.

Disponibilità e licenza

Questa capacità è distribuita in NextPDF Enterprise (nextpdf/enterprise) e si attiva con un envelope di licenza di livello Enterprise. Un deployment privo di tale entitlement non carica le classi della capacità. Confronta le edizioni e ottieni una licenza.

Questa superficie è licenziata dal confine del pacchetto nextpdf/enterprise e non ha un codice di capacità per-funzionalità separato. Core e Pro non includono uno strato di modellazione delle release.

Superficie API pubblica

composer require nextpdf/enterprise:^3

Simbolo	Parametri	Comportamento predefinito	Restituisce	Solleva o fallisce con	Note
ReleaseManifest::__construct	version, sourceCommit, builtAt, artifacts = [], sbomPath = null, gpgSignature = null, checksumPath = null	Costruisce il documento di release immutabile di primo livello	istanza	—	final readonly; SCHEMA_VERSION è '1.0'; minor per campi additivi, major per incompatibili; since 3.0.0
ReleaseManifest::createWithDefaults	string $version, string $sourceCommit, DateTimeImmutable $builtAt, array $artifacts = []	Precollega i nomi di file predefiniti di SBOM, firma e checksum tramite ArtifactNamer	self	—	Punto di ingresso canonico per i builder di release; usare il costruttore per sovrascrivere singoli percorsi
ReleaseManifest::toArray / ::toJson	nessuno	Serializza il manifest con tutte le voci degli artefatti	array / stringa JSON	toJson: JsonException in caso di errore di codifica	Formattato leggibile, slash non-escapati; built_at in formato ATOM
ReleaseManifest::validate	nessuno	Verifica che l’elenco degli artefatti non sia vuoto e che ogni artefatto corrisponda a versione e commit della release	list<string> di errori; vuoto significa valido	Non solleva mai	I chiamanti devono trattare un elenco non vuoto come un difetto
ArtifactManifest::__construct	filename, version, sourceCommit, edition, deliveryMode, encodingTechnology, channel, phpTarget, sha256, ioncubeExpire, builtAt	Registra un artefatto costruito: cosa è stato costruito, come, e come verificarlo	istanza	—	final readonly; ioncubeExpire è null per gli artefatti senza scadenza
ArtifactManifest::fromProfile	BuildProfile $profile, string $version, string $sourceCommit, string $sha256, ?DateTimeImmutable $builtAt = null	Deriva il nome di file e tutte le dimensioni del profilo	self	—	builtAt assume come predefinito l’ora corrente
ArtifactManifest::toArray	nessuno	Serializza per la codifica JSON	array<string, string|null>	—	I campi enum si serializzano nei rispettivi valori stringa di backing
BuildProfile::__construct / ::fromArray	campi del profilo / array $data	Definisce una variante di artefatto; l’unica fonte di verità per naming, manifest e piano	istanza / self	fromArray: InvalidArgumentException su un campo obbligatorio mancante o vuoto	Chiavi obbligatorie: name, edition, delivery, encoding_technology, channel, php_target
BuildProfile::requiresEncoding / ::isEvaluation	nessuno	Helper predicato sulle dimensioni del profilo	bool	—	La codifica richiede insieme DeliveryMode::Encoded ed EncodingTechnology::IonCube
ArtifactNamer::format	BuildProfile $profile, string $version	Emette nextpdf-{edition}-{delivery}-{channel}-php{target}-{version}.zip	non-empty-string	—	Deterministico; i punti vengono rimossi dalla versione PHP di destinazione (8.4 diventa php84)
ArtifactNamer::checksumFile / ::signatureFile / ::sbomFile / ::manifestFile	string $version (manifestFile: nessuno)	Emette SHA256SUMS-{v}.txt, SHA256SUMS-{v}.txt.asc, sbom-{v}.cdx.json, release-manifest.json	non-empty-string	—	Il nome di file dell’SBOM corrisponde al documento CycloneDX scritto dal generatore SBOM di Core
PackageMapping::packageName / ::resolvePackageName	BuildProfile / LicenseEdition + LicenseChannel	Mappa a nextpdf/pro o nextpdf/enterprise; il canale evaluation aggiunge -evaluation	non-empty-string	InvalidArgumentException su un’edizione sconosciuta	Il namespace evaluation separato previene la confusione con gli artefatti paid
PackageMapping::distUrlPattern	BuildProfile $profile, string $version	Risolve l’URL di download dell’artefatto sul repository canonico degli artefatti	non-empty-string	—	Encoded e cleartext condividono un nome di pacchetto; i loro URL dist differiscono
PackageMapping::accessBoundary / ::artifactOrigin / ::consumptionChannel / ::allPackageNames	BuildProfile / nessuno / nessuno / nessuno	Il confine segue il canale della licenza; canali di origine e consumo fissi; tutti i nomi di pacchetto rivolti al cliente	AccessBoundary / DistributionChannel / DistributionChannel / list<non-empty-string>	—	Core non è un pacchetto premium ed è escluso dall’elenco dei nomi
PublishingPlan::fromProfiles	array $profiles, string $version, PublishingEnvironment $environment = Staging	Risolve due destinazioni per profilo: un’origine dell’artefatto, uno strato di consumo	self	—	L’ambiente assume come predefinito Staging; la produzione è sempre una scelta esplicita
PublishingPlan::targetsByBoundary / ::targetsByChannel / ::packageNames	AccessBoundary / DistributionChannel / nessuno	Helper di filtro ed enumerazione sulle destinazioni risolte	list<PublishingTarget> / list<PublishingTarget> / list<non-empty-string>	—	packageNames è ordinato e deduplicato
PublishingPlan::validate	nessuno	Verifica che le destinazioni non siano vuote, che le versioni corrispondano al piano e che nessun pacchetto evaluation si trovi in un confine paid	list<string> di errori; vuoto significa valido	Non solleva mai	Eseguire prima di qualsiasi passo di caricamento
PublishingPlan::toArray	nessuno	Serializza per output dry-run e logging	array<string, mixed>	—	Include target_count e l’elenco dei pacchetti
PublishingTarget::fromProfile	BuildProfile $profile, string $version, PublishingEnvironment $environment, DistributionChannel $channel	Risolve il nome del pacchetto, il confine di accesso e il nome di file dell’artefatto per un canale	self	—	final readonly; toArray serializza per il logging
AccessBoundary	enum: Paid, Evaluation, Internal	isCustomerFacing è true solo per Paid ed Evaluation	valori di backing 'paid', 'evaluation', 'internal'	—	requiresAuthentication restituisce true per ogni confine
DistributionChannel	enum: GitHubReleases, PrivatePackagist, DirectDownload	isArtifactOrigin e isConsumptionLayer separano i due ruoli	valori di backing 'github_releases', 'private_packagist', 'direct_download'	—	DirectDownload è riservato a un futuro canale con URL firmato
EncodingTechnology	enum: IonCube, None	Nomina lo strumento di codifica, distinto dalla forma di consegna	valori di backing 'ioncube', 'none'	—	Un artefatto in chiaro riporta sempre None
PublishingEnvironment	enum: Staging, Production	isCustomerFacing è true solo per Production	valori di backing 'staging', 'production'	—	Staging è una destinazione di verifica interna
ReleaseStatus	enum: Built, Audited, Staged, Published, Revoked, Superseded	canPromote, nextStatus, isCustomerVisible, isTerminal tipizzano il ciclo di vita	nextStatus restituisce ?self	—	Catena di promozione Built → Audited → Staged → Published; Revoked e Superseded sono terminali

Firme dei punti di ingresso, letterali dal sorgente:

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

Contratto di comportamento

• Ogni classe è final; ogni classe valore è readonly. La costruzione fissa tutto lo stato. Il modulo non esegue operazioni su filesystem, di rete o crittografiche.
• ReleaseManifest è il documento immutabile di primo livello per una versione: versione semantica, commit di origine, timestamp di build, elenco degli artefatti e percorsi facoltativi delle prove di supply chain (SBOM, firma GPG, checksum). La versione del suo schema è minor-per-additivo e major-per-incompatibile.
• BuildProfile è l’unica fonte di verità per ciò che un artefatto contiene e per come è impacchettato. Naming, manifest e piano derivano tutti dal profilo; non esiste una fonte di configurazione secondaria.
• EncodingTechnology nomina lo strumento di codifica; DeliveryMode (dal modulo Licensing) nomina la forma consegnata. I due sono deliberatamente separati e un artefatto in chiaro riporta sempre EncodingTechnology::None.
• DistributionChannel separa un’origine dell’artefatto (archiviazione binaria; la destinazione di caricamento) da uno strato di consumo del pacchetto (il registry che un composer require legge). L’origine archivia il binario; lo strato di consumo serve i metadati che vi puntano.
• AccessBoundary enumera Paid, Evaluation e Internal. Ogni confine richiede autenticazione. Gli artefatti Internal servono CI, QA e staging e non sono mai rivolti al cliente.
• PublishingPlan::fromProfiles risolve ogni profilo in esattamente due destinazioni: una destinazione di origine dell’artefatto e una destinazione dello strato di consumo, con il confine di accesso derivato dal canale di licenza del profilo, così che gli artefatti paid ed evaluation vengano instradati correttamente.
• Il piano è descrittivo delle destinazioni previste, non del trasporto. Il caricamento effettivo è eseguito dal tooling di release circostante e il manifest registra — ma non produce esso stesso — le prove di supply chain.
• ReleaseStatus tipizza il ciclo di vita: Built → Audited → Staged → Published, con Revoked e Superseded come uscite terminali da Published. Solo Published è visibile al cliente; canPromote è false da Published in poi.
• ReleaseManifest::validate e PublishingPlan::validate riportano gli errori di coerenza come elenchi di stringhe e non sollevano mai. Un elenco vuoto è l’unico esito valido.

Casi limite e modalità di errore

• BuildProfile::fromArray con un campo obbligatorio mancante, non-stringa o vuoto: InvalidArgumentException che nomina il campo.
• BuildProfile::fromArray con un ioncube_expire vuoto o non-stringa: normalizzato a null (senza scadenza). Le voci non-stringa o vuote in encode_paths ed exclude_paths vengono scartate silenziosamente.
• PackageMapping::resolvePackageName con un’edizione al di fuori della mappa nota: InvalidArgumentException.
• ReleaseManifest::toJson su dati non codificabili: JsonException. La serializzazione usa JSON_THROW_ON_ERROR; non esiste alcun fallback silenzioso.
• ReleaseManifest::validate riporta come errori un elenco di artefatti vuoto e qualsiasi artefatto la cui versione o commit di origine differisca dalla release.
• PublishingPlan::validate riporta un elenco di destinazioni vuoto, qualsiasi versione di destinazione divergente dal piano e qualsiasi pacchetto evaluation risolto in un confine paid.
• ReleaseStatus::nextStatus restituisce null da Published, Revoked e Superseded. I chiamanti devono gestire null; non esiste wrap-around.
• I canali di origine e dello strato di consumo sono distinti; non puntare un composer require all’origine dell’artefatto.
• Gli artefatti del confine Internal non sono mai rivolti al cliente; instradarli verso un canale cliente è un errore di modellazione esplicito.
• Questo modulo non esegue operazioni crittografiche. La firma GPG e la generazione dei checksum sono esterne e qui solo riferite.

Conformità

Non si rivendica alcuna conformità a standard per questo modulo; è uno strato di modellazione delle release e NextPDF non detiene alcuna certificazione. Il nome di file predefinito dell’SBOM (sbom-{version}.cdx.json) corrisponde al documento CycloneDX scritto dal generatore SBOM di Core; il manifest riferisce quella prova e non la convalida. Le firme GPG e i checksum sono prodotti e verificati dalla pipeline di release circostante. Registrare un percorso di prova è una capacità, non un’attestazione: un manifest non è una prova di per sé, non attesta la provenienza, non certifica una release e non costituisce consulenza legale.

Note di sviluppo

• Preferire ReleaseManifest::createWithDefaults così che i nomi di file delle prove concordino sempre con ArtifactNamer. Riservare il costruttore grezzo a sovrascritture per-percorso deliberate.
• Eseguire entrambi i gate validate() in CI prima di qualsiasi passo di pubblicazione e far fallire la pipeline in caso di elenco di errori non vuoto.
• PublishingPlan::fromProfiles assume come predefinito PublishingEnvironment::Staging. Passare Production esplicitamente; nulla in questo modulo promuove un ambiente implicitamente.
• I manifest serializzati portano valori di backing degli enum (paid, encoded, ioncube e così via) e timestamp ATOM; trattare quelle stringhe come il contratto di trasmissione.
• Gli artefatti evaluation risiedono in un namespace di pacchetto separato (suffisso -evaluation). Mantenere distinti i registry paid ed evaluation nella configurazione Composer.
• L’instradamento per-canale, le credenziali e l’archiviazione sono responsabilità dell’operatore. Il piano indica al tooling dove appartiene un artefatto, non come autenticarsi ad esso.

Confine di pubblicazione

Questa pagina documenta solo il comportamento osservabile dall’esterno e la superficie API pubblica supportata. I percorsi di namespace interni, le classi helper, le tabelle dei meccanismi, i nomi di file di runbook e i prefissi di ticket sono fuori ambito.

Vedere anche

• Release (pagina della capacità)
• Licensing — Riferimento approfondito — gli enum LicenseEdition, LicenseChannel e DeliveryMode consumati dai profili.
• Panoramica Enterprise
• Attivazione della licenza