Pro édition

Legal — Référence approfondie

En un coup d’œil

Génère des tampons de numéros Bates séquentiels sous forme de fragments de flux de contenu PDF, page par page.
Trois types publics : BatesNumberConfig (configuration immuable), BatesNumberer (moteur), BatesPosition (énumération de position à six cas).
Chaque fragment est autonome. L’état graphique est sauvegardé puis restauré, si bien que l’ajout ne perturbe jamais le contenu existant de la page.
La sortie est déterministe : un fragment est une fonction pure de la configuration, du texte du tampon et de la taille de la page.
Le module ne lève aucune exception. Les entrées hors plage se dégradent selon les règles de repli documentées.

Disponibilité et licence

Cette fonctionnalité est fournie dans NextPDF Pro (nextpdf/pro) et s’active avec une enveloppe de licence de niveau Pro. Un déploiement dépourvu de ce droit ne charge pas les classes de la fonctionnalité. Comparer les éditions et obtenir une licence.

Il n’existe aucun indicateur de licence par fonctionnalité. Il s’agit d’une fonctionnalité de l’édition Pro.

composer require nextpdf/pro:^3

Surface d’API publique

Symbole	Paramètres	Comportement par défaut	Retourne	Lève ou échoue avec	Notes
`BatesNumberConfig::__construct`	`string $prefix = ''`, `string $suffix = ''`, `int $startNumber = 1`, `int $padding = 5`, `BatesPosition $position = BatesPosition::BottomRight`, `float $fontSize = 9.0`, `string $fontFamily = 'Courier'`, `float $opacity = 1.0`, `bool $useLayer = true`, `string $layerName = 'Bates Numbers'`, `float $inset = 15.0`	Configuration immuable de l’apparence et de la numérotation	`BatesNumberConfig`	—	Les onze propriétés sont toutes publiques et readonly.
`BatesNumberConfig::formatNumber`	`int $pageIndex` (indexé à partir de 0)	`prefix` + (`startNumber + pageIndex`) complété par des zéros + `suffix`	`string`	—	Un nombre plus large que `padding` n’est pas tronqué.
`BatesNumberConfig::getRange`	`int $pageCount`	Premier et dernier tampons formatés de la série	`array{first: string, last: string}`	—	Suppose `pageCount >= 1` ; un total de 0 formate l’index de page -1.
`BatesNumberer::__construct`	`BatesNumberConfig $config`	Lie la configuration	`BatesNumberer`	—	La classe est final et readonly.
`BatesNumberer::generate`	`int $pageCount`, `array $pageSizes`, `string $prefix = ''`, `int $startFrom = 1`	Chemin rapide statique avec apparence par défaut	`list<string>`	—	Le suffixe, la position, la police, l’opacité et le calque conservent leurs valeurs par défaut.
`BatesNumberer::generateStreams`	`int $pageCount`, `list<array{width: float, height: float}> $pageSizes`	Un fragment autonome par page	`list<string>`	Ne lève jamais ; une entrée de taille manquante bascule sur A4 portrait	Le nombre de fragments est égal à `pageCount` ; les entrées de taille en trop sont ignorées.
`BatesNumberer::buildPageStream`	`string $text`, `float $pageWidth`, `float $pageHeight`	Construit le fragment de tampon d’une page	`string`	—	Encadré par `q`/`Q` ; texte du tampon échappé pour la syntaxe de chaîne littérale.
`BatesNumberer::getConfig`	—	Retourne la configuration liée	`BatesNumberConfig`	—	—
`BatesPosition`	cas d’énumération `BottomLeft`, `BottomCenter`, `BottomRight`, `TopLeft`, `TopCenter`, `TopRight`	Vocabulaire de positions adossé à des chaînes	—	—	Les valeurs sous-jacentes sont en kebab-case (par exemple `bottom-right`).
`BatesPosition::coordinates`	`float $pageWidth`, `float $pageHeight`, `float $textWidth`, `float $inset = 15.0`	X/Y de la ligne de base du tampon dans l’espace natif PDF	`array{x: float, y: float}`	—	L’origine est en bas à gauche ; les rangées du haut placent la ligne de base à `inset` du bord supérieur.

Signatures des points d’entrée

public function __construct(
    public string $prefix = '',
    public string $suffix = '',
    public int $startNumber = 1,
    public int $padding = 5,
    public BatesPosition $position = BatesPosition::BottomRight,
    public float $fontSize = 9.0,
    public string $fontFamily = 'Courier',
    public float $opacity = 1.0,
    public bool $useLayer = true,
    public string $layerName = 'Bates Numbers',
    public float $inset = 15.0,
) {}

public static function generate(
    int $pageCount,
    array $pageSizes,
    string $prefix = '',
    int $startFrom = 1,
): array
public function generateStreams(int $pageCount, array $pageSizes): array
public function buildPageStream(string $text, float $pageWidth, float $pageHeight): string

