Branding

In sintesi

Il sottosistema di branding applica un branding di valutazione visibile ai PDF generati durante una valutazione e non applica nulla sotto una licenza a pagamento. È distribuito nel pacchetto nextpdf/enterprise, disciplina il comportamento di valutazione tra le edizioni ed è guidato interamente dalla licenza — non dal codice dell’applicazione. Per l’intera vicenda della valutazione, vedere Prova e branding di valutazione; questa pagina documenta il sottosistema di branding in sé.

Disponibilità e licenze

Questa capacità è distribuita in NextPDF Enterprise (nextpdf/enterprise) e si attiva con un envelope di licenza di livello Enterprise. Una distribuzione priva di tale entitlement non carica le classi della capacità. Confronta le edizioni e ottieni una licenza.

A differenza della maggior parte delle superfici Enterprise, dispone di un codice di capacità dedicato, enterprise.branding, perché disciplina il comportamento di valutazione in tutte le edizioni — comprese le distribuzioni solo-Core e solo-Pro. La modalità di branding è risolta dall’envelope di licenza firmato in fase di esecuzione; nessun flag dell’applicazione la seleziona e una licenza a pagamento in qualsiasi edizione si risolve in BrandingMode::None.

Installazione

composer require nextpdf/enterprise:^3

Panoramica concettuale

Il runtime ha una modalità di branding con due stati, modellata da BrandingMode:

• None — nessun branding di valutazione. L’output a pagamento e normale non viene mai modificato. È l’impostazione predefinita.
• EvaluationWatermark — un branding di valutazione visibile viene applicato ai PDF generati.

BrandingStrategyFactory associa la modalità a una strategia: NullBrandingStrategy per None (non esegue alcun lavoro e non produce alcuna modifica) ed EvaluationBrandingStrategy per EvaluationWatermark. È lo stato della licenza — non il codice dell’applicazione — a selezionare la modalità. Una licenza a pagamento non produce mai output con branding, e non vi è alcun build di produzione da commutare né alcun flag di codice da attivare.

Questa pagina descrive solo il comportamento in fase di esecuzione. Non offre alcuna garanzia e nessuna dichiarazione in merito a idoneità o effetto legale; i termini applicabili alla propria valutazione o al proprio abbonamento sono definiti esclusivamente dal proprio contratto di licenza.

Superficie API

Concetto	Comportamento
BrandingMode	Due stati: None (predefinito, nessuna modifica) o EvaluationWatermark.
BrandingStrategyFactory	Risolve un BrandingMode in una strategia.
EvaluationBrandingStrategy	Applica la filigrana di valutazione e la decorazione dei metadati.
NullBrandingStrategy	Strategia no-op per l’output a pagamento / normale.
EvaluationBrandingConfig	Testo della filigrana, decorazione dei metadati, dimensione del font, livello di grigio e angolo immutabili.
BrandingStrategy	Contratto consumato dal livello di integrazione: isActive(), buildPageWatermark(), decorateProducer(), decorateSubject().
BrandingApplicator	Applica una strategia risolta ai byte del PDF renderizzato; fail-closed — solleva BrandingApplicationException quando un branding attivo non può essere marcato.

Il sottosistema espone una piccola superficie richiamabile per il livello di integrazione che applica la strategia risolta dalla licenza; il codice dell’applicazione non sceglie mai se applicare il branding. Gli esempi seguenti mostrano i due punti di contatto: la lettura di una strategia risolta e la marcatura dei byte renderizzati con l’applicator fail-closed.

Esempio di codice — Avvio rapido

Risolvere la strategia selezionata dalla licenza e leggerne il comportamento. Una licenza a pagamento si risolve in BrandingMode::None, la cui strategia è inattiva e lascia passare ogni valore inalterato.

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)

Esempio di codice — Produzione

Marcare i byte del PDF già renderizzato con la strategia risolta dalla licenza. BrandingApplicator::apply() restituisce l’input inalterato per una licenza a pagamento e, per una licenza di valutazione, aggiunge la filigrana e i marcatori di metadati lasciando intatti i byte originali. Solleva BrandingApplicationException quando un branding attivo non può essere applicato in sicurezza — considerarlo come terminale e non salvare mai i byte non marcati.

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;
    }
}

Cosa fa il branding di valutazione

Quando la licenza attiva seleziona EvaluationWatermark, la strategia di valutazione:

• disegna un testo di filigrana diagonale grigio chiaro su ciascuna pagina, reso come un flusso di contenuti di pagina in uno stato grafico isolato in modo da non alterare il contenuto circostante né il proprio layout;
• aggiunge un suffisso di valutazione ai metadati del produttore del documento;
• antepone un prefisso di valutazione ai metadati dell’oggetto del documento.

La filigrana usa un font Base14 e una matrice di rotazione per posizionare il testo in diagonale attraverso il centro della pagina. L’oggetto di configurazione è immutabile e convalida i propri input (per esempio, il testo della filigrana non può essere vuoto e la dimensione del font deve essere positiva).

Come una licenza a pagamento rimuove il branding

Sotto una licenza a pagamento (non di valutazione) la modalità di branding è None e viene selezionata la strategia null: nessuna filigrana, nessun suffisso del produttore, nessun prefisso dell’oggetto. L’output è identico all’output prodotto senza alcun sottosistema di branding. La rimozione del branding di valutazione non richiede alcuna modifica al codice — installare una licenza a pagamento e il documento generato successivamente è privo di branding.

