Branding — Diepe referentie

In één oogopslag

Deze pagina is de diepe referentie voor de NextPDF\Enterprise\Branding-module. De module markeert evaluatie-uitvoer en laat betaalde uitvoer ongemoeid. Een via de licentie opgeloste BrandingMode selecteert een strategie; BrandingApplicator past de opgeloste strategie toe op gerenderde PDF-bytes. Onder een betaalde licentie is de transformatie de identiteit: de uitvoer is byte-voor-byte ongewijzigd, zonder dat een codewijziging nodig is. Lees voor de evaluatieworkflow eerst de Branding-capabilitypagina.

Beschikbaarheid en licenties

Deze capability wordt geleverd in NextPDF Enterprise (nextpdf/enterprise) en wordt geactiveerd met een licentie-envelop op Enterprise-niveau. Een deployment zonder die entitlement laadt de classes van de capability niet. Vergelijk edities en vraag een licentie aan.

Het subsysteem draagt de toegewijde capability-code enterprise.branding omdat het evaluatiegedrag over alle edities regelt. De branding-modus wordt tijdens runtime opgelost uit de ondertekende licentie-envelop; geen applicatievlag selecteert die. Een betaalde licentie lost de modus op naar None en produceert nooit gebrande uitvoer. Er is geen productiebuild om naar te schakelen.

Publiek API-oppervlak

Symbool	Parameters	Standaardgedrag	Retourneert	Gooit of faalt met	Opmerkingen
BrandingMode	—	None ('none'): geen wijziging	—	—	String-backed enum; EvaluationWatermark ('evaluation') activeert evaluatie-branding.
BrandingStrategy	—	Contract dat door integratiepunten wordt geconsumeerd	—	—	Interface; aanroepers vertakken nooit rechtstreeks op BrandingMode.
BrandingStrategy::isActive	—	false voor null-strategie, true voor evaluatiestrategie	bool	—	false betekent dat elke andere methode identiteitswaarden retourneert.
BrandingStrategy::buildPageWatermark	float $pageWidth, float $pageHeight (punten)	Lege string wanneer inactief; diagonale watermerkoperators wanneer actief	string	—	Stream gaat uit van een /helvetica-fontresource op de pagina.
BrandingStrategy::decorateProducer	string $producer	Identiteit wanneer inactief; voegt de evaluatiesuffix toe wanneer actief	string	—	Standaardsuffix: [EVALUATION].
BrandingStrategy::decorateSubject	string $subject	Identiteit wanneer inactief; plaatst de evaluatieprefix ervoor wanneer actief	string	—	Een lege subject levert de getrimde markering op.
BrandingStrategyFactory::create	BrandingMode $mode, ?EvaluationBrandingConfig $config = null	Mapt None naar NullBrandingStrategy, EvaluationWatermark naar EvaluationBrandingStrategy	BrandingStrategy	—	Statisch; een null-config gebruikt de standaardwaarden.
EvaluationBrandingConfig::__construct	Zes optionele benoemde parameters (text, suffix, prefix, size, gray, angle)	Standaardwaarden: 48 pt, grijs 0.85, 45 graden	Instance	InvalidArgumentException bij lege tekst, niet-positieve fontgrootte of grijs buiten 0.0–1.0	final readonly; onveranderlijk.
EvaluationBrandingStrategy	Optionele EvaluationBrandingConfig	Past watermerk- en metadatadecoratie toe	—	—	final readonly; implementeert BrandingStrategy.
NullBrandingStrategy	—	Identiteit bij elke methode	—	—	Geselecteerd onder een betaalde licentie.
BrandingApplicator::apply	string $pdfBytes, BrandingStrategy $strategy	Inactieve strategie: invoer wordt byte-voor-byte geretourneerd; actief: één incrementele update toegevoegd	string	BrandingApplicationException wanneer actieve branding niet veilig kan worden toegepast	Zuivere, deterministische byte-transformatie.
BrandingApplicationException	—	Terminaal, fail-closed foutsignaal	—	—	Draagt SPEC_CODE (SPEC-BRANDING-UNAPPLICABLE); factory unsupportedStructure().

