Branding — Référence détaillée

En bref

Cette page est la référence détaillée du module NextPDF\Enterprise\Branding. Le module marque la sortie d’évaluation et laisse la sortie payante intacte. Un BrandingMode résolu par la licence sélectionne une stratégie ; BrandingApplicator applique la stratégie résolue aux octets PDF rendus. Sous une licence payante, la transformation est l’identité : la sortie est inchangée octet pour octet, sans aucune modification de code requise. Pour le flux de travail d’évaluation, lis d’abord la page de capacité Branding.

Disponibilité et licence

Cette capacité est fournie dans NextPDF Enterprise (nextpdf/enterprise) et s’active avec une enveloppe de licence de niveau Enterprise. Un déploiement dépourvu de ce droit ne charge pas les classes de la capacité. Compare les éditions et obtiens une licence.

Le sous-système porte le code de capacité dédié enterprise.branding parce qu’il régit le comportement d’évaluation dans toutes les éditions. Le mode de branding est résolu à partir de l’enveloppe de licence signée au moment de l’exécution ; aucun indicateur applicatif ne le sélectionne. Une licence payante résout le mode sur None et ne produit jamais de sortie marquée. Il n’y a aucune version de production à basculer.

Surface d’API publique

Symbole	Paramètres	Comportement par défaut	Retourne	Lève ou échoue avec	Notes
BrandingMode	—	None ('none') : aucune modification	—	—	Énumération à valeur chaîne ; EvaluationWatermark ('evaluation') active le branding d’évaluation.
BrandingStrategy	—	Contrat consommé par les points d’intégration	—	—	Interface ; les appelants ne font jamais de branchement sur BrandingMode directement.
BrandingStrategy::isActive	—	false pour la stratégie nulle, true pour la stratégie d’évaluation	bool	—	false signifie que toutes les autres méthodes retournent des valeurs identitaires.
BrandingStrategy::buildPageWatermark	float $pageWidth, float $pageHeight (points)	Chaîne vide lorsqu’inactive ; opérateurs de filigrane diagonal lorsqu’active	string	—	Le flux suppose une ressource de police /helvetica sur la page.
BrandingStrategy::decorateProducer	string $producer	Identité lorsqu’inactive ; ajoute le suffixe d’évaluation lorsqu’active	string	—	Suffixe par défaut : [EVALUATION].
BrandingStrategy::decorateSubject	string $subject	Identité lorsqu’inactive ; ajoute le préfixe d’évaluation au début lorsqu’active	string	—	Un sujet vide produit le marqueur rogné.
BrandingStrategyFactory::create	BrandingMode $mode, ?EvaluationBrandingConfig $config = null	Associe None à NullBrandingStrategy, EvaluationWatermark à EvaluationBrandingStrategy	BrandingStrategy	—	Statique ; une config null utilise les valeurs par défaut.
EvaluationBrandingConfig::__construct	Six paramètres nommés optionnels (texte, suffixe, préfixe, taille, gris, angle)	Valeurs par défaut : 48 pt, gris 0.85, 45 degrés	Instance	InvalidArgumentException en cas de texte vide, de taille de police non positive ou de gris hors de 0.0–1.0	final readonly ; immuable.
EvaluationBrandingStrategy	EvaluationBrandingConfig optionnel	Applique le filigrane et la décoration des métadonnées	—	—	final readonly ; implémente BrandingStrategy.
NullBrandingStrategy	—	Identité sur chaque méthode	—	—	Sélectionnée sous une licence payante.
BrandingApplicator::apply	string $pdfBytes, BrandingStrategy $strategy	Stratégie inactive : entrée retournée octet pour octet ; active : une mise à jour incrémentale ajoutée	string	BrandingApplicationException lorsque le branding actif ne peut pas être appliqué en toute sécurité	Transformation d’octets pure et déterministe.
BrandingApplicationException	—	Signal de défaillance terminal, fail-closed	—	—	Porte SPEC_CODE (SPEC-BRANDING-UNAPPLICABLE) ; fabrique unsupportedStructure().

