Publicación de versiones — Referencia detallada

De un vistazo

El espacio de nombres NextPDF\Enterprise\Release modela un release de producto como objetos de valor inmutables y tipados. Su superficie pública son siete clases final y cinco enumeraciones respaldadas por cadenas. ReleaseManifest agrega entradas ArtifactManifest por artefacto, además de las rutas de evidencia de la cadena de suministro. BuildProfile es la única fuente de verdad para una variante de artefacto. ArtifactNamer y PackageMapping derivan nombres de archivo deterministas y la identidad del paquete de Composer a partir de un perfil. PublishingPlan::fromProfiles resuelve cada perfil en entradas PublishingTarget tipadas con el canal y el límite de acceso correctos. ReleaseStatus tipa el ciclo de vida del release. El módulo no realiza E/S, ni llamadas de red, ni criptografía; es puro modelado de metadatos.

Disponibilidad y licencias

Esta funcionalidad se distribuye en NextPDF Enterprise (nextpdf/enterprise) y se activa con un sobre de licencia de nivel Enterprise. Un despliegue sin ese derecho no carga las clases de la funcionalidad. Comparar ediciones y obtener una licencia.

Esta superficie se licencia mediante el límite del paquete nextpdf/enterprise y no tiene un código de funcionalidad separado por característica. Core y Pro no incluyen una capa de modelado de releases.

Superficie de API pública

composer require nextpdf/enterprise:^3

