Release — Référence approfondie

Vue d’ensemble

L’espace de noms NextPDF\Enterprise\Release modélise une version de produit sous forme d’objets-valeurs immuables et typés. Sa surface publique compte sept classes final et cinq enums adossés à des chaînes. ReleaseManifest agrège les entrées ArtifactManifest par artefact, ainsi que les chemins de preuves de chaîne d’approvisionnement. BuildProfile est l’unique source de vérité pour une variante d’artefact. ArtifactNamer et PackageMapping dérivent d’un profil des noms de fichiers déterministes et l’identité du paquet Composer. PublishingPlan::fromProfiles résout chaque profil en entrées PublishingTarget typées, avec le canal et la frontière d’accès corrects. ReleaseStatus type le cycle de vie de la version. Le module n’effectue aucune E/S, aucun appel réseau et aucune cryptographie ; c’est de la pure modélisation de métadonnées.

Disponibilité et licence

Cette capacité est livrée dans NextPDF Enterprise (nextpdf/enterprise) et s’active avec une enveloppe de licence de niveau Enterprise. Un déploiement sans cette habilitation ne charge pas les classes de la capacité. Comparer les éditions et obtenir une licence.

Cette surface est concédée sous licence par la frontière du paquet nextpdf/enterprise et n’a aucun code de capacité distinct par fonctionnalité. Core et Pro ne livrent aucune couche de modélisation de version.

Surface d’API publique

composer require nextpdf/enterprise:^3