Signatures des points d’entrée

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

Contrat de comportement

Résolution du mode et de la stratégie. L’état de la licence — et non le code applicatif — sélectionne le BrandingMode. BrandingStrategyFactory::create associe None à NullBrandingStrategy et EvaluationWatermark à EvaluationBrandingStrategy. Les points d’intégration consomment l’interface BrandingStrategy et n’inspectent jamais le mode directement, de sorte que la logique de branding reste centralisée. Sous une licence payante, la stratégie nulle est sélectionnée et la sortie est identique à celle produite sans aucun sous-système de branding.

Génération du filigrane. buildPageWatermark émet des opérateurs de flux de contenu PDF pour une page : un état graphique isolé (q/Q), la police Helvetica standard-14 via le nom de ressource /helvetica, le mode de rendu de texte par remplissage et une matrice de rotation qui place le texte en diagonale à travers le centre de la page. Le style par défaut est un texte de 48 pt au niveau de gris 0.85, pivoté de 45 degrés. Le centrage estime la largeur du texte d’après le nombre de glyphes — clusters de graphèmes lorsque intl est chargée, points de code Unicode via mbstring sinon, longueur en octets comme ultime repli. Aucune largeur d’avance par glyphe n’est consultée, par conception. Le texte du filigrane est échappé en tant que chaîne littérale PDF conformément à ISO 32000-2:2020 §7.3.4.2 (barre oblique inverse et parenthèses).

Décoration des métadonnées. decorateProducer ajoute le suffixe de producteur à la valeur /Producer. decorateSubject ajoute le préfixe de sujet au début de la valeur /Subject ; un sujet vide produit le marqueur rogné, de sorte qu’un document sans métadonnée de sujet est tout de même marqué.

Application des octets. BrandingApplicator::apply est le consommateur terminal du contrôle de branding. Avec une stratégie inactive, il retourne l’entrée octet pour octet. Avec une stratégie active, il ajoute une unique mise à jour incrémentale dans la forme définie par ISO 32000-2:2020 §7.5.6 : les octets d’origine restent intacts, et le corps ajouté contient un objet Info décoré (réutilisant le numéro d’objet existant), un flux de contenu de filigrane plus un objet de page mis à jour par page, et un nouveau flux de références croisées (/Type /XRef, /W [1 4 2]) dont le /Prev pointe vers le startxref précédent. La transformation est pure et déterministe pour une entrée et une configuration données.

Contrat fail-closed. Lorsque la stratégie est active, l’entrée doit être « brandable » : un en-tête %PDF-, aucune entrée /Encrypt, aucun flux d’objets (/ObjStm), une fin de fichier à flux de références croisées, et une ressource de police /helvetica résoluble depuis chaque page. Toute violation lève BrandingApplicationException au lieu de retourner des octets non marqués. Les appelants doivent traiter l’exception comme terminale et ne doivent pas valider les octets d’origine non marqués.

Cas limites et modes de défaillance

• Une sortie marquée signifie que l’état de la licence est de type évaluation. Cela reflète l’état de la licence, non un défaut.
• Le filigrane est centré et diagonal par conception. Il n’est pas ajustable pour un usage en production ; une licence payante le supprime entièrement.
• EvaluationBrandingConfig rejette un texte de filigrane vide, une taille de police non positive et un niveau de gris hors de 0.0–1.0 avec InvalidArgumentException.
• Une stratégie active qui ne produit aucune modification de Producer, Subject ou filigrane est refusée avec BrandingApplicationException plutôt que d’émettre des octets qui semblent payants.
• Une page sans /MediaBox exploitable (absente ou héritée) est filigranée à la valeur par défaut A4 ISO 216 de 595.276 × 841.890 points.
• /Contents sous forme de référence unique et sous forme de tableau sont tous deux pris en charge ; la référence du filigrane est ajoutée en dernier afin qu’elle se dessine par-dessus. Une page sans /Contents en reçoit un.
• Les valeurs de chaîne Info font l’aller-retour dans leur représentation d’origine : les chaînes hexadécimales (UTF-16BE) restent hexadécimales, les chaînes littérales restent littérales. Une clé absente est ajoutée, encodée en hexadécimal lorsque la valeur contient des caractères non ASCII.
• Les documents chiffrés sont refusés : réécrire des objets chaîne sous /Encrypt nécessiterait la clé de chiffrement du document.
• Les défaillances portent le code stable SPEC-BRANDING-UNAPPLICABLE (BrandingApplicationException::SPEC_CODE) afin que les pipelines consommateurs puissent mettre en file de rebut et auditer les sorties impossibles à marquer.
• Le module n’effectue aucune opération cryptographique. La vérification de la signature de l’enveloppe de licence relève du sous-système de licences ; voir la référence détaillée Licensing.

