Regras de estabilidade da SPI

Visão geral

A interface de provedor de serviços do NextPDF segue o Semantic Versioning. Cada contrato público traz uma tag @stability e uma promessa de compatibilidade retroativa. Use estas regras para decidir em quais contratos você pode confiar como dependência.

Instalação

composer require nextpdf/core:^3

Visão conceitual

A interface de provedor de serviços inclui os contratos públicos nos namespaces NextPDF\Contracts e NextPDF\Event. Um tipo só faz parte da interface quando o PHPDoc de origem traz uma tag @stability. A tag define esse limite. Um tipo sem a tag é interno, mesmo que o PHP o exponha como public.

O NextPDF segue o Semantic Versioning 2.0.0. Uma mudança incompatível em um contrato stable exige incrementar a versão major. Um novo contrato ou uma adição compatível incrementa a versão minor. Uma correção de bug incrementa a versão patch.

A tag @stability

Cada contrato declara um de três valores de estabilidade:

Tag	Significado	Regra de mudança
stable	Pronto para produção. Seguro como dependência.	Nenhuma mudança incompatível em uma versão minor ou patch. Novos métodos são adicionados apenas com um comportamento padrão ou em um novo contrato.
experimental	Utilizável, mas ainda não congelado.	A interface pode mudar em uma versão minor, após um aviso de descontinuação.
deprecated	Agendado para remoção.	O contrato indica o substituto e a versão de remoção.

O NextPDF registra a promessa de cada contrato no mapa de contratos gerado e regenera esse mapa a partir da fonte a cada versão. O texto da promessa informa a regra exata daquele contrato. Trate o PHPDoc de origem do contrato como a única fonte da verdade.

Classes de promessa de compatibilidade retroativa

O mapa de contratos registra cada promessa em uma de quatro classes:

1. Promessa de interface. “Nenhuma mudança incompatível em uma versão minor ou patch. Novos métodos apenas com uma implementação padrão.” Aplica-se à maioria das interfaces stable, incluindo FontRegistryInterface, SignerInterface, HsmSignerInterface e HtmlSecurityPolicyInterface.
2. Promessa de enum. “Nenhuma remoção de casos. Novos casos podem ser adicionados em uma versão minor.” Aplica-se a enums stable como Alignment, Orientation e OutputDestination.
3. Promessa de objeto de valor congelado. “A assinatura do construtor e as propriedades públicas estão congeladas. Novos métodos podem ser adicionados.” Aplica-se a objetos de valor como TextPreprocessResult, TextSegment e aos payloads de eventos vinculados a ele.
4. Promessa experimental. “A interface pode mudar em uma versão minor com um aviso de descontinuação.” Aplica-se a contratos experimental como DeferredSignerInterface, TimestampProviderInterface, CursorInterface e StreamingWriterInterface.

Uma classe final como EventDispatcher ou ListenerProvider congela as assinaturas de seus métodos públicos. Use composição para estender uma classe final. Não crie subclasses dela.

Contratos de streaming experimentais

CursorInterface e StreamingWriterInterface são experimental (desde a 3.1.0). O NextPDF fornece implementações de engine finais e testadas para ambos os contratos; as classes de implementação são internas e não fazem parte da superfície pública. Você consome o comportamento de streaming por meio do contrato experimental público. Na maioria dos casos, você não implementa o contrato por conta própria.

Como o contrato é experimental, sua assinatura pode mudar em uma versão minor, após um aviso de descontinuação (a promessa experimental). Fixe a versão de forma restrita ou encapsule-o atrás do seu próprio adaptador antes de depender dele em produção. Trate o contrato de streaming como um ponto de extensão em estabilização, não como um ponto congelado.

Superfície da API

Esta página não define nenhuma interface de programação de aplicações (API) de tempo de execução. A superfície relevante é a tag PHPDoc @stability em cada contrato público e o mapa de contratos regenerado que agrega a promessa de cada contrato.

Exemplo de código — Início rápido