Symbole	Paramètres	Comportement par défaut	Retourne	Lève ou échoue avec	Notes
ReleaseManifest::__construct	version, sourceCommit, builtAt, artifacts = [], sbomPath = null, gpgSignature = null, checksumPath = null	Construit le document de version de plus haut niveau, immuable	instance	—	final readonly ; SCHEMA_VERSION vaut '1.0' ; mineure pour les champs additifs, majeure pour une rupture ; depuis 3.0.0
ReleaseManifest::createWithDefaults	string $version, string $sourceCommit, DateTimeImmutable $builtAt, array $artifacts = []	Précâble les noms de fichiers SBOM, de signature et de somme de contrôle par défaut via ArtifactNamer	self	—	Point d’entrée canonique pour les constructeurs de version ; utilise le constructeur pour redéfinir des chemins individuels
ReleaseManifest::toArray / ::toJson	aucun	Sérialise le manifeste avec toutes les entrées d’artefact	array / chaîne JSON	toJson : JsonException en cas d’échec d’encodage	Mise en forme lisible, barres obliques non échappées ; built_at au format ATOM
ReleaseManifest::validate	aucun	Vérifie que la liste d’artefacts n’est pas vide et que chaque artefact correspond à la version et au commit de la release	list<string> d’erreurs ; vide signifie valide	Ne lève jamais	Les appelants doivent traiter une liste non vide comme un défaut
ArtifactManifest::__construct	filename, version, sourceCommit, edition, deliveryMode, encodingTechnology, channel, phpTarget, sha256, ioncubeExpire, builtAt	Enregistre un artefact construit : ce qui a été construit, comment, et comment le vérifier	instance	—	final readonly ; ioncubeExpire vaut null pour les artefacts sans expiration
ArtifactManifest::fromProfile	BuildProfile $profile, string $version, string $sourceCommit, string $sha256, ?DateTimeImmutable $builtAt = null	Dérive le nom de fichier et toutes les dimensions du profil	self	—	builtAt vaut l’heure actuelle par défaut
ArtifactManifest::toArray	aucun	Sérialise pour l’encodage JSON	array<string, string|null>	—	Les champs enum se sérialisent en leurs valeurs de chaîne sous-jacentes
BuildProfile::__construct / ::fromArray	champs du profil / array $data	Définit une variante d’artefact ; l’unique source de vérité pour le nommage, le manifeste et le plan	instance / self	fromArray : InvalidArgumentException sur un champ requis manquant ou vide	Clés requises : name, edition, delivery, encoding_technology, channel, php_target
BuildProfile::requiresEncoding / ::isEvaluation	aucun	Assistants prédicats sur les dimensions du profil	bool	—	L’encodage requiert à la fois DeliveryMode::Encoded et EncodingTechnology::IonCube
ArtifactNamer::format	BuildProfile $profile, string $version	Émet nextpdf-{edition}-{delivery}-{channel}-php{target}-{version}.zip	non-empty-string	—	Déterministe ; les points sont retirés de la cible PHP (8.4 devient php84)
ArtifactNamer::checksumFile / ::signatureFile / ::sbomFile / ::manifestFile	string $version (manifestFile : aucun)	Émet SHA256SUMS-{v}.txt, SHA256SUMS-{v}.txt.asc, sbom-{v}.cdx.json, release-manifest.json	non-empty-string	—	Le nom de fichier SBOM correspond au document CycloneDX qu’écrit le générateur de SBOM de Core
PackageMapping::packageName / ::resolvePackageName	BuildProfile / LicenseEdition + LicenseChannel	Mappe vers nextpdf/pro ou nextpdf/enterprise ; le canal d’évaluation ajoute -evaluation	non-empty-string	InvalidArgumentException sur une édition inconnue	L’espace de noms d’évaluation distinct empêche le mélange avec les artefacts payants
PackageMapping::distUrlPattern	BuildProfile $profile, string $version	Résout l’URL de téléchargement de l’artefact sur le dépôt d’artefacts canonique	non-empty-string	—	L’encodé et le clair partagent un nom de paquet ; leurs URL dist diffèrent
PackageMapping::accessBoundary / ::artifactOrigin / ::consumptionChannel / ::allPackageNames	BuildProfile / aucun / aucun / aucun	La frontière suit le canal de licence ; canaux d’origine et de consommation fixes ; tous les noms de paquets exposés au client	AccessBoundary / DistributionChannel / DistributionChannel / list<non-empty-string>	—	Core n’est pas un paquet premium et est exclu de la liste des noms
PublishingPlan::fromProfiles	array $profiles, string $version, PublishingEnvironment $environment = Staging	Résout deux cibles par profil : une origine d’artefact, une couche de consommation	self	—	L’environnement vaut Staging par défaut ; la production est toujours un choix explicite
PublishingPlan::targetsByBoundary / ::targetsByChannel / ::packageNames	AccessBoundary / DistributionChannel / aucun	Assistants de filtrage et d’énumération sur les cibles résolues	list<PublishingTarget> / list<PublishingTarget> / list<non-empty-string>	—	packageNames est trié et dédupliqué
PublishingPlan::validate	aucun	Vérifie que les cibles ne sont pas vides, que les versions correspondent au plan et qu’aucun paquet d’évaluation ne se trouve dans une frontière payante	list<string> d’erreurs ; vide signifie valide	Ne lève jamais	À exécuter avant toute étape de téléversement
PublishingPlan::toArray	aucun	Sérialise pour la sortie en simulation et la journalisation	array<string, mixed>	—	Inclut target_count et la liste des paquets
PublishingTarget::fromProfile	BuildProfile $profile, string $version, PublishingEnvironment $environment, DistributionChannel $channel	Résout le nom de paquet, la frontière d’accès et le nom de fichier d’artefact pour un canal	self	—	final readonly ; toArray sérialise pour la journalisation
AccessBoundary	enum : Paid, Evaluation, Internal	isCustomerFacing vaut true pour Paid et Evaluation uniquement	adossé à 'paid', 'evaluation', 'internal'	—	requiresAuthentication retourne true pour chaque frontière
DistributionChannel	enum : GitHubReleases, PrivatePackagist, DirectDownload	isArtifactOrigin et isConsumptionLayer séparent les deux rôles	adossé à 'github_releases', 'private_packagist', 'direct_download'	—	DirectDownload est réservé à un futur canal d’URL signée
EncodingTechnology	enum : IonCube, None	Nomme l’outil d’encodage, distinct de la forme de livraison	adossé à 'ioncube', 'none'	—	Un artefact en clair rapporte toujours None
PublishingEnvironment	enum : Staging, Production	isCustomerFacing vaut true uniquement pour Production	adossé à 'staging', 'production'	—	Staging est une cible de vérification interne
ReleaseStatus	enum : Built, Audited, Staged, Published, Revoked, Superseded	canPromote, nextStatus, isCustomerVisible, isTerminal typent le cycle de vie	nextStatus retourne ?self	—	Chaîne de promotion Built → Audited → Staged → Published ; Revoked et Superseded sont terminaux

Signatures des points d’entrée, telles quelles depuis le source :

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

Contrat de comportement

• Chaque classe est final ; chaque classe-valeur est readonly. La construction fige tout l’état. Le module n’effectue aucune opération de système de fichiers, réseau ou cryptographique.
• ReleaseManifest est le document de plus haut niveau, immuable, pour une version : version sémantique, commit source, horodatage de build, liste d’artefacts et chemins facultatifs de preuves de chaîne d’approvisionnement (SBOM, signature GPG, sommes de contrôle). Sa version de schéma est mineure-pour-additif et majeure-pour-rupture.
• BuildProfile est l’unique source de vérité pour ce qu’un artefact contient et la façon dont il est empaqueté. Le nommage, le manifeste et le plan dérivent tous du profil ; il n’existe aucune source de configuration secondaire.
• EncodingTechnology nomme l’outil d’encodage ; DeliveryMode (du module Licensing) nomme la forme livrée. Les deux sont délibérément distincts, et un artefact en clair rapporte toujours EncodingTechnology::None.
• DistributionChannel sépare une origine d’artefact (stockage binaire ; la destination de téléversement) d’une couche de consommation de paquet (le registre que lit un composer require). L’origine stocke le binaire ; la couche de consommation sert les métadonnées qui pointent vers lui.
• AccessBoundary énumère Paid, Evaluation et Internal. Chaque frontière exige une authentification. Les artefacts Internal servent la CI, la QA et le staging et ne sont jamais exposés au client.
• PublishingPlan::fromProfiles résout chaque profil en exactement deux cibles : une cible d’origine d’artefact et une cible de couche de consommation, avec la frontière d’accès dérivée du canal de licence du profil afin que les artefacts payants et d’évaluation soient routés correctement.
• Le plan est descriptif des cibles visées, non du transport. Le téléversement effectif est réalisé par l’outillage de version environnant, et le manifeste enregistre — mais ne produit pas lui-même — les preuves de chaîne d’approvisionnement.
• ReleaseStatus type le cycle de vie : Built → Audited → Staged → Published, avec Revoked et Superseded comme sorties terminales depuis Published. Seul Published est visible par le client ; canPromote vaut false à partir de Published.
• ReleaseManifest::validate et PublishingPlan::validate rapportent les erreurs de cohérence sous forme de listes de chaînes et ne lèvent jamais. Une liste vide est le seul résultat valide.

