Branding — Referência Profunda

Visão geral

Esta página é a referência detalhada do módulo NextPDF\Enterprise\Branding. O módulo marca a saída de avaliação e deixa a saída paga intacta. Um BrandingMode resolvido pela licença seleciona uma estratégia; o BrandingApplicator aplica a estratégia resolvida aos bytes do PDF renderizado. Sob uma licença paga, a transformação é a identidade: a saída fica byte a byte inalterada, sem exigir nenhuma alteração de código. Para o fluxo de trabalho de avaliação, leia primeiro a página de capacidade Branding.

Disponibilidade e licenciamento

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

O subsistema carrega o código de capacidade dedicado enterprise.branding porque rege o comportamento de avaliação em todas as edições. O modo de branding é resolvido a partir do envelope de licença assinado em tempo de execução; nenhuma flag da aplicação o seleciona. Uma licença paga resolve o modo para None e nunca produz saída com branding. Não há build de produção a alternar.

Superfície pública de API

Symbol	Parameters	Default behavior	Returns	Throws or fails with	Notes
BrandingMode	—	None ('none'): nenhuma modificação	—	—	Enum baseado em string; EvaluationWatermark ('evaluation') ativa o branding de avaliação.
BrandingStrategy	—	Contrato consumido pelos pontos de integração	—	—	Interface; os chamadores nunca ramificam diretamente em BrandingMode.
BrandingStrategy::isActive	—	false para a estratégia nula, true para a estratégia de avaliação	bool	—	false significa que todos os outros métodos retornam valores de identidade.
BrandingStrategy::buildPageWatermark	float $pageWidth, float $pageHeight (points)	String vazia quando inativa; operadores de marca d’água diagonal quando ativa	string	—	O stream assume um recurso de fonte /helvetica na página.
BrandingStrategy::decorateProducer	string $producer	Identidade quando inativa; acrescenta o sufixo de avaliação quando ativa	string	—	Sufixo padrão: [EVALUATION].
BrandingStrategy::decorateSubject	string $subject	Identidade quando inativa; prefixa o prefixo de avaliação quando ativa	string	—	Um subject vazio produz o marcador aparado.
BrandingStrategyFactory::create	BrandingMode $mode, ?EvaluationBrandingConfig $config = null	Mapeia None para NullBrandingStrategy, EvaluationWatermark para EvaluationBrandingStrategy	BrandingStrategy	—	Estático; config null usa os padrões.
EvaluationBrandingConfig::__construct	Seis parâmetros nomeados opcionais (text, suffix, prefix, size, gray, angle)	Padrões: 48 pt, gray 0.85, 45 graus	Instância	InvalidArgumentException em texto vazio, tamanho de fonte não positivo ou gray fora de 0.0–1.0	final readonly; imutável.
EvaluationBrandingStrategy	EvaluationBrandingConfig opcional	Aplica marca d’água e decoração de metadados	—	—	final readonly; implementa BrandingStrategy.
NullBrandingStrategy	—	Identidade em todos os métodos	—	—	Selecionada sob uma licença paga.
BrandingApplicator::apply	string $pdfBytes, BrandingStrategy $strategy	Estratégia inativa: entrada retornada byte a byte; ativa: uma atualização incremental acrescentada	string	BrandingApplicationException quando o branding ativo não pode ser aplicado com segurança	Transformação de bytes pura e determinística.
BrandingApplicationException	—	Sinal de falha terminal, fail-closed	—	—	Carrega SPEC_CODE (SPEC-BRANDING-UNAPPLICABLE); factory unsupportedStructure().

Assinaturas dos pontos de entrada

enum BrandingMode: string
{
    case None = 'none';
    case EvaluationWatermark = 'evaluation';
}

public static function create(
    BrandingMode $mode,
    ?EvaluationBrandingConfig $config = null,
): BrandingStrategy

public function __construct(
    public string $watermarkText = 'EVALUATION COPY — Not for Production Use',
    public string $producerSuffix = ' [EVALUATION]',
    public string $subjectPrefix = '[EVALUATION] ',
    public float $watermarkFontSize = 48.0,
    public float $watermarkGray = 0.85,
    public float $watermarkAngle = 45.0,
)

public function apply(string $pdfBytes, BrandingStrategy $strategy): string

Contrato de comportamento

Resolução de modo e estratégia. O estado da licença — não o código da aplicação — seleciona o BrandingMode. BrandingStrategyFactory::create mapeia None para NullBrandingStrategy e EvaluationWatermark para EvaluationBrandingStrategy. Os pontos de integração consomem a interface BrandingStrategy e nunca inspecionam o modo diretamente, de modo que a lógica de branding permanece centralizada. Sob uma licença paga, a estratégia nula é selecionada e a saída é idêntica à saída produzida sem nenhum subsistema de branding.

Geração da marca d’água. buildPageWatermark emite operadores de content stream do PDF para uma página: um estado gráfico isolado (q/Q), a fonte standard-14 Helvetica via o nome de recurso /helvetica, o modo de renderização de texto de preenchimento e uma matriz de rotação que posiciona o texto diagonalmente pelo centro da página. O estilo padrão é texto de 48 pt em nível de cinza 0.85, rotacionado 45 graus. A centralização aproxima a largura do texto pela contagem de glifos — clusters de grafemas quando o intl está carregado, code points Unicode via mbstring caso contrário, comprimento em bytes como fallback final. Nenhuma largura de avanço por glifo é consultada, por design. O texto da marca d’água é escapado como uma string literal do PDF conforme a ISO 32000-2:2020 §7.3.4.2 (barra invertida e parênteses).

Decoração de metadados. decorateProducer acrescenta o sufixo de produtor ao valor /Producer. decorateSubject prefixa o prefixo de subject ao valor /Subject; um subject vazio produz o marcador aparado, de modo que um documento sem metadados de subject ainda é marcado.

