Release — Referência Profunda

Em resumo

O namespace NextPDF\Enterprise\Release modela um release de produto como objetos de valor imutáveis e tipados. Sua superfície pública é composta por sete classes final e cinco enums com suporte em string. ReleaseManifest agrega entradas ArtifactManifest por artefato mais os caminhos de evidência da cadeia de suprimentos. BuildProfile é a única fonte de verdade para uma variante de artefato. ArtifactNamer e PackageMapping derivam nomes de arquivo determinísticos e a identidade de pacote Composer a partir de um perfil. PublishingPlan::fromProfiles resolve cada perfil em entradas PublishingTarget tipadas com o canal e o limite de acesso corretos. ReleaseStatus tipa o ciclo de vida do release. O módulo não realiza I/O, chamadas de rede nem criptografia; é modelagem de metadados pura.

Disponibilidade e licenciamento

Esta capacidade é distribuída no NextPDF Enterprise (nextpdf/enterprise) e é ativada com um envelope de licença de nível Enterprise. Uma implantação sem esse direito não carrega as classes da capacidade. Compare edições e obtenha uma licença.

Esta superfície é licenciada pelo limite do pacote nextpdf/enterprise e não tem nenhum código de capacidade por recurso separado. O Core e o Pro não incluem uma camada de modelagem de release.

Superfície de API pública

composer require nextpdf/enterprise:^3

