Release — Ausführliche Referenz

Auf einen Blick

Der Namespace NextPDF\Enterprise\Release modelliert ein Produkt-Release als unveränderliche, typisierte Wertobjekte. Seine öffentliche Oberfläche besteht aus sieben finalen Klassen und fünf string-basierten Enums. ReleaseManifest aggregiert ArtifactManifest-Einträge pro Artefakt sowie Pfade zu Lieferketten-Nachweisen. BuildProfile ist die einzige Quelle der Wahrheit für eine Artefaktvariante. ArtifactNamer und PackageMapping leiten deterministische Dateinamen und die Composer-Paketidentität aus einem Profil ab. PublishingPlan::fromProfiles löst jedes Profil zu typisierten PublishingTarget-Einträgen mit dem korrekten Kanal und der korrekten Zugriffsgrenze auf. ReleaseStatus typisiert den Release-Lebenszyklus. Das Modul führt keine I/O, keine Netzwerkaufrufe und keine Kryptografie aus; es ist reine Metadaten-Modellierung.

Verfügbarkeit & Lizenzierung

Diese Funktion wird mit NextPDF Enterprise (nextpdf/enterprise) ausgeliefert und wird durch eine Lizenzhülle der Enterprise-Stufe aktiviert. Eine Bereitstellung ohne diese Berechtigung lädt die Klassen der Funktion nicht. Editionen vergleichen und Lizenz erwerben.

Diese Oberfläche wird über die Paketgrenze nextpdf/enterprise lizenziert und besitzt keinen separaten funktionsspezifischen Capability-Code. Core und Pro liefern keine Release-Modellierungsschicht.

Öffentliche API-Oberfläche

composer require nextpdf/enterprise:^3