Símbolo	Parámetros	Comportamiento predeterminado	Devuelve	Lanza o falla con	Notas
ReleaseManifest::__construct	version, sourceCommit, builtAt, artifacts = [], sbomPath = null, gpgSignature = null, checksumPath = null	Construye el documento de release de nivel superior inmutable	instancia	—	final readonly; SCHEMA_VERSION es '1.0'; minor para campos aditivos, major para rupturas; desde 3.0.0
ReleaseManifest::createWithDefaults	string $version, string $sourceCommit, DateTimeImmutable $builtAt, array $artifacts = []	Preconfigura los nombres de archivo predeterminados de SBOM, firma y checksum mediante ArtifactNamer	self	—	Punto de entrada canónico para los constructores de release; usar el constructor para anular rutas individuales
ReleaseManifest::toArray / ::toJson	ninguno	Serializa el manifiesto con todas las entradas de artefacto	array / cadena JSON	toJson: JsonException si falla la codificación	Con formato legible, barras sin escapar; built_at en formato ATOM
ReleaseManifest::validate	ninguno	Comprueba que la lista de artefactos no esté vacía y que cada artefacto coincida con la versión y el commit del release	list<string> de errores; vacía significa válido	Nunca lanza	Quien la invoque debe tratar una lista no vacía como un defecto
ArtifactManifest::__construct	filename, version, sourceCommit, edition, deliveryMode, encodingTechnology, channel, phpTarget, sha256, ioncubeExpire, builtAt	Registra un artefacto compilado: qué se compiló, cómo y cómo verificarlo	instancia	—	final readonly; ioncubeExpire es null para artefactos sin caducidad
ArtifactManifest::fromProfile	BuildProfile $profile, string $version, string $sourceCommit, string $sha256, ?DateTimeImmutable $builtAt = null	Deriva el nombre de archivo y todas las dimensiones del perfil	self	—	builtAt toma por defecto la hora actual
ArtifactManifest::toArray	ninguno	Serializa para la codificación JSON	array<string, string|null>	—	Los campos de enumeración se serializan a sus valores de cadena de respaldo
BuildProfile::__construct / ::fromArray	campos de perfil / array $data	Define una variante de artefacto; la única fuente de verdad para la nomenclatura, el manifiesto y el plan	instancia / self	fromArray: InvalidArgumentException si falta un campo obligatorio o está vacío	Claves obligatorias: name, edition, delivery, encoding_technology, channel, php_target
BuildProfile::requiresEncoding / ::isEvaluation	ninguno	Ayudantes de predicado sobre las dimensiones del perfil	bool	—	La codificación requiere DeliveryMode::Encoded y EncodingTechnology::IonCube juntos
ArtifactNamer::format	BuildProfile $profile, string $version	Emite nextpdf-{edition}-{delivery}-{channel}-php{target}-{version}.zip	non-empty-string	—	Determinista; los puntos se eliminan del target de PHP (8.4 se convierte en php84)
ArtifactNamer::checksumFile / ::signatureFile / ::sbomFile / ::manifestFile	string $version (manifestFile: ninguno)	Emite SHA256SUMS-{v}.txt, SHA256SUMS-{v}.txt.asc, sbom-{v}.cdx.json, release-manifest.json	non-empty-string	—	El nombre de archivo del SBOM coincide con el documento CycloneDX que escribe el generador de SBOM de Core
PackageMapping::packageName / ::resolvePackageName	BuildProfile / LicenseEdition + LicenseChannel	Asigna a nextpdf/pro o nextpdf/enterprise; el canal de evaluación añade -evaluation	non-empty-string	InvalidArgumentException ante una edición desconocida	El espacio de nombres de evaluación separado evita mezclarse con artefactos de pago
PackageMapping::distUrlPattern	BuildProfile $profile, string $version	Resuelve la URL de descarga del artefacto en el repositorio de artefactos canónico	non-empty-string	—	El artefacto codificado y el de texto claro comparten un nombre de paquete; sus URL de dist difieren
PackageMapping::accessBoundary / ::artifactOrigin / ::consumptionChannel / ::allPackageNames	BuildProfile / ninguno / ninguno / ninguno	El límite sigue el canal de licencia; canales de origen y de consumo fijos; todos los nombres de paquete de cara al cliente	AccessBoundary / DistributionChannel / DistributionChannel / list<non-empty-string>	—	Core no es un paquete premium y se excluye de la lista de nombres
PublishingPlan::fromProfiles	array $profiles, string $version, PublishingEnvironment $environment = Staging	Resuelve dos destinos por perfil: un origen de artefacto y una capa de consumo	self	—	El entorno toma por defecto Staging; la producción es siempre una elección explícita
PublishingPlan::targetsByBoundary / ::targetsByChannel / ::packageNames	AccessBoundary / DistributionChannel / ninguno	Ayudantes de filtrado y enumeración sobre los destinos resueltos	list<PublishingTarget> / list<PublishingTarget> / list<non-empty-string>	—	packageNames está ordenada y sin duplicados
PublishingPlan::validate	ninguno	Comprueba que los destinos no estén vacíos, que las versiones coincidan con el plan y que ningún paquete de evaluación se ubique en un límite de pago	list<string> de errores; vacía significa válido	Nunca lanza	Ejecutar antes de cualquier paso de subida
PublishingPlan::toArray	ninguno	Serializa para la salida de dry-run y el registro	array<string, mixed>	—	Incluye target_count y la lista de paquetes
PublishingTarget::fromProfile	BuildProfile $profile, string $version, PublishingEnvironment $environment, DistributionChannel $channel	Resuelve el nombre del paquete, el límite de acceso y el nombre de archivo del artefacto para un canal	self	—	final readonly; toArray serializa para el registro
AccessBoundary	enum: Paid, Evaluation, Internal	isCustomerFacing es true solo para Paid y Evaluation	respaldado por 'paid', 'evaluation', 'internal'	—	requiresAuthentication devuelve true para todos los límites
DistributionChannel	enum: GitHubReleases, PrivatePackagist, DirectDownload	isArtifactOrigin e isConsumptionLayer separan los dos roles	respaldado por 'github_releases', 'private_packagist', 'direct_download'	—	DirectDownload está reservado para un futuro canal de URL firmada
EncodingTechnology	enum: IonCube, None	Nombra la herramienta de codificación, distinta de la forma de entrega	respaldado por 'ioncube', 'none'	—	Un artefacto de texto claro siempre informa None
PublishingEnvironment	enum: Staging, Production	isCustomerFacing es true solo para Production	respaldado por 'staging', 'production'	—	Staging es un destino de verificación interno
ReleaseStatus	enum: Built, Audited, Staged, Published, Revoked, Superseded	canPromote, nextStatus, isCustomerVisible, isTerminal tipan el ciclo de vida	nextStatus devuelve ?self	—	Cadena de promoción Built → Audited → Staged → Published; Revoked y Superseded son terminales

Firmas de los puntos de entrada, textuales de la fuente:

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

Contrato de comportamiento

• Cada clase es final; cada clase de valor es readonly. La construcción fija todo el estado. El módulo no realiza operaciones de sistema de archivos, de red ni criptográficas.
• ReleaseManifest es el documento de nivel superior inmutable de una versión: versión semántica, commit de origen, marca de tiempo de compilación, lista de artefactos y rutas opcionales de evidencia de la cadena de suministro (SBOM, firma GPG, checksums). Su versión de esquema es minor para aditivos y major para rupturas.
• BuildProfile es la única fuente de verdad de lo que contiene un artefacto y de cómo se empaqueta. La nomenclatura, el manifiesto y el plan derivan todos del perfil; no hay una fuente de configuración secundaria.
• EncodingTechnology nombra la herramienta de codificación; DeliveryMode (del módulo de Licensing) nombra la forma entregada. Ambas están deliberadamente separadas, y un artefacto de texto claro siempre informa EncodingTechnology::None.
• DistributionChannel separa un origen de artefacto (almacenamiento del binario; el destino de subida) de una capa de consumo de paquetes (el registro que lee un composer require). El origen almacena el binario; la capa de consumo sirve los metadatos que apuntan a él.
• AccessBoundary enumera Paid, Evaluation e Internal. Todos los límites requieren autenticación. Los artefactos internos sirven a CI, QA y staging y nunca son de cara al cliente.
• PublishingPlan::fromProfiles resuelve cada perfil en exactamente dos destinos: un destino de origen de artefacto y un destino de capa de consumo, con el límite de acceso derivado del canal de licencia del perfil para que los artefactos de pago y de evaluación se enruten correctamente.
• El plan describe los destinos previstos, no el transporte. La subida real la realiza el utillaje de release circundante, y el manifiesto registra —pero no produce por sí mismo— la evidencia de la cadena de suministro.
• ReleaseStatus tipa el ciclo de vida: Built → Audited → Staged → Published, con Revoked y Superseded como salidas terminales desde Published. Solo Published es visible para el cliente; canPromote es false a partir de Published.
• ReleaseManifest::validate y PublishingPlan::validate informan los errores de consistencia como listas de cadenas y nunca lanzan. Una lista vacía es el único resultado válido.

