Branding — Ausführliche Referenz

Auf einen Blick

Diese Seite ist die Detailreferenz für das Modul NextPDF\Enterprise\Branding. Das Modul kennzeichnet Evaluierungsausgaben und lässt bezahlte Ausgaben unangetastet. Ein lizenzaufgelöster BrandingMode wählt eine Strategie aus; BrandingApplicator wendet die aufgelöste Strategie auf gerenderte PDF-Bytes an. Unter einer kostenpflichtigen Lizenz ist die Transformation die Identität: Die Ausgabe bleibt Byte für Byte unverändert, ohne dass eine Codeänderung erforderlich ist. Für den Evaluierungsworkflow lesen Sie zuerst die Seite zur Branding-Funktion.

Verfügbarkeit & Lizenzierung

Diese Funktion ist Bestandteil von NextPDF Enterprise (nextpdf/enterprise) und wird mit einem License-Envelope der Enterprise-Stufe aktiviert. Eine Bereitstellung ohne diese Berechtigung lädt die Klassen der Funktion nicht. Editionen vergleichen und eine Lizenz erwerben.

Das Subsystem trägt den dedizierten Funktionscode enterprise.branding, weil es das Evaluierungsverhalten über alle Editionen hinweg steuert. Der Branding-Modus wird zur Laufzeit aus dem signierten License-Envelope aufgelöst; kein Anwendungsflag wählt ihn aus. Eine kostenpflichtige Lizenz löst den Modus zu None auf und erzeugt niemals gekennzeichnete Ausgaben. Es gibt keinen Produktions-Build, zwischen dem umgeschaltet werden müsste.

Öffentliche API-Oberfläche

Symbol	Parameter	Standardverhalten	Rückgabe	Wirft oder scheitert mit	Hinweise
BrandingMode	—	None ('none'): keine Änderung	—	—	String-basiertes Enum; EvaluationWatermark ('evaluation') aktiviert die Evaluierungskennzeichnung.
BrandingStrategy	—	Vertrag, der von Integrationspunkten konsumiert wird	—	—	Interface; Aufrufer verzweigen niemals direkt anhand von BrandingMode.
BrandingStrategy::isActive	—	false bei Null-Strategie, true bei Evaluierungsstrategie	bool	—	false bedeutet, dass jede andere Methode Identitätswerte zurückgibt.
BrandingStrategy::buildPageWatermark	float $pageWidth, float $pageHeight (Punkt)	Leere Zeichenkette wenn inaktiv; diagonale Wasserzeichen-Operatoren wenn aktiv	string	—	Der Stream setzt eine /helvetica-Schriftressource auf der Seite voraus.
BrandingStrategy::decorateProducer	string $producer	Identität wenn inaktiv; hängt das Evaluierungssuffix an wenn aktiv	string	—	Standardsuffix: [EVALUATION].
BrandingStrategy::decorateSubject	string $subject	Identität wenn inaktiv; stellt das Evaluierungspräfix voran wenn aktiv	string	—	Ein leeres Subject ergibt die getrimmte Markierung.
BrandingStrategyFactory::create	BrandingMode $mode, ?EvaluationBrandingConfig $config = null	Bildet None auf NullBrandingStrategy ab, EvaluationWatermark auf EvaluationBrandingStrategy	BrandingStrategy	—	Statisch; eine null-Konfiguration verwendet die Standardwerte.
EvaluationBrandingConfig::__construct	Sechs optionale benannte Parameter (Text, Suffix, Präfix, Größe, Grau, Winkel)	Standardwerte: 48 pt, Grau 0.85, 45 Grad	Instanz	InvalidArgumentException bei leerem Text, nicht-positiver Schriftgröße oder Grau außerhalb 0.0–1.0	final readonly; unveränderlich.
EvaluationBrandingStrategy	Optionale EvaluationBrandingConfig	Wendet Wasserzeichen- und Metadaten-Dekoration an	—	—	final readonly; implementiert BrandingStrategy.
NullBrandingStrategy	—	Identität bei jeder Methode	—	—	Wird unter einer kostenpflichtigen Lizenz ausgewählt.
BrandingApplicator::apply	string $pdfBytes, BrandingStrategy $strategy	Inaktive Strategie: Eingabe wird Byte für Byte zurückgegeben; aktiv: eine inkrementelle Aktualisierung angehängt	string	BrandingApplicationException, wenn aktives Branding nicht sicher angewendet werden kann	Reine, deterministische Byte-Transformation.
BrandingApplicationException	—	Terminales, fail-closed-Fehlersignal	—	—	Trägt SPEC_CODE (SPEC-BRANDING-UNAPPLICABLE); Factory unsupportedStructure().

Signaturen der Einstiegspunkte

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

Verhaltensvertrag