Symbol	Parameter	Standardverhalten	Rückgabe	Wirft oder scheitert mit	Hinweise
ReleaseManifest::__construct	version, sourceCommit, builtAt, artifacts = [], sbomPath = null, gpgSignature = null, checksumPath = null	Erstellt das unveränderliche Release-Dokument der obersten Ebene	Instanz	—	final readonly; SCHEMA_VERSION ist '1.0'; minor bei additiven Feldern, major bei brechenden Änderungen; seit 3.0.0
ReleaseManifest::createWithDefaults	string $version, string $sourceCommit, DateTimeImmutable $builtAt, array $artifacts = []	Verdrahtet die Standard-Dateinamen für SBOM, Signatur und Prüfsumme vorab über ArtifactNamer	self	—	Kanonischer Einstiegspunkt für Release-Builder; verwenden Sie den Konstruktor, um einzelne Pfade zu überschreiben
ReleaseManifest::toArray / ::toJson	keine	Serialisiert das Manifest mit allen Artefakteinträgen	array / JSON-String	toJson: JsonException bei Kodierungsfehler	Pretty-Printed, nicht escapte Schrägstriche; built_at im ATOM-Format
ReleaseManifest::validate	keine	Prüft, ob die Artefaktliste nicht leer ist und jedes Artefakt zu Version und Commit des Release passt	list<string> von Fehlern; leer bedeutet gültig	Wirft nie	Aufrufer müssen eine nicht leere Liste als Defekt behandeln
ArtifactManifest::__construct	filename, version, sourceCommit, edition, deliveryMode, encodingTechnology, channel, phpTarget, sha256, ioncubeExpire, builtAt	Erfasst ein gebautes Artefakt: was gebaut wurde, wie und wie es zu verifizieren ist	Instanz	—	final readonly; ioncubeExpire ist null für nicht ablaufende Artefakte
ArtifactManifest::fromProfile	BuildProfile $profile, string $version, string $sourceCommit, string $sha256, ?DateTimeImmutable $builtAt = null	Leitet den Dateinamen und alle Profildimensionen ab	self	—	builtAt verwendet standardmäßig die aktuelle Zeit
ArtifactManifest::toArray	keine	Serialisiert für die JSON-Kodierung	array<string, string|null>	—	Enum-Felder serialisieren zu ihren string-Backing-Werten
BuildProfile::__construct / ::fromArray	Profilfelder / array $data	Definiert eine Artefaktvariante; die einzige Quelle der Wahrheit für Benennung, Manifest und Plan	Instanz / self	fromArray: InvalidArgumentException bei fehlendem oder leerem Pflichtfeld	Erforderliche Schlüssel: name, edition, delivery, encoding_technology, channel, php_target
BuildProfile::requiresEncoding / ::isEvaluation	keine	Prädikat-Hilfsmethoden über die Profildimensionen	bool	—	Kodierung erfordert DeliveryMode::Encoded und EncodingTechnology::IonCube gemeinsam
ArtifactNamer::format	BuildProfile $profile, string $version	Gibt nextpdf-{edition}-{delivery}-{channel}-php{target}-{version}.zip aus	non-empty-string	—	Deterministisch; Punkte werden aus dem PHP-Target entfernt (8.4 wird zu php84)
ArtifactNamer::checksumFile / ::signatureFile / ::sbomFile / ::manifestFile	string $version (manifestFile: keine)	Gibt SHA256SUMS-{v}.txt, SHA256SUMS-{v}.txt.asc, sbom-{v}.cdx.json, release-manifest.json aus	non-empty-string	—	Der SBOM-Dateiname entspricht dem CycloneDX-Dokument, das der SBOM-Generator von Core schreibt
PackageMapping::packageName / ::resolvePackageName	BuildProfile / LicenseEdition + LicenseChannel	Ordnet nextpdf/pro oder nextpdf/enterprise zu; der Evaluation-Kanal hängt -evaluation an	non-empty-string	InvalidArgumentException bei unbekannter Edition	Der separate Evaluation-Namespace verhindert die Vermischung mit bezahlten Artefakten
PackageMapping::distUrlPattern	BuildProfile $profile, string $version	Löst die Artefakt-Download-URL im kanonischen Artefakt-Repository auf	non-empty-string	—	Kodiert und Klartext teilen sich einen Paketnamen; ihre Dist-URLs unterscheiden sich
PackageMapping::accessBoundary / ::artifactOrigin / ::consumptionChannel / ::allPackageNames	BuildProfile / keine / keine / keine	Die Grenze folgt dem Lizenzkanal; feste Origin- und Consumption-Kanäle; alle kundenseitigen Paketnamen	AccessBoundary / DistributionChannel / DistributionChannel / list<non-empty-string>	—	Core ist kein Premium-Paket und wird aus der Namensliste ausgeschlossen
PublishingPlan::fromProfiles	array $profiles, string $version, PublishingEnvironment $environment = Staging	Löst zwei Ziele pro Profil auf: eine Artefakt-Origin, eine Consumption-Schicht	self	—	Die Umgebung ist standardmäßig Staging; Produktion ist immer eine explizite Wahl
PublishingPlan::targetsByBoundary / ::targetsByChannel / ::packageNames	AccessBoundary / DistributionChannel / keine	Filter- und Aufzählungs-Hilfsmethoden über die aufgelösten Ziele	list<PublishingTarget> / list<PublishingTarget> / list<non-empty-string>	—	packageNames ist sortiert und dedupliziert
PublishingPlan::validate	keine	Prüft, dass die Ziele nicht leer sind, die Versionen zum Plan passen und kein Evaluation-Paket in einer bezahlten Grenze liegt	list<string> von Fehlern; leer bedeutet gültig	Wirft nie	Vor jedem Upload-Schritt ausführen
PublishingPlan::toArray	keine	Serialisiert für Dry-Run-Ausgabe und Logging	array<string, mixed>	—	Enthält target_count und die Paketliste
PublishingTarget::fromProfile	BuildProfile $profile, string $version, PublishingEnvironment $environment, DistributionChannel $channel	Löst den Paketnamen, die Zugriffsgrenze und den Artefakt-Dateinamen für einen Kanal auf	self	—	final readonly; toArray serialisiert für Logging
AccessBoundary	Enum: Paid, Evaluation, Internal	isCustomerFacing ist nur für Paid und Evaluation true	gestützt durch 'paid', 'evaluation', 'internal'	—	requiresAuthentication gibt für jede Grenze true zurück
DistributionChannel	Enum: GitHubReleases, PrivatePackagist, DirectDownload	isArtifactOrigin und isConsumptionLayer trennen die beiden Rollen	gestützt durch 'github_releases', 'private_packagist', 'direct_download'	—	DirectDownload ist für einen zukünftigen Signed-URL-Kanal reserviert
EncodingTechnology	Enum: IonCube, None	Benennt das Kodierungswerkzeug, unterschieden von der Lieferform	gestützt durch 'ioncube', 'none'	—	Ein Klartext-Artefakt meldet immer None
PublishingEnvironment	Enum: Staging, Production	isCustomerFacing ist nur für Production true	gestützt durch 'staging', 'production'	—	Staging ist ein internes Verifizierungsziel
ReleaseStatus	Enum: Built, Audited, Staged, Published, Revoked, Superseded	canPromote, nextStatus, isCustomerVisible, isTerminal typisieren den Lebenszyklus	nextStatus gibt ?self zurück	—	Promotion-Kette Built → Audited → Staged → Published; Revoked und Superseded sind terminal

