Branding

Visão geral

O subsistema de branding aplica branding de avaliação visível aos PDFs gerados durante uma avaliação e não aplica nada sob uma licença paga. Ele é entregue no pacote nextpdf/enterprise, governa o comportamento de avaliação entre as edições e é conduzido inteiramente pela licença — não pelo código da aplicação. Para a história completa de avaliação, consulte Avaliação e Branding de Avaliação; esta página documenta o próprio subsistema de branding.

Disponibilidade e licenciamento

Este recurso é entregue no NextPDF Enterprise (nextpdf/enterprise) e é ativado com um envelope de licença de nível Enterprise. Uma implantação sem essa titularidade não carrega as classes do recurso. Compare as edições e obtenha uma licença.

Diferentemente da maioria das superfícies Enterprise, ele carrega um código de recurso dedicado, enterprise.branding, porque governa o comportamento de avaliação em todas as edições — incluindo implantações somente Core e somente Pro. O modo de branding é resolvido a partir do envelope de licença assinado em tempo de execução; nenhum sinalizador da aplicação o seleciona, e uma licença paga em qualquer edição é resolvida como BrandingMode::None.

Instalação

composer require nextpdf/enterprise:^3

Visão conceitual

O runtime tem um modo de branding com dois estados, modelado por BrandingMode:

• None — nenhum branding de avaliação. A saída paga e normal nunca é modificada. Este é o padrão.
• EvaluationWatermark — branding de avaliação visível é aplicado aos PDFs gerados.

BrandingStrategyFactory mapeia o modo para uma estratégia: NullBrandingStrategy para None (ela não realiza nenhum trabalho e não produz nenhuma modificação) e EvaluationBrandingStrategy para EvaluationWatermark. O estado da licença — não o código da aplicação — seleciona o modo. Uma licença paga nunca produz saída com branding, e não há build de produção para alternar nem sinalizador de código para acionar.

Esta página descreve apenas o comportamento em tempo de execução. Ela não faz nenhuma garantia e nenhuma declaração sobre elegibilidade ou efeito legal; os termos que se aplicam à sua avaliação ou assinatura são definidos exclusivamente pelo seu contrato de licença.

Superfície da API

Conceito	Comportamento
BrandingMode	Dois estados: None (padrão, sem modificação) ou EvaluationWatermark.
BrandingStrategyFactory	Resolve um BrandingMode para uma estratégia.
EvaluationBrandingStrategy	Aplica a marca d’água de avaliação e a decoração de metadados.
NullBrandingStrategy	Estratégia no-op para saída paga / normal.
EvaluationBrandingConfig	Texto da marca d’água, decoração de metadados, tamanho da fonte, nível de cinza e ângulo imutáveis.
BrandingStrategy	Contrato que a camada de integração consome: isActive(), buildPageWatermark(), decorateProducer(), decorateSubject().
BrandingApplicator	Aplica uma estratégia resolvida aos bytes de PDF renderizados; fail-closed — lança BrandingApplicationException quando o branding ativo não pode ser marcado.

O subsistema expõe uma pequena superfície chamável para a camada de integração que aplica a estratégia que a licença resolveu; o código da aplicação nunca escolhe se deve aplicar branding. Os exemplos abaixo mostram os dois pontos de contato: ler uma estratégia resolvida e marcar bytes renderizados com o applicator fail-closed.

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

Resolva a estratégia que a licença selecionou e leia seu comportamento. Uma licença paga é resolvida como BrandingMode::None, cuja estratégia está inativa e repassa cada valor inalterado.

resolve-strategy.php

<?php

declare(strict_types=1);

use NextPDF\Enterprise\Branding\BrandingMode;
use NextPDF\Enterprise\Branding\BrandingStrategyFactory;

// The license resolves the mode; None is what a paid license produces.
$strategy = BrandingStrategyFactory::create(BrandingMode::None);

