Branding — Riferimento approfondito

A colpo d’occhio

Questa pagina è il riferimento approfondito per il modulo NextPDF\Enterprise\Branding. Il modulo contrassegna l’output di valutazione e lascia intatto l’output a pagamento. Un BrandingMode risolto dalla licenza seleziona una strategia; BrandingApplicator applica la strategia risolta ai byte PDF renderizzati. Sotto una licenza a pagamento la trasformazione è l’identità: l’output è invariato byte per byte, senza alcuna modifica al codice. Per il flusso di lavoro di valutazione, leggere prima la pagina della capability Branding.

Disponibilità e licenza

Questa capability è inclusa in NextPDF Enterprise (nextpdf/enterprise) e si attiva con un envelope di licenza di livello Enterprise. Un deployment privo di tale entitlement non carica le classi della capability. Confronta le edizioni e ottieni una licenza.

Il sottosistema porta il codice di capability dedicato enterprise.branding perché governa il comportamento di valutazione in tutte le edizioni. La modalità di branding viene risolta dall’envelope di licenza firmato in fase di esecuzione; nessun flag dell’applicazione la seleziona. Una licenza a pagamento risolve la modalità in None e non produce mai output con branding. Non esiste alcuna build di produzione da commutare.

Superficie API pubblica

Simbolo	Parametri	Comportamento predefinito	Restituisce	Solleva o fallisce con	Note
BrandingMode	—	None ('none'): nessuna modifica	—	—	Enum con backing string; EvaluationWatermark ('evaluation') attiva il branding di valutazione.
BrandingStrategy	—	Contratto consumato dai punti di integrazione	—	—	Interfaccia; i chiamanti non diramano mai direttamente su BrandingMode.
BrandingStrategy::isActive	—	false per la strategia null, true per la strategia di valutazione	bool	—	false significa che ogni altro metodo restituisce valori identità.
BrandingStrategy::buildPageWatermark	float $pageWidth, float $pageHeight (punti)	Stringa vuota quando inattiva; operatori di filigrana diagonale quando attiva	string	—	Lo stream presuppone una risorsa font /helvetica sulla pagina.
BrandingStrategy::decorateProducer	string $producer	Identità quando inattiva; aggiunge il suffisso di valutazione quando attiva	string	—	Suffisso predefinito: [EVALUATION].
BrandingStrategy::decorateSubject	string $subject	Identità quando inattiva; antepone il prefisso di valutazione quando attiva	string	—	Un subject vuoto produce il marcatore ripulito dagli spazi.
BrandingStrategyFactory::create	BrandingMode $mode, ?EvaluationBrandingConfig $config = null	Mappa None su NullBrandingStrategy, EvaluationWatermark su EvaluationBrandingStrategy	BrandingStrategy	—	Statico; una config null usa i valori predefiniti.
EvaluationBrandingConfig::__construct	Sei parametri denominati opzionali (testo, suffisso, prefisso, dimensione, grigio, angolo)	Predefiniti: 48 pt, grigio 0.85, 45 gradi	Istanza	InvalidArgumentException per testo vuoto, dimensione del font non positiva o grigio fuori dall’intervallo 0.0–1.0	final readonly; immutabile.
EvaluationBrandingStrategy	EvaluationBrandingConfig opzionale	Applica filigrana e decorazione dei metadati	—	—	final readonly; implementa BrandingStrategy.
NullBrandingStrategy	—	Identità su ogni metodo	—	—	Selezionata sotto una licenza a pagamento.
BrandingApplicator::apply	string $pdfBytes, BrandingStrategy $strategy	Strategia inattiva: input restituito byte per byte; attiva: un singolo incremental update aggiunto in coda	string	BrandingApplicationException quando il branding attivo non può essere applicato in sicurezza	Trasformazione a byte pura e deterministica.
BrandingApplicationException	—	Segnale di errore terminale, fail-closed	—	—	Porta SPEC_CODE (SPEC-BRANDING-UNAPPLICABLE); factory unsupportedStructure().

