Release — Diepe referentie

In één oogopslag

De namespace NextPDF\Enterprise\Release modelleert een productrelease als onveranderlijke, getypeerde value objects. Het publieke oppervlak bestaat uit zeven final classes en vijf string-backed enums. ReleaseManifest aggregeert ArtifactManifest-vermeldingen per artefact plus bewijspaden voor de toeleveringsketen. BuildProfile is de enige bron van waarheid voor één artefactvariant. ArtifactNamer en PackageMapping leiden deterministische bestandsnamen en de Composer-package-identiteit af uit een profiel. PublishingPlan::fromProfiles resolveert elk profiel naar getypeerde PublishingTarget-vermeldingen met het juiste kanaal en de juiste toegangsgrens. ReleaseStatus typeert de levenscyclus van de release. De module voert geen I/O, geen netwerkaanroepen en geen cryptografie uit; het is pure metadatamodellering.

Beschikbaarheid en licentie

Deze functionaliteit wordt geleverd in NextPDF Enterprise (nextpdf/enterprise) en wordt geactiveerd met een licentie-envelop op Enterprise-niveau. Een deployment zonder dat recht laadt de classes van deze functionaliteit niet. Vergelijk edities en vraag een licentie aan.

Dit oppervlak wordt gelicentieerd via de pakketgrens nextpdf/enterprise en heeft geen aparte capaciteitscode per functie. Core en Pro leveren geen release-modelleringslaag.

Publiek API-oppervlak

composer require nextpdf/enterprise:^3