\var_dump($strategy->isActive());                 // bool(false)
echo $strategy->decorateProducer('NextPDF 3.1');  // NextPDF 3.1 (unchanged)

Exemplo de código — Produção

Marque bytes de PDF já renderizados com a estratégia que a licença resolveu. BrandingApplicator::apply() retorna a entrada inalterada para uma licença paga e, para uma licença de avaliação, acrescenta a marca d’água e os marcadores de metadados enquanto mantém os bytes originais intactos. Ele lança BrandingApplicationException quando o branding ativo não pode ser aplicado com segurança — trate isso como terminal e nunca confirme os bytes não marcados.

apply-evaluation-branding.php

<?php

declare(strict_types=1);

use NextPDF\Enterprise\Branding\BrandingApplicationException;
use NextPDF\Enterprise\Branding\BrandingApplicator;
use NextPDF\Enterprise\Branding\BrandingMode;
use NextPDF\Enterprise\Branding\BrandingStrategyFactory;
use NextPDF\Enterprise\Branding\EvaluationBrandingConfig;

/**
 * Apply the branding the license resolved to freshly rendered PDF bytes.
 *
 * @param string       $renderedPdf Bytes from the render engine.
 * @param BrandingMode $mode        Resolved from the signed license envelope.
 *
 * @throws BrandingApplicationException When active branding cannot be marked.
 */
function markEvaluationOutput(string $renderedPdf, BrandingMode $mode): string
{
    $strategy = BrandingStrategyFactory::create(
        $mode,
        new EvaluationBrandingConfig(
            watermarkText: 'EVALUATION COPY — Not for Production Use',
        ),
    );

    try {
        return (new BrandingApplicator())->apply($renderedPdf, $strategy);
    } catch (BrandingApplicationException $e) {
        // Fail-closed: never emit unbranded evaluation output. Dead-letter.
        throw $e;
    }
}

O que o branding de avaliação faz

Quando a licença ativa seleciona EvaluationWatermark, a estratégia de avaliação:

• desenha um texto de marca d’água diagonal cinza-claro em cada página, renderizado como um fluxo de conteúdo de página em um estado gráfico isolado, de modo que não altere o conteúdo ao redor nem o seu layout;
• acrescenta um sufixo de avaliação aos metadados de produtor do documento;
• antepõe um prefixo de avaliação aos metadados de assunto do documento.

A marca d’água usa uma fonte Base14 e uma matriz de rotação para posicionar o texto diagonalmente sobre o centro da página. O objeto de configuração é imutável e valida suas entradas (por exemplo, o texto da marca d’água não pode ser vazio e o tamanho da fonte deve ser positivo).

Como uma licença paga remove o branding

Sob uma licença paga (não de avaliação), o modo de branding é None e a estratégia nula é selecionada: nenhuma marca d’água, nenhum sufixo de produtor, nenhum prefixo de assunto. A saída é idêntica à saída produzida sem nenhum subsistema de branding. Remover o branding de avaliação não requer nenhuma alteração de código — instale uma licença paga e o próximo documento gerado fica sem branding.

Casos extremos e armadilhas

• O branding aparece quando o estado da licença é do tipo avaliação. Isso reflete o estado da licença, não um defeito; verifique o status da licença e renove pelo portal de licenças.
• A marca d’água é centralizada e diagonal por design, para que a saída de avaliação seja inequívoca; ela não se destina a ser ajustada para produção. Uma licença paga a remove inteiramente.
• Os metadados de produtor e de assunto carregam marcadores de avaliação durante uma avaliação e estão ausentes sob uma licença paga.

Desempenho

A marca d’água é um pequeno fluxo de conteúdo por página, fixo, com impacto desprezível no tempo de geração ou no tamanho do documento. Sob uma licença paga, o subsistema não realiza nenhum trabalho. O orçamento de desempenho da página reflete a renderização da documentação.

Notas de segurança