Firme dei punti di ingresso

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

Contratto di comportamento

Risoluzione di modalità e strategia. Lo stato della licenza — non il codice dell’applicazione — seleziona il BrandingMode. BrandingStrategyFactory::create mappa None su NullBrandingStrategy e EvaluationWatermark su EvaluationBrandingStrategy. I punti di integrazione consumano l’interfaccia BrandingStrategy e non ispezionano mai direttamente la modalità, così la logica di branding resta centralizzata. Sotto una licenza a pagamento viene selezionata la strategia null e l’output è identico a quello prodotto senza alcun sottosistema di branding.

Generazione della filigrana. buildPageWatermark emette operatori di content stream PDF per una pagina: uno stato grafico isolato (q/Q), il font Helvetica standard-14 tramite il nome risorsa /helvetica, la modalità di rendering del testo a riempimento e una matrice di rotazione che dispone il testo in diagonale attraverso il centro della pagina. Lo stile predefinito è testo da 48 pt al livello di grigio 0.85, ruotato di 45 gradi. La centratura approssima la larghezza del testo tramite il conteggio dei glifi — cluster di grafemi quando intl è caricato, code point Unicode tramite mbstring altrimenti, la lunghezza in byte come fallback finale. Per progettazione non vengono consultate le larghezze di avanzamento per singolo glifo. Il testo della filigrana viene sottoposto a escape come stringa letterale PDF secondo ISO 32000-2:2020 §7.3.4.2 (backslash e parentesi).

Decorazione dei metadati. decorateProducer aggiunge il suffisso del producer al valore /Producer. decorateSubject antepone il prefisso del subject al valore /Subject; un subject vuoto produce il marcatore ripulito dagli spazi, così un documento privo di metadati di subject viene comunque contrassegnato.

Applicazione a byte. BrandingApplicator::apply è il consumatore terminale del controllo di branding. Con una strategia inattiva restituisce l’input byte per byte. Con una strategia attiva aggiunge in coda un singolo incremental update nella forma definita da ISO 32000-2:2020 §7.5.6: i byte originali restano intatti e il corpo aggiunto contiene un oggetto Info decorato (riutilizzando il numero di oggetto esistente), un content stream di filigrana più un oggetto pagina aggiornato per ciascuna pagina, e un nuovo cross-reference stream (/Type /XRef, /W [1 4 2]) il cui /Prev punta al precedente startxref. La trasformazione è pura e deterministica per un dato input e una data configurazione.

Contratto fail-closed. Quando la strategia è attiva, l’input deve essere brandabile: un header %PDF-, nessuna voce /Encrypt, nessun object stream (/ObjStm), una coda con cross-reference stream e una risorsa font /helvetica risolvibile da ogni pagina. Qualsiasi violazione solleva BrandingApplicationException invece di restituire byte privi di branding. I chiamanti devono trattare l’eccezione come terminale e non devono committare i byte originali non contrassegnati.

Casi limite e modalità di errore