Modus- und Strategieauflösung. Der Lizenzstatus — nicht der Anwendungscode — wählt den BrandingMode aus. BrandingStrategyFactory::create bildet None auf NullBrandingStrategy und EvaluationWatermark auf EvaluationBrandingStrategy ab. Integrationspunkte konsumieren das BrandingStrategy-Interface und untersuchen den Modus niemals direkt, sodass die Branding-Logik zentralisiert bleibt. Unter einer kostenpflichtigen Lizenz wird die Null-Strategie ausgewählt und die Ausgabe ist identisch mit einer Ausgabe, die ganz ohne Branding-Subsystem erzeugt wurde.

Wasserzeichenerzeugung. buildPageWatermark gibt PDF-Content-Stream-Operatoren für eine Seite aus: einen isolierten Grafikzustand (q/Q), die Standard-14-Schrift Helvetica über den Ressourcennamen /helvetica, den Fülltext-Rendering-Modus und eine Rotationsmatrix, die den Text diagonal durch die Seitenmitte platziert. Der Standardstil ist 48-pt-Text bei Graustufe 0.85, um 45 Grad gedreht. Die Zentrierung nähert die Textbreite über die Glyphenanzahl an — Graphemcluster, wenn intl geladen ist, andernfalls Unicode-Codepunkte über mbstring, als letzten Rückgriff die Bytelänge. Es werden bauartbedingt keine Vorschubbreiten pro Glyphe herangezogen. Der Wasserzeichentext wird gemäß ISO 32000-2:2020 §7.3.4.2 als PDF-Literalzeichenkette maskiert (Backslash und Klammern).

Metadaten-Dekoration. decorateProducer hängt das Producer-Suffix an den /Producer-Wert an. decorateSubject stellt das Subject-Präfix dem /Subject-Wert voran; ein leeres Subject ergibt die getrimmte Markierung, sodass ein Dokument ohne Subject-Metadaten dennoch gekennzeichnet wird.

Byte-Anwendung. BrandingApplicator::apply ist der terminale Konsument der Branding-Steuerung. Bei einer inaktiven Strategie gibt sie die Eingabe Byte für Byte zurück. Bei einer aktiven Strategie hängt sie eine einzelne inkrementelle Aktualisierung in der von ISO 32000-2:2020 §7.5.6 definierten Form an: Die ursprünglichen Bytes bleiben intakt, und der angehängte Body enthält ein dekoriertes Info-Objekt (das die bestehende Objektnummer wiederverwendet), einen Wasserzeichen-Content-Stream sowie ein aktualisiertes Seitenobjekt pro Seite und einen neuen Querverweis-Stream (/Type /XRef, /W [1 4 2]), dessen /Prev auf das vorherige startxref zurückverweist. Die Transformation ist für eine gegebene Eingabe und Konfiguration rein und deterministisch.

Fail-closed-Vertrag. Wenn die Strategie aktiv ist, muss die Eingabe brandbar sein: ein %PDF--Header, kein /Encrypt-Eintrag, keine Objekt-Streams (/ObjStm), ein Querverweis-Stream-Abschluss und eine von jeder Seite auflösbare /helvetica-Schriftressource. Jeder Verstoß löst BrandingApplicationException aus, anstatt ungekennzeichnete Bytes zurückzugeben. Aufrufer müssen die Ausnahme als terminal behandeln und dürfen die ursprünglichen, nicht gekennzeichneten Bytes nicht festschreiben.

Grenzfälle & Fehlermodi

• Gekennzeichnete Ausgabe bedeutet, dass der Lizenzstatus dem Evaluierungsstil entspricht. Das spiegelt den Lizenzstatus wider, keinen Defekt.
• Das Wasserzeichen ist bauartbedingt zentriert und diagonal. Es ist nicht für den Produktionseinsatz anpassbar; eine kostenpflichtige Lizenz entfernt es vollständig.
• EvaluationBrandingConfig weist leeren Wasserzeichentext, eine nicht-positive Schriftgröße und eine Graustufe außerhalb 0.0–1.0 mit InvalidArgumentException zurück.
• Eine aktive Strategie, die keine Änderung an Producer, Subject oder Wasserzeichen erzeugt, wird mit BrandingApplicationException abgelehnt, statt Bytes auszugeben, die bezahlt aussehen.
• Eine Seite ohne verwendbare /MediaBox (fehlend oder vererbt) wird mit dem ISO-216-A4-Standard von 595.276 × 841.890 Punkt mit einem Wasserzeichen versehen.
• /Contents wird sowohl in Einzelreferenz- als auch in Array-Form unterstützt; die Wasserzeichenreferenz wird zuletzt angehängt, sodass sie obenauf gezeichnet wird. Eine Seite ohne /Contents erhält eines.
• Info-Zeichenkettenwerte werden in ihrer ursprünglichen Darstellung round-trip-fähig erhalten: Hexadezimal-Zeichenketten (UTF-16BE) bleiben hexadezimal, Literalzeichenketten bleiben literal. Ein fehlender Schlüssel wird angehängt, hex-kodiert, wenn der Wert Nicht-ASCII-Zeichen enthält.
• Verschlüsselte Dokumente werden abgelehnt: Das Neuschreiben von Zeichenkettenobjekten unter /Encrypt würde den Verschlüsselungsschlüssel des Dokuments erfordern.
• Fehler tragen den stabilen Code SPEC-BRANDING-UNAPPLICABLE (BrandingApplicationException::SPEC_CODE), sodass konsumierende Pipelines nicht brandbare Ausgaben in eine Dead-Letter-Queue verschieben und auditieren können.
• Das Modul führt keine kryptografischen Operationen aus. Die Signaturprüfung des License-Envelope gehört zum Lizenzierungssubsystem; siehe die Detailreferenz zur Lizenzierung.