O branding de avaliação é um marcador de visibilidade, não um controle de segurança. Ele indica saída de avaliação. Não é uma assinatura digital e não deve ser usado como tal. Para uma saída com evidência de adulteração, use os recursos de assinatura descritos na matriz de recursos. A licença que seleciona o modo de branding é um envelope assinado cuja assinatura do emissor o runtime verifica.

Residência de dados e mitigações de PII

O subsistema de branding adiciona uma marca d’água fixa e marcadores de metadados; ele não lê nem transmite conteúdo do documento e não faz nenhuma chamada de rede.

Telemetria segura e limpeza de logs

O subsistema não registra conteúdo do documento. As transições de estado da licença que mudam o modo de branding são expostas pelo subsistema de licenciamento, não aqui.

Conformidade

Nenhuma conformidade com padrões é declarada para esta página. Ela descreve apenas o comportamento em tempo de execução. Ela não declara nem implica nenhuma garantia, certificação ou elegibilidade. Os termos da sua avaliação ou assinatura são definidos exclusivamente pelo seu contrato de licença.

Comportamento em modo FIPS

Este módulo não realiza nenhuma operação criptográfica. A verificação da assinatura da licença é tratada pelo subsistema de licenciamento.

Modelo de ameaças

O próprio subsistema de branding não processa nenhuma entrada externa além do modo de branding resolvido. O envelope de licença que seleciona o modo é assinado, e sua assinatura de emissor é verificada pelo runtime; falsificar o modo exigiria forjar essa assinatura.

Contrato de comportamento

• BrandingMode tem dois estados: None (padrão; sem modificação da saída) e EvaluationWatermark.
• Sob uma licença paga (não de avaliação), o modo é None e a estratégia nula é selecionada: a saída é idêntica à saída produzida sem nenhum subsistema de branding.
• Sob uma licença de avaliação, a estratégia desenha uma marca d’água diagonal em um estado gráfico isolado e acrescenta marcadores de avaliação aos metadados de produtor e de assunto.
• O objeto de configuração é imutável e valida suas entradas (texto da marca d’água não vazio, tamanho da fonte positivo).

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 do escopo.

Fallback do Core

O subsistema de branding é entregue no pacote nextpdf/enterprise, mas governa o comportamento de avaliação em todas as edições, incluindo implantações somente Core e somente Pro que usam uma licença de avaliação. Não há um subsistema de branding somente Core para servir de fallback; uma licença paga em qualquer edição é resolvida como BrandingMode::None.

Fallback do Pro

Não há um subsistema de branding do Pro separado. O mesmo subsistema de branding nextpdf/enterprise governa o comportamento de avaliação para implantações Pro; uma licença Pro paga é resolvida como BrandingMode::None exatamente como uma licença Enterprise paga.

Nota sobre o limite do Enterprise

Os detalhes internos de mecanismo permanecem na documentação interna do repositório de origem e estão fora do escopo deste manual.

Limite de implantação

O envelope de licença que seleciona o modo de branding é um artefato assinado cuja assinatura de emissor o runtime verifica; o provisionamento, a renovação e o armazenamento seguro da licença são responsabilidade do operador. O subsistema não faz nenhuma chamada de rede e não lê nenhum conteúdo do documento.

Limite de conformidade legal

Esta página descreve apenas o comportamento em tempo de execução. Ela não declara nem implica nenhuma garantia, certificação ou elegibilidade, e não constitui aconselhamento jurídico. Os termos da sua avaliação ou assinatura — incluindo qual branding se aplica e por quanto tempo — são definidos exclusivamente pelo seu contrato de licença. Consulte esse contrato ou fale com a equipe de vendas.

Consulte também

• Branding — Referência aprofundada — API pública e contrato de comportamento deste subsistema.
• Avaliação e Branding de Avaliação — a história completa de avaliação.
• Ativação de licença
• Visão geral do Enterprise
• Matriz de recursos Core vs Pro vs Enterprise