• Un output con branding significa che lo stato della licenza è di tipo valutazione. Ciò riflette lo stato della licenza, non un difetto.
• La filigrana è centrata e diagonale per progettazione. Non è regolabile per l’uso in produzione; una licenza a pagamento la rimuove interamente.
• EvaluationBrandingConfig rifiuta testo della filigrana vuoto, dimensione del font non positiva e livello di grigio fuori dall’intervallo 0.0–1.0 con InvalidArgumentException.
• Una strategia attiva che non produce alcuna modifica di Producer, Subject o filigrana viene rifiutata con BrandingApplicationException anziché emettere byte che sembrano a pagamento.
• Una pagina priva di un /MediaBox utilizzabile (assente o ereditato) viene filigranata al valore predefinito A4 ISO 216 di 595.276 × 841.890 punti.
• /Contents è supportato sia in forma di riferimento singolo sia di array; il riferimento alla filigrana viene aggiunto per ultimo così da disegnarsi in cima. Una pagina priva di /Contents ne riceve uno.
• I valori stringa di Info effettuano il round-trip nella loro rappresentazione originale: le stringhe esadecimali (UTF-16BE) restano esadecimali, le stringhe letterali restano letterali. Una chiave assente viene aggiunta, codificata in esadecimale quando il valore contiene caratteri non ASCII.
• I documenti cifrati vengono rifiutati: la riscrittura degli oggetti stringa sotto /Encrypt richiederebbe la chiave di cifratura del documento.
• Gli errori portano il codice stabile SPEC-BRANDING-UNAPPLICABLE (BrandingApplicationException::SPEC_CODE) così che le pipeline consumatrici possano applicare il dead-letter e sottoporre ad audit l’output non brandabile.
• Il modulo non esegue alcuna operazione crittografica. La verifica della firma dell’envelope di licenza spetta al sottosistema di licensing; vedere il riferimento approfondito sul Licensing.

Conformità

Dichiarazione	Standard	Clausola
Gli incremental update aggiungono le modifiche alla fine del file e lasciano intatti i contenuti originali.	ISO 32000-2	§7.5.6
La sezione di cross-reference dell’update copre solo gli oggetti modificati e il trailer aggiunto porta una voce Prev che individua la precedente sezione di cross-reference.	ISO 32000-2	§7.5.6
Le stringhe letterali si scrivono tra parentesi; le parentesi non bilanciate e la reverse solidus richiedono un trattamento di escape.	ISO 32000-2	§7.3.4.2

Tutte le clausole sono parafrasate; NextPDF non riproduce il testo normativo. NextPDF non avanza alcuna rivendicazione di certificazione. L’applicator scrive gli incremental update nella forma ISO 32000-2 citata come dichiarazione di capacità; non è un writer certificato o validato in modo indipendente. Questa pagina descrive esclusivamente il comportamento in fase di esecuzione. Non avanza alcuna garanzia, alcuna dichiarazione sull’idoneità o sull’effetto legale, e non costituisce un parere legale; i termini di una valutazione o di un abbonamento sono definiti esclusivamente dal contratto di licenza.

Note di sviluppo

• BrandingMode, BrandingStrategy, entrambe le strategie e la config portano @since 3.0.0; BrandingApplicator e BrandingApplicationException portano @since 3.1.0.
• Il sottosistema non effettua alcuna chiamata di rete. L’applicator legge solo i campi strutturali che riscrive: le stringhe del dizionario Info, i dizionari di pagina e la coda di cross-reference.
• L’envelope di licenza è un artefatto firmato la cui firma dell’emittente viene verificata dal runtime. Il provisioning, il rinnovo e l’archiviazione sicura della licenza sono responsabilità dell’operatore.
• Tutti i tipi concreti sono final; le strategie e la config sono anche readonly. Costruire una nuova istanza di config per modificare lo stile della filigrana.
• BrandingStrategy::isActive() che restituisce false garantisce valori identità da ogni altro metodo; i chiamanti possono usarlo come short-circuit per le prestazioni.
• Lo stream della filigrana fa riferimento al nome risorsa /helvetica. Core registra questa risorsa per il proprio branding; un’integrazione che disabilita il branding di Core deve garantire che la risorsa esista.
• L’applicator non calcola alcun digest; il chiamante ricalcola il digest dei byte con branding prima di committarli.
• I dettagli interni del meccanismo restano nella documentazione interna del repository sorgente e sono fuori dall’ambito di questo manuale.

Confine di pubblicazione

Questa pagina documenta esclusivamente 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 dei file di runbook e i prefissi dei ticket sono fuori ambito.

Vedere anche

• Branding — pagina della capability per il sottosistema di branding di valutazione.
• Trial e branding di valutazione — la storia completa della valutazione.
• Licensing — Riferimento approfondito
• Panoramica di Enterprise