Handtekeningen van de entry-points

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

Gedragscontract

Modus- en strategieresolutie. De licentiestatus — niet applicatiecode — selecteert de BrandingMode. BrandingStrategyFactory::create mapt None naar NullBrandingStrategy en EvaluationWatermark naar EvaluationBrandingStrategy. Integratiepunten consumeren de BrandingStrategy-interface en inspecteren de modus nooit rechtstreeks, zodat de branding-logica gecentraliseerd blijft. Onder een betaalde licentie wordt de null-strategie geselecteerd en is de uitvoer identiek aan uitvoer die helemaal zonder branding-subsysteem wordt geproduceerd.

Watermerkgeneratie. buildPageWatermark genereert PDF-contentstreamoperators voor één pagina: een geïsoleerde graphics state (q/Q), het standard-14 Helvetica-font via de resourcenaam /helvetica, de fill-tekstrendermodus, en een rotatiematrix die de tekst diagonaal door het paginacentrum plaatst. De standaardstijl is tekst van 48 pt op grijsniveau 0.85, geroteerd 45 graden. Het centreren benadert de tekstbreedte via het aantal glyphs — grafeemclusters wanneer intl geladen is, anders Unicode-codepoints via mbstring, met bytelengte als laatste fallback. Er worden bewust geen per-glyph advance-breedtes geraadpleegd. De watermerktekst wordt geëscaped als een PDF-literal-string volgens ISO 32000-2:2020 §7.3.4.2 (backslash en haakjes).

Metadatadecoratie. decorateProducer voegt de producer-suffix toe aan de /Producer-waarde. decorateSubject plaatst de subject-prefix vóór de /Subject-waarde; een lege subject levert de getrimde markering op, zodat een document zonder subject-metadata alsnog gemarkeerd wordt.

Byte-toepassing. BrandingApplicator::apply is de terminale consument van de branding-control. Met een inactieve strategie retourneert het de invoer byte-voor-byte. Met een actieve strategie voegt het één enkele incrementele update toe in de vorm die is gedefinieerd in ISO 32000-2:2020 §7.5.6: de originele bytes blijven intact, en het toegevoegde body bevat een gedecoreerd Info-object (dat het bestaande objectnummer hergebruikt), één watermerkcontentstream plus één bijgewerkt pagina-object per pagina, en een nieuwe cross-reference-stream (/Type /XRef, /W [1 4 2]) waarvan de /Prev terugwijst naar de vorige startxref. De transformatie is zuiver en deterministisch voor een gegeven invoer en configuratie.

Fail-closed-contract. Wanneer de strategie actief is, moet de invoer brandbaar zijn: een %PDF--header, geen /Encrypt-entry, geen object streams (/ObjStm), een cross-reference-stream-staart, en een /helvetica-fontresource die vanaf elke pagina oplosbaar is. Elke schending gooit een BrandingApplicationException in plaats van ongebrande bytes te retourneren. Aanroepers moeten de exception als terminaal behandelen en mogen de originele, ongemarkeerde bytes niet vastleggen.

Randgevallen en foutmodi

• Gebrande uitvoer betekent dat de licentiestatus evaluatie-stijl is. Dat weerspiegelt de licentiestatus, geen defect.
• Het watermerk is van ontwerp gecentreerd en diagonaal. Het is niet afstembaar voor productiegebruik; een betaalde licentie verwijdert het volledig.
• EvaluationBrandingConfig weigert lege watermerktekst, een niet-positieve fontgrootte en een grijsniveau buiten 0.0–1.0 met InvalidArgumentException.
• Een actieve strategie die geen wijziging aan Producer, Subject of watermerk oplevert, wordt geweigerd met BrandingApplicationException in plaats van bytes uit te geven die betaald lijken.
• Een pagina zonder bruikbare /MediaBox (afwezig of geërfd) krijgt een watermerk op de ISO 216 A4-standaard van 595.276 × 841.890 punten.
• /Contents in zowel enkelvoudige-referentie- als array-vorm worden beide ondersteund; de watermerkreferentie wordt als laatste toegevoegd zodat die bovenop tekent. Een pagina zonder /Contents krijgt er één.
• Info-stringwaarden behouden hun oorspronkelijke representatie bij het round-trippen: hexadecimale strings (UTF-16BE) blijven hexadecimaal, literal-strings blijven literal. Een ontbrekende sleutel wordt toegevoegd, hex-gecodeerd wanneer de waarde niet-ASCII-tekens bevat.
• Versleutelde documenten worden geweigerd: het herschrijven van stringobjecten onder /Encrypt zou de documentversleutelingssleutel vereisen.
• Fouten dragen de stabiele code SPEC-BRANDING-UNAPPLICABLE (BrandingApplicationException::SPEC_CODE) zodat consumerende pipelines onbrandbare uitvoer kunnen dead-letteren en auditen.
• De module voert geen cryptografische bewerkingen uit. De handtekeningverificatie van de licentie-envelop hoort bij het licensing-subsysteem; zie de Licensing-diepe-referentie.