Aplicação de bytes. BrandingApplicator::apply é o consumidor terminal do controle de branding. Com uma estratégia inativa, ele retorna a entrada byte a byte. Com uma estratégia ativa, ele acrescenta uma única atualização incremental na forma definida pela ISO 32000-2:2020 §7.5.6: os bytes originais permanecem intactos, e o corpo acrescentado contém um objeto Info decorado (reutilizando o número de objeto existente), um content stream de marca d’água mais um objeto de página atualizado por página, e um novo cross-reference stream (/Type /XRef, /W [1 4 2]) cujo /Prev aponta de volta para o startxref anterior. A transformação é pura e determinística para uma dada entrada e configuração.

Contrato fail-closed. Quando a estratégia está ativa, a entrada precisa ser marcável: um cabeçalho %PDF-, nenhuma entrada /Encrypt, nenhum object stream (/ObjStm), uma cauda de cross-reference-stream e um recurso de fonte /helvetica resolvível a partir de cada página. Qualquer violação levanta BrandingApplicationException em vez de retornar bytes sem branding. Os chamadores precisam tratar a exceção como terminal e não devem confirmar os bytes originais, sem marcação.

Casos extremos e modos de falha

• Saída com branding significa que o estado da licença é do tipo avaliação. Isso reflete o estado da licença, não um defeito.
• A marca d’água é centralizada e diagonal por design. Ela não é ajustável para uso em produção; uma licença paga a remove totalmente.
• EvaluationBrandingConfig rejeita texto de marca d’água vazio, um tamanho de fonte não positivo e um nível de cinza fora de 0.0–1.0 com InvalidArgumentException.
• Uma estratégia ativa que não produz nenhuma alteração de Producer, Subject ou marca d’água é recusada com BrandingApplicationException em vez de emitir bytes que pareçam pagos.
• Uma página sem um /MediaBox utilizável (ausente ou herdado) recebe a marca d’água no padrão ISO 216 A4 de 595.276 × 841.890 points.
• /Contents nas formas de referência única e de array são ambos suportados; a referência da marca d’água é acrescentada por último para que ela seja desenhada por cima. Uma página sem /Contents recebe um.
• Os valores de string do Info fazem round-trip em sua representação original: strings hexadecimais (UTF-16BE) permanecem hexadecimais, strings literais permanecem literais. Uma chave ausente é acrescentada, codificada em hex quando o valor contém caracteres não ASCII.
• Documentos criptografados são recusados: reescrever objetos de string sob /Encrypt exigiria a chave de criptografia do documento.
• As falhas carregam o código estável SPEC-BRANDING-UNAPPLICABLE (BrandingApplicationException::SPEC_CODE) para que os pipelines consumidores possam fazer dead-letter e auditar a saída não marcável.
• O módulo não realiza nenhuma operação criptográfica. A verificação da assinatura do envelope de licença pertence ao subsistema de licenciamento; consulte a referência detalhada de Licenciamento.

Conformidade

Claim	Standard	Clause
As atualizações incrementais acrescentam as alterações ao final do arquivo e deixam o conteúdo original intacto.	ISO 32000-2	§7.5.6
A seção de cross-reference da atualização cobre apenas os objetos alterados, e o trailer acrescentado carrega uma entrada Prev localizando a seção de cross-reference anterior.	ISO 32000-2	§7.5.6
Strings literais são escritas entre parênteses; parênteses não balanceados e a barra invertida exigem tratamento de escape.	ISO 32000-2	§7.3.4.2

Todas as cláusulas são parafraseadas; o NextPDF não reproduz texto normativo. O NextPDF não faz nenhuma reivindicação de certificação. O applicator escreve atualizações incrementais na forma da ISO 32000-2 citada como uma declaração de capacidade; ele não é um writer certificado ou validado de forma independente. Esta página descreve apenas o comportamento em tempo de execução. Ela não faz nenhuma garantia, nenhuma declaração sobre elegibilidade ou efeito jurídico e não constitui aconselhamento jurídico; os termos de uma avaliação ou assinatura são definidos exclusivamente pelo contrato de licença.

Notas de desenvolvimento

• BrandingMode, BrandingStrategy, ambas as estratégias e a config carregam @since 3.0.0; BrandingApplicator e BrandingApplicationException carregam @since 3.1.0.
• O subsistema não faz nenhuma chamada de rede. O applicator lê apenas os campos estruturais que reescreve: as strings do dicionário Info, os dicionários de página e a cauda de cross-reference.
• O envelope de licença é um artefato assinado cuja assinatura do emissor o runtime verifica. O provisionamento, a renovação e o armazenamento seguro da licença são responsabilidade do operador.
• Todos os tipos concretos são final; as estratégias e a config também são readonly. Construa uma nova instância de config para alterar o estilo da marca d’água.
• BrandingStrategy::isActive() retornando false garante valores de identidade de todos os outros métodos; os chamadores podem fazer curto-circuito nele por desempenho.
• O stream da marca d’água referencia o nome de recurso /helvetica. O Core registra esse recurso para seu próprio branding; uma integração que desabilita o branding do Core precisa garantir que o recurso exista.
• O applicator não calcula nenhum digest; o chamador recalcula o digest dos bytes com branding antes de confirmá-los.
• Detalhes internos de mecanismo permanecem na documentação interna do repositório de origem e estão fora do escopo deste manual.

Limite de publicação

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

Veja também

• Branding — página de capacidade do subsistema de branding de avaliação.
• Trial e branding de avaliação — a história de avaliação de ponta a ponta.
• Licenciamento — Referência detalhada
• Visão geral do Enterprise