Símbolo	Parâmetros	Comportamento padrão	Retorna	Lança ou falha com	Notas
ReleaseManifest::__construct	version, sourceCommit, builtAt, artifacts = [], sbomPath = null, gpgSignature = null, checksumPath = null	Constrói o documento de release imutável de nível superior	instância	—	final readonly; SCHEMA_VERSION é '1.0'; menor para campos aditivos, maior para quebra; desde 3.0.0
ReleaseManifest::createWithDefaults	string $version, string $sourceCommit, DateTimeImmutable $builtAt, array $artifacts = []	Pré-configura os nomes de arquivo padrão de SBOM, assinatura e checksum via ArtifactNamer	self	—	Ponto de entrada canônico para construtores de release; use o construtor para substituir caminhos individuais
ReleaseManifest::toArray / ::toJson	nenhum	Serializa o manifesto com todas as entradas de artefato	array / string JSON	toJson: JsonException em falha de codificação	Formatação legível, barras sem escape; built_at no formato ATOM
ReleaseManifest::validate	nenhum	Verifica se a lista de artefatos não está vazia e se todo artefato corresponde à versão e ao commit do release	list<string> de erros; vazia significa válido	Nunca lança	Os chamadores devem tratar uma lista não vazia como defeito
ArtifactManifest::__construct	filename, version, sourceCommit, edition, deliveryMode, encodingTechnology, channel, phpTarget, sha256, ioncubeExpire, builtAt	Registra um artefato construído: o que foi construído, como, e como verificá-lo	instância	—	final readonly; ioncubeExpire é null para artefatos sem expiração
ArtifactManifest::fromProfile	BuildProfile $profile, string $version, string $sourceCommit, string $sha256, ?DateTimeImmutable $builtAt = null	Deriva o nome de arquivo e todas as dimensões do perfil	self	—	builtAt assume por padrão o horário atual
ArtifactManifest::toArray	nenhum	Serializa para codificação JSON	array<string, string|null>	—	Campos enum serializam para seus valores string de suporte
BuildProfile::__construct / ::fromArray	campos do perfil / array $data	Define uma variante de artefato; a única fonte de verdade para nomeação, manifesto e plano	instância / self	fromArray: InvalidArgumentException em campo obrigatório ausente ou vazio	Chaves obrigatórias: name, edition, delivery, encoding_technology, channel, php_target
BuildProfile::requiresEncoding / ::isEvaluation	nenhum	Auxiliares de predicado sobre as dimensões do perfil	bool	—	A codificação exige DeliveryMode::Encoded e EncodingTechnology::IonCube em conjunto
ArtifactNamer::format	BuildProfile $profile, string $version	Emite nextpdf-{edition}-{delivery}-{channel}-php{target}-{version}.zip	non-empty-string	—	Determinístico; os pontos são removidos do PHP target (8.4 vira php84)
ArtifactNamer::checksumFile / ::signatureFile / ::sbomFile / ::manifestFile	string $version (manifestFile: nenhum)	Emite SHA256SUMS-{v}.txt, SHA256SUMS-{v}.txt.asc, sbom-{v}.cdx.json, release-manifest.json	non-empty-string	—	O nome de arquivo do SBOM corresponde ao documento CycloneDX que o gerador de SBOM do Core escreve
PackageMapping::packageName / ::resolvePackageName	BuildProfile / LicenseEdition + LicenseChannel	Mapeia para nextpdf/pro ou nextpdf/enterprise; o canal de avaliação acrescenta -evaluation	non-empty-string	InvalidArgumentException em edição desconhecida	O namespace de avaliação separado impede a mistura com artefatos pagos
PackageMapping::distUrlPattern	BuildProfile $profile, string $version	Resolve a URL de download do artefato no repositório de artefatos canônico	non-empty-string	—	Codificado e texto claro compartilham um nome de pacote; suas dist URLs diferem
PackageMapping::accessBoundary / ::artifactOrigin / ::consumptionChannel / ::allPackageNames	BuildProfile / nenhum / nenhum / nenhum	O limite segue o canal de licença; canais de origem e consumo fixos; todos os nomes de pacote voltados ao cliente	AccessBoundary / DistributionChannel / DistributionChannel / list<non-empty-string>	—	O Core não é um pacote premium e é excluído da lista de nomes
PublishingPlan::fromProfiles	array $profiles, string $version, PublishingEnvironment $environment = Staging	Resolve dois destinos por perfil: uma origem de artefato, uma camada de consumo	self	—	O ambiente assume Staging por padrão; a produção é sempre uma escolha explícita
PublishingPlan::targetsByBoundary / ::targetsByChannel / ::packageNames	AccessBoundary / DistributionChannel / nenhum	Auxiliares de filtro e enumeração sobre os destinos resolvidos	list<PublishingTarget> / list<PublishingTarget> / list<non-empty-string>	—	packageNames é ordenado e desduplicado
PublishingPlan::validate	nenhum	Verifica se os destinos não estão vazios, se as versões correspondem ao plano e se nenhum pacote de avaliação está em um limite pago	list<string> de erros; vazia significa válido	Nunca lança	Execute antes de qualquer etapa de upload
PublishingPlan::toArray	nenhum	Serializa para saída de dry-run e logging	array<string, mixed>	—	Inclui target_count e a lista de pacotes
PublishingTarget::fromProfile	BuildProfile $profile, string $version, PublishingEnvironment $environment, DistributionChannel $channel	Resolve o nome de pacote, o limite de acesso e o nome de arquivo do artefato para um canal	self	—	final readonly; toArray serializa para logging
AccessBoundary	enum: Paid, Evaluation, Internal	isCustomerFacing é true apenas para Paid e Evaluation	com suporte em 'paid', 'evaluation', 'internal'	—	requiresAuthentication retorna true para todo limite
DistributionChannel	enum: GitHubReleases, PrivatePackagist, DirectDownload	isArtifactOrigin e isConsumptionLayer separam os dois papéis	com suporte em 'github_releases', 'private_packagist', 'direct_download'	—	DirectDownload é reservado para um futuro canal de URL assinada
EncodingTechnology	enum: IonCube, None	Nomeia a ferramenta de codificação, distinta da forma de entrega	com suporte em 'ioncube', 'none'	—	Um artefato em texto claro sempre informa None
PublishingEnvironment	enum: Staging, Production	isCustomerFacing é true apenas para Production	com suporte em 'staging', 'production'	—	Staging é um destino de verificação interno
ReleaseStatus	enum: Built, Audited, Staged, Published, Revoked, Superseded	canPromote, nextStatus, isCustomerVisible, isTerminal tipam o ciclo de vida	nextStatus retorna ?self	—	Cadeia de promoção Built → Audited → Staged → Published; Revoked e Superseded são terminais

Assinaturas dos pontos de entrada, verbatim da fonte:

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 comportamento

• Toda classe é final; toda classe de valor é readonly. A construção fixa todo o estado. O módulo não realiza operações de sistema de arquivos, de rede nem criptográficas.
• ReleaseManifest é o documento imutável de nível superior para uma versão: versão semântica, commit de origem, carimbo de data/hora de build, lista de artefatos e caminhos opcionais de evidência da cadeia de suprimentos (SBOM, assinatura GPG, checksums). Sua versão de schema é menor-para-aditivo e maior-para-quebra.
• BuildProfile é a única fonte de verdade para o que um artefato contém e como é empacotado. Nomeação, manifesto e plano derivam todos do perfil; não há fonte de configuração secundária.
• EncodingTechnology nomeia a ferramenta de codificação; DeliveryMode (do módulo Licensing) nomeia a forma entregue. As duas são deliberadamente separadas, e um artefato em texto claro sempre informa EncodingTechnology::None.
• DistributionChannel separa uma origem de artefato (armazenamento de binário; o destino do upload) de uma camada de consumo de pacote (o registro que um composer require lê). A origem armazena o binário; a camada de consumo serve os metadados que apontam para ele.
• AccessBoundary enumera Paid, Evaluation e Internal. Todo limite exige autenticação. Artefatos Internal servem CI, QA e staging e nunca são voltados ao cliente.
• PublishingPlan::fromProfiles resolve cada perfil em exatamente dois destinos: um destino de origem de artefato e um destino de camada de consumo, com o limite de acesso derivado do canal de licença do perfil, de modo que artefatos pagos e de avaliação sejam roteados corretamente.
• O plano é descritivo dos destinos pretendidos, não é transporte. O upload efetivo é realizado pela ferramenta de release ao redor, e o manifesto registra — mas não produz por si só — a evidência da cadeia de suprimentos.
• ReleaseStatus tipa o ciclo de vida: Built → Audited → Staged → Published, com Revoked e Superseded como saídas terminais de Published. Apenas Published é visível ao cliente; canPromote é false a partir de Published.
• ReleaseManifest::validate e PublishingPlan::validate relatam erros de consistência como listas de string e nunca lançam. Uma lista vazia é o único resultado válido.