Casos límite y modos de fallo

• BuildProfile::fromArray con un campo obligatorio ausente, no textual o vacío: InvalidArgumentException que nombra el campo.
• BuildProfile::fromArray con un ioncube_expire vacío o no textual: se normaliza a null (sin caducidad). Las entradas no textuales o vacías en encode_paths y exclude_paths se descartan silenciosamente.
• PackageMapping::resolvePackageName con una edición fuera del mapa conocido: InvalidArgumentException.
• ReleaseManifest::toJson con datos no codificables: JsonException. La serialización usa JSON_THROW_ON_ERROR; no hay una alternativa silenciosa.
• ReleaseManifest::validate informa como errores una lista de artefactos vacía y cualquier artefacto cuya versión o commit de origen difiera del release.
• PublishingPlan::validate informa una lista de destinos vacía, cualquier versión de destino que diverja del plan y cualquier paquete de evaluación resuelto en un límite de pago.
• ReleaseStatus::nextStatus devuelve null desde Published, Revoked y Superseded. Quien la invoque debe gestionar null; no hay ciclo de retorno.
• Los canales de origen y de capa de consumo son distintos; no apuntar un composer require al origen del artefacto.
• Los artefactos con límite interno nunca son de cara al cliente; enrutarlos a un canal de cliente es un error de modelado explícito.
• Este módulo no realiza operaciones criptográficas. La firma GPG y la generación de checksums son externas y aquí solo se referencian.

Conformidad

No se reclama conformidad con ningún estándar para este módulo; es una capa de modelado de releases, y NextPDF no posee ninguna certificación. El nombre de archivo predeterminado del SBOM (sbom-{version}.cdx.json) coincide con el documento CycloneDX que escribe el generador de SBOM de Core; el manifiesto referencia esa evidencia y no la valida. Las firmas GPG y los checksums los produce y verifica el pipeline de release circundante. Registrar una ruta de evidencia es una capacidad, no una atestación: un manifiesto no es prueba por sí mismo, no atestigua la procedencia, no certifica un release y no constituye asesoramiento legal.

Notas de desarrollo

• Preferir ReleaseManifest::createWithDefaults para que los nombres de archivo de evidencia coincidan siempre con ArtifactNamer. Reservar el constructor sin procesar para anulaciones deliberadas por ruta.
• Ejecutar ambas comprobaciones validate() en CI antes de cualquier paso de publicación y hacer fallar el pipeline ante una lista de errores no vacía.
• PublishingPlan::fromProfiles toma por defecto PublishingEnvironment::Staging. Pasar Production explícitamente; nada en este módulo promueve un entorno de forma implícita.
• Los manifiestos serializados llevan valores de respaldo de enumeración (paid, encoded, ioncube, etc.) y marcas de tiempo ATOM; tratar esas cadenas como el contrato de transmisión.
• Los artefactos de evaluación residen en un espacio de nombres de paquete separado (sufijo -evaluation). Mantener distintos los registros de pago y de evaluación en la configuración de Composer.
• El enrutamiento por canal, las credenciales y el almacenamiento son responsabilidad del operador. El plan le indica al utillaje dónde pertenece un artefacto, no cómo autenticarse ante él.

Límite de publicación

Esta página documenta únicamente el comportamiento observable externamente y la superficie de API pública admitida. Las rutas de espacios de nombres internos, las clases auxiliares, las tablas de mecanismos, los nombres de archivo de runbook y los prefijos de ticket quedan fuera del alcance.

Véase también

• Release (página de funcionalidad)
• Licenciamiento — Referencia detallada — las enumeraciones LicenseEdition, LicenseChannel y DeliveryMode que consumen los perfiles.
• Visión general de Enterprise
• Activación de licencia