Casi limite e insidie

• Il branding compare quando lo stato della licenza è di tipo valutazione. Ciò riflette lo stato della licenza, non un difetto; verificare lo stato della licenza e rinnovarla tramite il portale delle licenze.
• La filigrana è centrata e diagonale per progettazione, così che l’output di valutazione sia inequivocabile; non è pensata per essere regolata per la produzione. Una licenza a pagamento la rimuove integralmente.
• I metadati del produttore e dell’oggetto trasportano marcatori di valutazione durante una valutazione e sono assenti sotto una licenza a pagamento.

Prestazioni

La filigrana è un piccolo flusso di contenuti per pagina, fisso, con impatto trascurabile sul tempo di generazione o sulla dimensione del documento. Sotto una licenza a pagamento il sottosistema non esegue alcun lavoro. Il budget di prestazioni della pagina riflette il rendering della documentazione.

Note di sicurezza

Il branding di valutazione è un marcatore di visibilità, non un controllo di sicurezza. Indica un output di valutazione. Non è una firma digitale e non vi si deve fare affidamento come tale. Per un output con rilevabilità delle manomissioni, usare le capacità di firma descritte nella matrice delle funzionalità. La licenza che seleziona la modalità di branding è un envelope firmato la cui firma dell’emittente è verificata dal runtime.

Residenza dei dati e mitigazioni dei dati personali (PII)

Il sottosistema di branding aggiunge una filigrana fissa e marcatori di metadati; non legge né trasmette il contenuto del documento e non effettua alcuna chiamata di rete.

Telemetria sicura e sanificazione dei log

Il sottosistema non registra il contenuto del documento. Le transizioni di stato della licenza che cambiano la modalità di branding emergono tramite il sottosistema di licenze, non qui.

Conformità

Per questa pagina non si rivendica alcuna conformità a standard. Descrive solo il comportamento in fase di esecuzione. Non dichiara né implica alcuna garanzia, certificazione o idoneità. I termini della propria valutazione o del proprio abbonamento sono definiti esclusivamente dal proprio contratto di licenza.

Comportamento in modalità FIPS

Questo modulo non esegue alcuna operazione crittografica. La verifica della firma della licenza è gestita dal sottosistema di licenze.

Modello di minaccia

Il sottosistema di branding di per sé non elabora alcun input esterno oltre alla modalità di branding risolta. L’envelope della licenza che seleziona la modalità è firmato e la sua firma dell’emittente è verificata dal runtime; falsificare la modalità richiederebbe la contraffazione di tale firma.

Contratto di comportamento

• BrandingMode ha due stati: None (predefinito; nessuna modifica dell’output) ed EvaluationWatermark.
• Sotto una licenza a pagamento (non di valutazione) la modalità è None e viene selezionata la strategia null: l’output è identico all’output prodotto senza alcun sottosistema di branding.
• Sotto una licenza di valutazione la strategia disegna una filigrana diagonale in uno stato grafico isolato e aggiunge marcatori di valutazione ai metadati del produttore e dell’oggetto.
• L’oggetto di configurazione è immutabile e convalida i propri input (testo della filigrana non vuoto, dimensione del font positiva).

Confine di pubblicazione

Questa pagina documenta solo il comportamento osservabile dall’esterno e la superficie API pubblica supportata. I percorsi di namespace interni, le classi helper, le tabelle dei meccanismi, i nomi di file di runbook e i prefissi di ticket sono fuori ambito.

Fallback di Core

Il sottosistema di branding è incluso nel pacchetto nextpdf/enterprise ma disciplina il comportamento di valutazione in tutte le edizioni, comprese le distribuzioni solo-Core e solo-Pro che usano una licenza di valutazione. Non vi è alcun sottosistema di branding solo-Core a cui ricorrere; una licenza a pagamento in qualsiasi edizione si risolve in BrandingMode::None.

Fallback di Pro

Non vi è alcun sottosistema di branding di Pro separato. Lo stesso sottosistema di branding nextpdf/enterprise disciplina il comportamento di valutazione per le distribuzioni Pro; una licenza Pro a pagamento si risolve in BrandingMode::None esattamente come una licenza Enterprise a pagamento.

Nota sul confine Enterprise

Il dettaglio del meccanismo interno rimane nella documentazione interna del repository sorgente ed è fuori ambito per questo manuale.

Confine di distribuzione

L’envelope della licenza che seleziona la modalità di branding è un artefatto firmato la cui firma dell’emittente è verificata dal runtime; il provisioning, il rinnovo e l’archiviazione sicura della licenza sono responsabilità dell’operatore. Il sottosistema non effettua alcuna chiamata di rete e non legge alcun contenuto del documento.

Confine di conformità legale

Questa pagina descrive solo il comportamento in fase di esecuzione. Non dichiara né implica alcuna garanzia, certificazione o idoneità, e non costituisce consulenza legale. I termini della propria valutazione o del proprio abbonamento — incluso quale branding si applichi e per quanto tempo — sono definiti esclusivamente dal proprio contratto di licenza. Consultare tale contratto o contattare il team commerciale.

Vedere anche

• Branding — Riferimento approfondito — API pubblica e contratto di comportamento per questo sottosistema.
• Prova e branding di valutazione — l’intera vicenda della valutazione.
• Attivazione della licenza
• Panoramica Enterprise
• Matrice delle funzionalità Core vs Pro vs Enterprise