Cas limites et modes de défaillance

• BuildProfile::fromArray avec un champ requis manquant, non-chaîne ou vide : InvalidArgumentException nommant le champ.
• BuildProfile::fromArray avec un ioncube_expire vide ou non-chaîne : normalisé à null (sans expiration). Les entrées non-chaîne ou vides dans encode_paths et exclude_paths sont silencieusement écartées.
• PackageMapping::resolvePackageName avec une édition hors de la table connue : InvalidArgumentException.
• ReleaseManifest::toJson sur des données non encodables : JsonException. La sérialisation utilise JSON_THROW_ON_ERROR ; il n’existe aucun repli silencieux.
• ReleaseManifest::validate rapporte comme erreurs une liste d’artefacts vide, ainsi que tout artefact dont la version ou le commit source diffère de la release.
• PublishingPlan::validate rapporte une liste de cibles vide, toute version de cible divergeant du plan, et tout paquet d’évaluation résolu dans une frontière payante.
• ReleaseStatus::nextStatus retourne null depuis Published, Revoked et Superseded. Les appelants doivent gérer null ; il n’y a aucun rebouclage.
• Les canaux d’origine et de couche de consommation sont distincts ; ne pointe pas un composer require vers l’origine d’artefact.
• Les artefacts de la frontière Internal ne sont jamais exposés au client ; les router vers un canal client est une erreur de modélisation explicite.
• Ce module n’effectue aucune opération cryptographique. La signature GPG et la génération de sommes de contrôle sont externes et seulement référencées ici.

Conformité

Aucune conformité à des normes n’est revendiquée pour ce module ; c’est une couche de modélisation de version, et NextPDF ne détient aucune certification. Le nom de fichier SBOM par défaut (sbom-{version}.cdx.json) correspond au document CycloneDX qu’écrit le générateur de SBOM de Core ; le manifeste référence cette preuve et ne la valide pas. Les signatures GPG et les sommes de contrôle sont produites et vérifiées par le pipeline de version environnant. Enregistrer un chemin de preuve est une capacité, non une attestation : un manifeste n’est pas une preuve à lui seul, n’atteste pas la provenance, ne certifie pas une version et ne constitue pas un avis juridique.

Notes de développement

• Préfère ReleaseManifest::createWithDefaults afin que les noms de fichiers de preuve concordent toujours avec ArtifactNamer. Réserve le constructeur brut aux redéfinitions délibérées par chemin.
• Exécute les deux garde-fous validate() en CI avant toute étape de publication et fais échouer le pipeline sur une liste d’erreurs non vide.
• PublishingPlan::fromProfiles vaut PublishingEnvironment::Staging par défaut. Passe Production explicitement ; rien dans ce module ne promeut un environnement implicitement.
• Les manifestes sérialisés portent les valeurs sous-jacentes des enums (paid, encoded, ioncube, etc.) et des horodatages ATOM ; traite ces chaînes comme le contrat de transport.
• Les artefacts d’évaluation vivent dans un espace de noms de paquet distinct (suffixe -evaluation). Garde les registres payants et d’évaluation distincts dans ta configuration Composer.
• Le routage par canal, les identifiants et le stockage relèvent de la responsabilité de l’opérateur. Le plan indique à l’outillage où appartient un artefact, non comment s’y authentifier.

Frontière de publication

Cette page ne documente que le comportement observable de l’extérieur et la surface d’API publique prise en charge. Les chemins d’espace de noms internes, les classes d’assistance, les tables de mécanismes, les noms de fichiers de runbook et les préfixes de ticket sont hors périmètre.

Voir aussi

• Release (page de capacité)
• Licensing — Référence approfondie — les enums LicenseEdition, LicenseChannel et DeliveryMode que consomment les profils.
• Présentation d’Enterprise
• Activation de licence