Konformität

Aussage	Standard	Klausel
Inkrementelle Aktualisierungen hängen Änderungen an das Dateiende an und lassen den ursprünglichen Inhalt unverändert.	ISO 32000-2	§7.5.6
Der Querverweisabschnitt der Aktualisierung erfasst nur geänderte Objekte, und der hinzugefügte Trailer enthält einen Prev-Eintrag, der den vorherigen Querverweisabschnitt lokalisiert.	ISO 32000-2	§7.5.6
Literale Zeichenketten werden in Klammern geschrieben; unausgeglichene Klammern und der umgekehrte Schrägstrich erfordern eine Escape-Behandlung.	ISO 32000-2	§7.3.4.2

Alle Klauseln sind paraphrasiert; NextPDF gibt keinen normativen Text wieder. NextPDF erhebt keinen Zertifizierungsanspruch. Der Applicator schreibt inkrementelle Aktualisierungen in der zitierten ISO-32000-2-Form als Fähigkeitsaussage; er ist kein zertifizierter oder unabhängig validierter Writer. Diese Seite beschreibt ausschließlich das Laufzeitverhalten. Sie gibt keine Gewährleistung, keine Aussage über Anspruchsberechtigung oder Rechtswirkung und stellt keine Rechtsberatung dar; die Bedingungen einer Evaluierung oder eines Abonnements werden ausschließlich durch den Lizenzvertrag festgelegt.

Entwicklungshinweise

• BrandingMode, BrandingStrategy, beide Strategien und die Konfiguration tragen @since 3.0.0; BrandingApplicator und BrandingApplicationException tragen @since 3.1.0.
• Das Subsystem tätigt keine Netzwerkaufrufe. Der Applicator liest nur die strukturellen Felder, die er neu schreibt: die Zeichenketten des Info-Dictionary, die Seiten-Dictionaries und den Querverweis-Abschluss.
• Das License-Envelope ist ein signiertes Artefakt, dessen Aussteller-Signatur die Runtime verifiziert. Bereitstellung, Erneuerung und sichere Aufbewahrung der Lizenz liegen in der Verantwortung des Betreibers.
• Alle konkreten Typen sind final; die Strategien und die Konfiguration sind zudem readonly. Erstellen Sie eine neue Konfigurationsinstanz, um den Wasserzeichenstil zu ändern.
• Wenn BrandingStrategy::isActive() false zurückgibt, sind Identitätswerte von jeder anderen Methode garantiert; Aufrufer können daraufhin aus Performancegründen kurzschließen.
• Der Wasserzeichen-Stream referenziert den Ressourcennamen /helvetica. Core registriert diese Ressource für sein eigenes Branding; eine Integration, die das Core-Branding deaktiviert, muss sicherstellen, dass die Ressource existiert.
• Der Applicator berechnet keinen Digest; der Aufrufer berechnet den Digest der gekennzeichneten Bytes neu, bevor er sie festschreibt.
• Interne Mechanismus-Details verbleiben in der internen Dokumentation des Quell-Repositorys und liegen außerhalb des Umfangs dieses Handbuchs.

Veröffentlichungsgrenze

Diese Seite dokumentiert ausschließlich extern beobachtbares Verhalten und die unterstützte öffentliche API-Oberfläche. Interne Namespace-Pfade, Hilfsklassen, Mechanismustabellen, Runbook-Dateinamen und Ticket-Präfixe liegen außerhalb des Umfangs.

Siehe auch

• Branding — Funktionsseite für das Subsystem zur Evaluierungskennzeichnung.
• Test- und Evaluierungskennzeichnung — die durchgängige Evaluierungsgeschichte.
• Lizenzierung — Ausführliche Referenz
• Enterprise-Übersicht