Einstiegspunkt-Signaturen, wortwörtlich aus dem Quellcode:

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

Verhaltensvertrag

• Jede Klasse ist final; jede Wertklasse ist readonly. Die Konstruktion legt den gesamten Zustand fest. Das Modul führt keine Dateisystem-, Netzwerk- oder Kryptografie-Operationen aus.
• ReleaseManifest ist das unveränderliche Dokument der obersten Ebene für eine Version: semantische Version, Source-Commit, Build-Zeitstempel, Artefaktliste und optionale Pfade zu Lieferketten-Nachweisen (SBOM, GPG-Signatur, Prüfsummen). Seine Schemaversion ist minor-bei-additiv und major-bei-brechend.
• BuildProfile ist die einzige Quelle der Wahrheit dafür, was ein Artefakt enthält und wie es paketiert wird. Benennung, Manifest und Plan leiten sich alle aus dem Profil ab; es gibt keine sekundäre Konfigurationsquelle.
• EncodingTechnology benennt das Kodierungswerkzeug; DeliveryMode (aus dem Licensing-Modul) benennt die ausgelieferte Form. Beide sind bewusst getrennt, und ein Klartext-Artefakt meldet immer EncodingTechnology::None.
• DistributionChannel trennt eine Artefakt-Origin (Binärspeicher; das Upload-Ziel) von einer Paket-Consumption-Schicht (die Registry, die ein composer require liest). Die Origin speichert das Binary; die Consumption-Schicht liefert die Metadaten, die darauf verweisen.
• AccessBoundary zählt Paid, Evaluation und Internal auf. Jede Grenze erfordert Authentifizierung. Interne Artefakte dienen CI, QA und Staging und sind nie kundenseitig.
• PublishingPlan::fromProfiles löst jedes Profil zu genau zwei Zielen auf: ein Artefakt-Origin-Ziel und ein Consumption-Schicht-Ziel, wobei die Zugriffsgrenze aus dem Lizenzkanal des Profils abgeleitet wird, damit bezahlte und Evaluation-Artefakte korrekt geroutet werden.
• Der Plan beschreibt beabsichtigte Ziele, nicht den Transport. Der eigentliche Upload wird vom umgebenden Release-Tooling durchgeführt, und das Manifest erfasst Lieferketten-Nachweise — erzeugt sie aber nicht selbst.
• ReleaseStatus typisiert den Lebenszyklus: Built → Audited → Staged → Published, mit Revoked und Superseded als terminale Ausgänge aus Published. Nur Published ist kundensichtbar; canPromote ist ab Published false.
• ReleaseManifest::validate und PublishingPlan::validate melden Konsistenzfehler als String-Listen und werfen nie. Eine leere Liste ist das einzige gültige Ergebnis.

Grenzfälle & Fehlermodi