Leia a estabilidade de um contrato a partir da fonte antes de depender dele.

<?php

declare(strict_types=1);

use ReflectionClass;

$doc = (new ReflectionClass(\NextPDF\Contracts\FontRegistryInterface::class))
    ->getDocComment();

// Look for the "@stability stable" line in the contract PHPDoc.
\assert(\is_string($doc) && \str_contains($doc, '@stability stable'));

Exemplo de código — Produção

Uma restrição de versão do Composer fixa a versão major, onde ocorrem as mudanças incompatíveis em um contrato stable.

{
    "require": {
        "nextpdf/core": "^3.0"
    }
}

Use ^3.0 para receber versões minor e patch sem nenhuma mudança incompatível em qualquer contrato stable. Fixe a versão de forma mais restrita quando você depender de um contrato experimental, porque um contrato experimental pode mudar em uma versão minor.

Casos extremos e pegadinhas

• Tag, não visibilidade. Um método PHP marcado como public não faz parte da interface de provedor de serviços, a menos que o tipo que o declara traga uma tag @stability.
• Desvio de contratos experimentais. Um contrato experimental pode mudar em uma versão minor. Fixe a versão de forma restrita ou encapsule-o atrás do seu próprio adaptador. Isso se aplica aos contratos de streaming mesmo que eles tenham implementações já distribuídas.
• Novos métodos padrão. Uma interface stable pode ganhar um método que tem um comportamento padrão. Implemente o novo método ao atualizar, para que a sua própria implementação permaneça explícita.
• Paridade entre edições. O NextPDF Pro e o NextPDF Enterprise seguem as mesmas regras. Um contrato que você usa no Core permanece válido em relação a uma implementação Premium do mesmo contrato.

Ciclo de vida da descontinuação

Um contrato passa por um ciclo de vida definido:

1. Marcação. O responsável define @stability deprecated no PHPDoc de origem e registra o substituto e a versão de remoção.
2. Aviso. A descontinuação é anunciada no changelog da versão que a marca.
3. Sobreposição. O contrato descontinuado e o seu substituto coexistem por pelo menos uma versão minor.
4. Remoção. O contrato é removido na versão major indicada. A remoção nunca acontece em uma versão minor ou patch.

Planeje uma atualização assim que um contrato for marcado como deprecated. O substituto é sempre informado.

Desempenho

Esta página define uma política. Ela não tem custo em tempo de execução.

Notas de segurança

Os contratos de assinatura são stable e seguem a promessa de interface. Um novo método em um contrato de assinatura só chega com um comportamento padrão ou em um novo contrato, de modo que uma implementação baseada em hardware não quebre em uma atualização minor. Revise o changelog antes de uma atualização major, porque uma versão major pode mudar um contrato stable.

Conformidade

Estas regras de versionamento estão em conformidade com o Semantic Versioning 2.0.0. A geração do changelog segue o Conventional Commits 1.0.0.

Contexto comercial

O NextPDF Pro e o NextPDF Enterprise seguem as mesmas regras de estabilidade da interface de provedor de serviços que o Core. Um contrato que você usa no Core permanece válido em relação à implementação Premium desse contrato, de modo que o código da sua extensão continua portável entre as edições.

Veja também

• Visão geral da criação de extensões
• Fontes personalizadas
• Gatilhos de ação e ouvintes de eventos
• Contrato de provedor KMS

Contratos e módulos relacionados

• Referência do módulo Contracts — mapa de contratos gerado e texto da promessa de cada contrato.
• Referência dos contratos de streaming — contratos de streaming experimental e suas implementações distribuídas.
• Referência dos contratos de assinatura — contratos de assinatura stable e experimental sob as mesmas regras.
• Visão geral da criação de extensões — o que cada tag @stability significa na prática.
• Gatilhos de ação e ouvintes de eventos — o dispatcher final e os payloads experimentais que estas regras governam.

O glossário define tag de estabilidade e promessa de compatibilidade retroativa. Consulte o glossário publicado para ver as definições canônicas.