Casos extremos e modos de falha

• BuildProfile::fromArray com um campo obrigatório ausente, não-string ou vazio: InvalidArgumentException nomeando o campo.
• BuildProfile::fromArray com um ioncube_expire vazio ou não-string: normalizado para null (sem expiração). Entradas não-string ou vazias em encode_paths e exclude_paths são descartadas silenciosamente.
• PackageMapping::resolvePackageName com uma edição fora do mapa conhecido: InvalidArgumentException.
• ReleaseManifest::toJson sobre dados não codificáveis: JsonException. A serialização usa JSON_THROW_ON_ERROR; não há fallback silencioso.
• ReleaseManifest::validate relata como erros uma lista de artefatos vazia e qualquer artefato cuja versão ou commit de origem difira do release.
• PublishingPlan::validate relata uma lista de destinos vazia, qualquer versão de destino que divirja do plano e qualquer pacote de avaliação resolvido para um limite pago.
• ReleaseStatus::nextStatus retorna null a partir de Published, Revoked e Superseded. Os chamadores devem tratar null; não há retorno cíclico.
• Os canais de origem e de camada de consumo são distintos; não aponte um composer require para a origem de artefato.
• Artefatos de limite Internal nunca são voltados ao cliente; roteá-los para um canal de cliente é um erro de modelagem explícito.
• Este módulo não realiza nenhuma operação criptográfica. A assinatura GPG e a geração de checksums são externas e apenas referenciadas aqui.

Conformidade

Nenhuma conformidade com padrões é declarada para este módulo; ele é uma camada de modelagem de release, e o NextPDF não possui nenhuma certificação. O nome de arquivo padrão do SBOM (sbom-{version}.cdx.json) corresponde ao documento CycloneDX que o gerador de SBOM do Core escreve; o manifesto referencia essa evidência e não a valida. Assinaturas GPG e checksums são produzidos e verificados pelo pipeline de release ao redor. Registrar um caminho de evidência é capacidade, não atestação: um manifesto não é prova por si só, não atesta proveniência, não certifica um release nem constitui parecer jurídico.

Notas de desenvolvimento

• Prefira ReleaseManifest::createWithDefaults para que os nomes de arquivo de evidência sempre concordem com ArtifactNamer. Reserve o construtor bruto para substituições deliberadas por caminho.
• Execute ambos os gates validate() na CI antes de qualquer etapa de publicação e faça o pipeline falhar em uma lista de erros não vazia.
• PublishingPlan::fromProfiles assume PublishingEnvironment::Staging por padrão. Passe Production explicitamente; nada neste módulo promove um ambiente implicitamente.
• Manifestos serializados carregam valores de suporte de enum (paid, encoded, ioncube, e assim por diante) e carimbos de data/hora ATOM; trate essas strings como o contrato de fio.
• Artefatos de avaliação vivem em um namespace de pacote separado (sufixo -evaluation). Mantenha os registros pagos e de avaliação distintos na sua configuração do Composer.
• O roteamento por canal, as credenciais e o armazenamento são responsabilidade do operador. O plano informa à ferramenta onde um artefato pertence, não como autenticar-se nele.

Limite de publicação

Esta página documenta apenas o comportamento observável externamente e a superfície de API pública suportada. Caminhos de namespace internos, classes auxiliares, tabelas de mecanismos, nomes de arquivo de runbook e prefixos de tíquete estão fora de escopo.

Consulte também

• Release (página de capacidade)
• Licensing — Referência Profunda — os enums LicenseEdition, LicenseChannel e DeliveryMode que os perfis consomem.
• Visão geral do Enterprise
• Ativação de licença