Conformité

Affirmation	Norme	Clause
Les mises à jour incrémentales ajoutent les modifications à la fin du fichier et laissent le contenu d’origine intact.	ISO 32000-2	§7.5.6
La section de références croisées de la mise à jour ne couvre que les objets modifiés, et le trailer ajouté porte une entrée Prev localisant la section de références croisées précédente.	ISO 32000-2	§7.5.6
Les chaînes littérales s’écrivent entre parenthèses ; les parenthèses déséquilibrées et la barre oblique inverse nécessitent un traitement d’échappement.	ISO 32000-2	§7.3.4.2

Toutes les clauses sont paraphrasées ; NextPDF ne reproduit pas le texte normatif. NextPDF ne formule aucune revendication de certification. L’applicateur écrit des mises à jour incrémentales dans la forme ISO 32000-2 citée à titre d’énoncé de capacité ; il ne s’agit pas d’un rédacteur certifié ni validé de manière indépendante. Cette page décrit uniquement le comportement à l’exécution. Elle ne fournit aucune garantie, aucune déclaration relative à l’éligibilité ou à l’effet juridique, et ne constitue pas un avis juridique ; les conditions d’une évaluation ou d’un abonnement sont définies exclusivement par le contrat de licence.

Notes de développement

• BrandingMode, BrandingStrategy, les deux stratégies et la config portent @since 3.0.0 ; BrandingApplicator et BrandingApplicationException portent @since 3.1.0.
• Le sous-système n’effectue aucun appel réseau. L’applicateur ne lit que les champs structurels qu’il réécrit : les chaînes du dictionnaire Info, les dictionnaires de page et la fin des références croisées.
• L’enveloppe de licence est un artefact signé dont le runtime vérifie la signature de l’émetteur. Le provisionnement, le renouvellement et le stockage sécurisé de la licence relèvent de la responsabilité de l’opérateur.
• Tous les types concrets sont final ; les stratégies et la config sont également readonly. Construis une nouvelle instance de config pour changer le style du filigrane.
• BrandingStrategy::isActive() retournant false garantit des valeurs identitaires de la part de toutes les autres méthodes ; les appelants peuvent court-circuiter dessus pour des raisons de performance.
• Le flux du filigrane référence le nom de ressource /helvetica. Core enregistre cette ressource pour son propre branding ; une intégration qui désactive le branding de Core doit s’assurer que la ressource existe.
• L’applicateur ne calcule aucun condensé ; l’appelant recalcule le condensé des octets marqués avant de les valider.
• Le détail du mécanisme interne reste dans la documentation interne du dépôt source et sort du périmètre de ce manuel.

Périmètre de publication

Cette page documente uniquement le comportement observable de l’extérieur et la surface d’API publique prise en charge. Les chemins de namespace internes, les classes utilitaires, les tables de mécanismes, les noms de fichiers de runbook et les préfixes de tickets sortent du périmètre.

Voir aussi

• Branding — page de capacité du sous-système de branding d’évaluation.
• Essai et branding d’évaluation — le parcours d’évaluation de bout en bout.
• Licensing — référence détaillée
• Vue d’ensemble Enterprise