public function coordinates(
    float $pageWidth,
    float $pageHeight,
    float $textWidth,
    float $inset = 15.0,
): array

Contrat de comportement

Numérotation

BatesNumberConfig::formatNumber calcule startNumber + pageIndex, complète le nombre à gauche avec des zéros jusqu’à padding chiffres, puis l’entoure de prefix et suffix. getRange retourne le premier et le dernier tampons formatés pour un nombre de pages. Utilise-le pour chaîner la numérotation de continuation entre plusieurs productions.

Anatomie d’un fragment

Chaque fragment se compose, dans l’ordre : d’une sauvegarde de l’état graphique (q), d’un opérateur de couleur de remplissage, d’un début de contenu marqué optionnel, d’un bloc de texte qui positionne et affiche le tampon, d’une fin de contenu marqué optionnelle et d’une restauration (Q). Les coordonnées et la taille de police sont sérialisées avec six décimales, si bien que des entrées identiques produisent des octets identiques. Le texte du tampon échappe \, ( et ) avant d’entrer dans la chaîne littérale.

Liaison de la police

Le bloc de texte sélectionne le nom de ressource de police fixe /BatesFont. Le dictionnaire de ressources de la page d’intégration doit associer ce nom à une police correspondant au fontFamily configuré, et la famille doit se résoudre dans le registre de polices. La génération du fragment elle-même ne consulte jamais le registre.

Placement

BatesPosition::coordinates calcule la ligne de base du tampon dans l’espace natif PDF ; l’origine est en bas à gauche. Le placement centré et à droite soustrait une largeur de texte estimée : la longueur en octets multipliée par 0.6 puis par la taille de police, une approximation monospace. Les polices proportionnelles et le texte multi-octets décalent cette estimation. Le placement à gauche n’en dépend pas.

Calques

Lorsque useLayer est activé (par défaut), le fragment encadre le texte entre les opérateurs de contenu marqué BDC et EMC. Le nom de contenu marqué a la forme /Lyr_<name>, dérivé de layerName avec les caractères non alphanumériques remplacés par des underscores. Cet encadrement se limite au niveau du fragment : l’enregistrement du groupe de contenu optionnel correspondant dans le document — l’étape qui rend le calque activable dans une visionneuse — revient au rédacteur d’intégration.

Opacité

Une opacity inférieure à 1.0 est émise sous forme de remplissage en niveaux de gris plus clair. Un tampon totalement opaque s’affiche en noir.

Portée

Le moteur applique la numérotation Bates exactement telle qu’elle est configurée. Il n’affirme pas qu’un document numéroté est recevable en justice ou juridiquement valide. Le schéma de numérotation, la conservation et le traitement probatoire restent de la responsabilité du client ; consulte tes équipes juridiques et de conformité pour la suffisance procédurale.

Cas limites et modes de défaillance

generateStreams ne lève jamais d’exception en cas de non-correspondance de pageSizes. Une entrée manquante bascule sur A4 portrait, 595.276 sur 841.890 points ; les entrées en trop sont ignorées.
Le nombre de fragments est toujours égal à pageCount.
Un nombre plus large que padding n’est pas tronqué ; le texte du tampon s’allonge simplement.
getRange suppose pageCount >= 1. Un total de 0 formate l’index de page -1, c’est-à-dire startNumber - 1.
L’opacité est un éclaircissement en niveaux de gris, non une transparence ExtGState ; le contenu superposé sous le tampon n’est pas fusionné.
Les octets du tampon autres que \, ( et ) passent sans encodage. La correction de l’encodage pour le texte non ASCII dépend de la police liée.
Les marques Bates sont un contenu en surimpression. Elles ne caviardent, ne suppriment ni ne chiffrent rien sur la page.
Le module n’effectue aucune opération cryptographique ; le mode FIPS ne modifie pas son comportement.

Conformité

Comportement	Référence	Statut
Encadrement du calque via les opérateurs de contenu marqué `BDC`/`EMC`	ISO 32000-2:2020 §8.11.3.2	Partielle — le fragment émet l’encadrement ; l’enregistrement du groupe de contenu optionnel est l’étape du rédacteur d’intégration

Ces lignes consignent la spécification par rapport à laquelle le module est conçu, non une certification ; NextPDF ne détient aucune certification de conformité. Le tableau n’est pas non plus une déclaration de validité juridique ou de suffisance probatoire.

Notes de développement

Les fragments sont des valeurs de chaîne pures. Teste-les par comparaison directe d’octets ; aucun contexte de document n’est requis.
buildPageStream est public et testable unitairement en isolation : passe un texte préformaté et des dimensions de page explicites.
Pour une numérotation de continuation entre plusieurs productions, initialise startNumber à partir de la série précédente et consigne la sortie de getRange dans ton journal de production.
Les noms de calque sont assainis en caractères alphanumériques. Préfère des noms de calque en ASCII pour que le nom de contenu marqué reste lisible dans les outils d’inspection.

Limite 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 sont hors du périmètre.