Symbool	Parameters	Standaardgedrag	Retourneert	Gooit of faalt met	Opmerkingen
ReleaseManifest::__construct	version, sourceCommit, builtAt, artifacts = [], sbomPath = null, gpgSignature = null, checksumPath = null	Bouwt het onveranderlijke releasedocument op het hoogste niveau	instantie	—	final readonly; SCHEMA_VERSION is '1.0'; minor voor additieve velden, major voor breaking; sinds 3.0.0
ReleaseManifest::createWithDefaults	string $version, string $sourceCommit, DateTimeImmutable $builtAt, array $artifacts = []	Bedraadt vooraf de standaard SBOM-, handtekening- en checksum-bestandsnamen via ArtifactNamer	self	—	Canoniek startpunt voor release-builders; gebruik de constructor om individuele paden te overschrijven
ReleaseManifest::toArray / ::toJson	geen	Serialiseert het manifest met alle artefactvermeldingen	array / JSON-string	toJson: JsonException bij encoderingsfout	Pretty-printed, niet-escapete slashes; built_at in ATOM-formaat
ReleaseManifest::validate	geen	Controleert of de artefactlijst niet leeg is en of elk artefact overeenkomt met de releaseversie en -commit	list<string> met fouten; leeg betekent geldig	Gooit nooit	Aanroepers moeten een niet-lege lijst als een defect behandelen
ArtifactManifest::__construct	filename, version, sourceCommit, edition, deliveryMode, encodingTechnology, channel, phpTarget, sha256, ioncubeExpire, builtAt	Registreert één gebouwd artefact: wat is gebouwd, hoe, en hoe je het verifieert	instantie	—	final readonly; ioncubeExpire is null voor niet-vervallende artefacten
ArtifactManifest::fromProfile	BuildProfile $profile, string $version, string $sourceCommit, string $sha256, ?DateTimeImmutable $builtAt = null	Leidt de bestandsnaam en alle profieldimensies af	self	—	builtAt valt standaard terug op de huidige tijd
ArtifactManifest::toArray	geen	Serialiseert voor JSON-encodering	array<string, string|null>	—	Enum-velden serialiseren naar hun backing-stringwaarden
BuildProfile::__construct / ::fromArray	profielvelden / array $data	Definieert één artefactvariant; de enige bron van waarheid voor naamgeving, manifest en plan	instantie / self	fromArray: InvalidArgumentException bij een ontbrekend of leeg verplicht veld	Verplichte keys: name, edition, delivery, encoding_technology, channel, php_target
BuildProfile::requiresEncoding / ::isEvaluation	geen	Predicate-helpers over de profieldimensies	bool	—	Encodering vereist DeliveryMode::Encoded en EncodingTechnology::IonCube samen
ArtifactNamer::format	BuildProfile $profile, string $version	Genereert nextpdf-{edition}-{delivery}-{channel}-php{target}-{version}.zip	non-empty-string	—	Deterministisch; punten worden verwijderd uit de PHP-target (8.4 wordt php84)
ArtifactNamer::checksumFile / ::signatureFile / ::sbomFile / ::manifestFile	string $version (manifestFile: geen)	Genereert SHA256SUMS-{v}.txt, SHA256SUMS-{v}.txt.asc, sbom-{v}.cdx.json, release-manifest.json	non-empty-string	—	De SBOM-bestandsnaam komt overeen met het CycloneDX-document dat de SBOM-generator van Core schrijft
PackageMapping::packageName / ::resolvePackageName	BuildProfile / LicenseEdition + LicenseChannel	Mapt naar nextpdf/pro of nextpdf/enterprise; het evaluatiekanaal voegt -evaluation toe	non-empty-string	InvalidArgumentException bij een onbekende editie	De aparte evaluation-namespace voorkomt vermenging met betaalde artefacten
PackageMapping::distUrlPattern	BuildProfile $profile, string $version	Resolveert de download-URL van het artefact in het canonieke artefact-repository	non-empty-string	—	Encoded en cleartext delen een package-naam; hun dist-URL’s verschillen
PackageMapping::accessBoundary / ::artifactOrigin / ::consumptionChannel / ::allPackageNames	BuildProfile / geen / geen / geen	De grens volgt het licentiekanaal; vaste oorsprong- en consumptiekanalen; alle klantgerichte package-namen	AccessBoundary / DistributionChannel / DistributionChannel / list<non-empty-string>	—	Core is geen premium-package en wordt uitgesloten van de namenlijst
PublishingPlan::fromProfiles	array $profiles, string $version, PublishingEnvironment $environment = Staging	Resolveert twee doelen per profiel: één artefactoorsprong, één consumptielaag	self	—	De omgeving valt standaard terug op Staging; productie is altijd een expliciete keuze
PublishingPlan::targetsByBoundary / ::targetsByChannel / ::packageNames	AccessBoundary / DistributionChannel / geen	Filter- en enumeratie-helpers over de geresolveerde doelen	list<PublishingTarget> / list<PublishingTarget> / list<non-empty-string>	—	packageNames is gesorteerd en ontdubbeld
PublishingPlan::validate	geen	Controleert of de doelen niet leeg zijn, of de versies overeenkomen met het plan, en of geen enkel evaluation-package in een betaalde grens zit	list<string> met fouten; leeg betekent geldig	Gooit nooit	Voer uit vóór elke uploadstap
PublishingPlan::toArray	geen	Serialiseert voor dry-run-uitvoer en logging	array<string, mixed>	—	Bevat target_count en de package-lijst
PublishingTarget::fromProfile	BuildProfile $profile, string $version, PublishingEnvironment $environment, DistributionChannel $channel	Resolveert de package-naam, toegangsgrens en artefactbestandsnaam voor één kanaal	self	—	final readonly; toArray serialiseert voor logging
AccessBoundary	enum: Paid, Evaluation, Internal	isCustomerFacing is alleen true voor Paid en Evaluation	onderliggende waarden: 'paid', 'evaluation', 'internal'	—	requiresAuthentication retourneert true voor elke grens
DistributionChannel	enum: GitHubReleases, PrivatePackagist, DirectDownload	isArtifactOrigin en isConsumptionLayer splitsen de twee rollen	onderliggende waarden: 'github_releases', 'private_packagist', 'direct_download'	—	DirectDownload is gereserveerd voor een toekomstig signed-URL-kanaal
EncodingTechnology	enum: IonCube, None	Benoemt de encoderingstool, onderscheiden van de leveringsvorm	onderliggende waarden: 'ioncube', 'none'	—	Een cleartext-artefact rapporteert altijd None
PublishingEnvironment	enum: Staging, Production	isCustomerFacing is alleen true voor Production	onderliggende waarden: 'staging', 'production'	—	Staging is een intern verificatiedoel
ReleaseStatus	enum: Built, Audited, Staged, Published, Revoked, Superseded	canPromote, nextStatus, isCustomerVisible, isTerminal typeren de levenscyclus	nextStatus retourneert ?self	—	Promotieketen Built → Audited → Staged → Published; Revoked en Superseded zijn terminaal

Startpunt-signatures, letterlijk uit de bron:

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

Gedragscontract

• Elke class is final; elke value class is readonly. Constructie legt alle state vast. De module voert geen filesystem-, netwerk- of cryptografische bewerkingen uit.
• ReleaseManifest is het onveranderlijke document op het hoogste niveau voor een versie: semantische versie, source commit, build-tijdstempel, artefactlijst en optionele bewijspaden voor de toeleveringsketen (SBOM, GPG-handtekening, checksums). De schemaversie is minor-voor-additief en major-voor-breaking.
• BuildProfile is de enige bron van waarheid voor wat een artefact bevat en hoe het wordt verpakt. Naamgeving, manifest en plan worden allemaal afgeleid uit het profiel; er is geen secundaire configuratiebron.
• EncodingTechnology benoemt de encoderingstool; DeliveryMode (uit de Licensing-module) benoemt de geleverde vorm. De twee zijn bewust gescheiden, en een cleartext-artefact rapporteert altijd EncodingTechnology::None.
• DistributionChannel scheidt een artefactoorsprong (binaire opslag; de uploadbestemming) van een pakketconsumptielaag (het register dat een composer require leest). De oorsprong slaat de binary op; de consumptielaag levert de metadata die ernaar verwijst.
• AccessBoundary somt Paid, Evaluation en Internal op. Elke grens vereist authenticatie. Internal-artefacten bedienen CI, QA en staging en zijn nooit klantgericht.
• PublishingPlan::fromProfiles resolveert elk profiel naar precies twee doelen: een artefactoorsprong-doel en een consumptielaag-doel, met de toegangsgrens afgeleid uit het licentiekanaal van het profiel zodat betaalde en evaluatie-artefacten correct worden gerouteerd.
• Het plan is beschrijvend voor de beoogde doelen, niet voor transport. De werkelijke upload wordt uitgevoerd door de omringende release-tooling, en het manifest registreert — maar produceert zelf niet — het bewijs voor de toeleveringsketen.
• ReleaseStatus typeert de levenscyclus: Built → Audited → Staged → Published, met Revoked en Superseded als terminale uitgangen vanuit Published. Alleen Published is zichtbaar voor de klant; canPromote is false vanaf Published.
• ReleaseManifest::validate en PublishingPlan::validate rapporteren consistentiefouten als stringlijsten en gooien nooit. Een lege lijst is de enige geldige uitkomst.