Conformiteit

Claim	Standaard	Clausule
Incrementele updates voegen wijzigingen toe aan het einde van het bestand en laten de originele inhoud intact.	ISO 32000-2	§7.5.6
De cross-reference-sectie van de update dekt alleen gewijzigde objecten, en de toegevoegde trailer draagt een Prev-entry die de vorige cross-reference-sectie lokaliseert.	ISO 32000-2	§7.5.6
Literal-strings worden tussen haakjes geschreven; ongebalanceerde haakjes en de reverse solidus vereisen escape-behandeling.	ISO 32000-2	§7.3.4.2

Alle clausules zijn geparafraseerd; NextPDF reproduceert geen normatieve tekst. NextPDF doet geen certificeringsclaim. De applicator schrijft incrementele updates in de geciteerde ISO 32000-2-vorm als een capability-verklaring; het is geen gecertificeerde of onafhankelijk gevalideerde writer. Deze pagina beschrijft alleen runtime-gedrag. Ze geeft geen garantie, geen verklaring over geschiktheid of juridisch effect, en vormt geen juridisch advies; de voorwaarden van een evaluatie of abonnement worden uitsluitend gedefinieerd door de licentieovereenkomst.

Ontwikkelnotities

• BrandingMode, BrandingStrategy, beide strategieën en de config dragen @since 3.0.0; BrandingApplicator en BrandingApplicationException dragen @since 3.1.0.
• Het subsysteem voert geen netwerkaanroepen uit. De applicator leest alleen de structurele velden die het herschrijft: de strings van het Info-dictionary, de pagina-dictionaries en de cross-reference-staart.
• De licentie-envelop is een ondertekend artefact wiens issuer-handtekening de runtime verifieert. Licentieprovisioning, verlenging en veilige opslag zijn de verantwoordelijkheid van de operator.
• Alle concrete types zijn final; de strategieën en de config zijn ook readonly. Construeer een nieuwe config-instance om de watermerkstijl te wijzigen.
• Wanneer BrandingStrategy::isActive() false retourneert, garandeert dat identiteitswaarden van elke andere methode; aanroepers mogen daarop kortsluiten voor performance.
• De watermerkstream verwijst naar de resourcenaam /helvetica. Core registreert deze resource voor zijn eigen branding; een integratie die Core-branding uitschakelt moet ervoor zorgen dat de resource bestaat.
• De applicator berekent geen digest; de aanroeper her-berekent de digest van de gebrande bytes voordat die worden vastgelegd.
• Interne mechanismedetails blijven in de interne documentatie van de bronrepository en vallen buiten de scope van deze handleiding.

Publicatiegrens

Deze pagina documenteert alleen extern waarneembaar gedrag en het ondersteunde publieke API-oppervlak. Interne namespace-paden, helper-classes, mechanismetabellen, runbook-bestandsnamen en ticketprefixen vallen buiten de scope.

Zie ook

• Branding — capabilitypagina voor het evaluatie-branding-subsysteem.
• Trial- en evaluatie-branding — het end-to-end evaluatieverhaal.
• Licensing — diepe referentie
• Enterprise-overzicht