• BuildProfile::fromArray mit einem fehlenden, nicht-string oder leeren Pflichtfeld: InvalidArgumentException, das das Feld benennt.
• BuildProfile::fromArray mit einem leeren oder nicht-string ioncube_expire: normalisiert zu null (nicht ablaufend). Nicht-string oder leere Einträge in encode_paths und exclude_paths werden stillschweigend verworfen.
• PackageMapping::resolvePackageName mit einer Edition außerhalb der bekannten Zuordnung: InvalidArgumentException.
• ReleaseManifest::toJson bei nicht kodierbaren Daten: JsonException. Die Serialisierung verwendet JSON_THROW_ON_ERROR; es gibt keinen stillen Fallback.
• ReleaseManifest::validate meldet eine leere Artefaktliste sowie jedes Artefakt, dessen Version oder Source-Commit vom Release abweicht, als Fehler.
• PublishingPlan::validate meldet eine leere Zielliste, jede Zielversion, die vom Plan abweicht, und jedes Evaluation-Paket, das in eine bezahlte Grenze aufgelöst wurde.
• ReleaseStatus::nextStatus gibt bei Published, Revoked und Superseded null zurück. Aufrufer müssen null behandeln; es gibt keinen Umlauf.
• Die Origin- und Consumption-Schicht-Kanäle sind verschieden; richten Sie ein composer require nicht auf die Artefakt-Origin.
• Artefakte mit Internal-Grenze sind nie kundenseitig; sie an einen Kundenkanal zu routen ist ein expliziter Modellierungsfehler.
• Dieses Modul führt keine kryptografischen Operationen aus. GPG-Signierung und Prüfsummen-Generierung sind extern und werden hier nur referenziert.

Konformität

Für dieses Modul wird keine Normkonformität beansprucht; es ist eine Release-Modellierungsschicht, und NextPDF besitzt keine Zertifizierung. Der Standard-SBOM-Dateiname (sbom-{version}.cdx.json) entspricht dem CycloneDX-Dokument, das der SBOM-Generator von Core schreibt; das Manifest referenziert diesen Nachweis und validiert ihn nicht. GPG-Signaturen und Prüfsummen werden von der umgebenden Release-Pipeline erzeugt und verifiziert. Das Erfassen eines Nachweispfads ist Fähigkeit, nicht Bescheinigung: Ein Manifest ist für sich genommen kein Beweis, bescheinigt keine Provenienz, zertifiziert kein Release und stellt keine Rechtsberatung dar.

Entwicklungshinweise

• Bevorzugen Sie ReleaseManifest::createWithDefaults, damit die Nachweis-Dateinamen immer mit ArtifactNamer übereinstimmen. Reservieren Sie den rohen Konstruktor für bewusste pfadspezifische Überschreibungen.
• Führen Sie beide validate()-Gates in der CI vor jedem Veröffentlichungsschritt aus und lassen Sie die Pipeline bei einer nicht leeren Fehlerliste scheitern.
• PublishingPlan::fromProfiles verwendet standardmäßig PublishingEnvironment::Staging. Übergeben Sie Production explizit; nichts in diesem Modul befördert eine Umgebung implizit.
• Serialisierte Manifeste tragen Enum-Backing-Werte (paid, encoded, ioncube und so weiter) und ATOM-Zeitstempel; behandeln Sie diese Strings als Wire-Contract.
• Evaluation-Artefakte leben in einem separaten Paket-Namespace (-evaluation-Suffix). Halten Sie bezahlte und Evaluation-Registries in Ihrer Composer-Konfiguration getrennt.
• Kanalspezifisches Routing, Anmeldedaten und Speicherung liegen in der Verantwortung des Betreibers. Der Plan sagt dem Tooling, wohin ein Artefakt gehört, nicht wie man sich dabei authentifiziert.

Veröffentlichungsgrenze

Diese Seite dokumentiert ausschließlich extern beobachtbares Verhalten und die unterstützte öffentliche API-Oberfläche. Interne Namespace-Pfade, Hilfsklassen, Mechanismustabellen, Runbook-Dateinamen und Ticket-Präfixe liegen außerhalb des Geltungsbereichs.

Siehe auch

• Release (Capability-Seite)
• Licensing — Tiefenreferenz — die Enums LicenseEdition, LicenseChannel und DeliveryMode, die die Profile konsumieren.
• Enterprise-Übersicht
• Lizenzaktivierung