Randgevallen en faalmodi

• BuildProfile::fromArray met een ontbrekend, niet-string of leeg verplicht veld: InvalidArgumentException die het veld benoemt.
• BuildProfile::fromArray met een lege of niet-string ioncube_expire: genormaliseerd naar null (niet-vervallend). Niet-string of lege vermeldingen in encode_paths en exclude_paths worden stil weggelaten.
• PackageMapping::resolvePackageName met een editie buiten de bekende map: InvalidArgumentException.
• ReleaseManifest::toJson op niet-encodeerbare data: JsonException. Serialisatie gebruikt JSON_THROW_ON_ERROR; er is geen stille fallback.
• ReleaseManifest::validate rapporteert een lege artefactlijst, en elk artefact waarvan de versie of source commit afwijkt van de release, als fouten.
• PublishingPlan::validate rapporteert een lege doellijst, elke doelversie die afwijkt van het plan, en elk evaluation-package dat in een betaalde grens is geresolveerd.
• ReleaseStatus::nextStatus retourneert null vanuit Published, Revoked en Superseded. Aanroepers moeten null afhandelen; er is geen wrap-around.
• De oorsprong- en consumptielaag-kanalen zijn onderscheiden; richt een composer require niet op de artefactoorsprong.
• Internal-boundary-artefacten zijn nooit klantgericht; ze naar een klantkanaal routeren is een expliciete modelleringsfout.
• Deze module voert geen cryptografische bewerkingen uit. GPG-ondertekening en checksum-generatie zijn extern en worden hier alleen gerefereerd.

Conformiteit

Er wordt voor deze module geen conformiteit met standaarden geclaimd; het is een release-modelleringslaag, en NextPDF houdt geen certificering. De standaard SBOM-bestandsnaam (sbom-{version}.cdx.json) komt overeen met het CycloneDX-document dat de SBOM-generator van Core schrijft; het manifest refereert dat bewijs en valideert het niet. GPG-handtekeningen en checksums worden geproduceerd en geverifieerd door de omringende release-pijplijn. Het registreren van een bewijspad is een capaciteit, geen attestatie: een manifest is op zichzelf geen bewijs, attesteert geen herkomst, certificeert geen release en vormt geen juridisch advies.

Ontwikkelnotities

• Geef de voorkeur aan ReleaseManifest::createWithDefaults zodat de bewijsbestandsnamen altijd overeenkomen met ArtifactNamer. Reserveer de kale constructor voor bewuste overschrijvingen per pad.
• Voer beide validate()-gates uit in CI vóór elke publicatiestap en laat de pijplijn falen bij een niet-lege foutenlijst.
• PublishingPlan::fromProfiles valt standaard terug op PublishingEnvironment::Staging. Geef Production expliciet mee; niets in deze module promoveert een omgeving impliciet.
• Geserialiseerde manifesten dragen enum-backing-waarden (paid, encoded, ioncube, enzovoort) en ATOM-tijdstempels; behandel die strings als het wire-contract.
• Evaluation-artefacten leven in een aparte package-namespace (-evaluation-suffix). Houd betaalde en evaluation-registers gescheiden in je Composer-configuratie.
• Routering, referenties en opslag per kanaal vallen onder de verantwoordelijkheid van de operator. Het plan vertelt de tooling waar een artefact thuishoort, niet hoe je je daar authenticeert.

Publicatiegrens

Deze pagina documenteert alleen extern waarneembaar gedrag en het ondersteunde publieke API-oppervlak. Interne namespace-paden, helper-classes, mechanismetabellen, runbook-bestandsnamen en ticketprefixen vallen buiten scope.

Zie ook

• Release (capaciteitspagina)
• Licensing — Diepe referentie — de enums LicenseEdition, LicenseChannel en DeliveryMode die de profielen consumeren.
• Enterprise-overzicht
• Licentieactivering