Pro edizione

Legal — Riferimento approfondito

In breve

Genera timbri di numerazione Bates sequenziale come frammenti di content stream PDF per pagina.
Tre tipi pubblici: BatesNumberConfig (configurazione immutabile), BatesNumberer (motore), BatesPosition (enum di posizione a sei casi).
Ogni frammento è autonomo. Lo stato grafico viene salvato e ripristinato, quindi l’aggiunta non altera mai il contenuto esistente della pagina.
L’output è deterministico: un frammento è funzione pura della configurazione, del testo del timbro e delle dimensioni della pagina.
Il modulo non solleva eccezioni. Gli input fuori intervallo degradano secondo le regole di fallback documentate.

Disponibilità e licenze

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

Non esiste alcun flag di licenza per singola funzionalità. Si tratta di una funzionalità dell’edizione Pro.

composer require nextpdf/pro:^3

Superficie API pubblica

Simbolo	Parametri	Comportamento predefinito	Restituisce	Solleva o fallisce con	Note
`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`	Configurazione immutabile di aspetto e numerazione	`BatesNumberConfig`	—	Tutte e undici le proprietà sono public e readonly.
`BatesNumberConfig::formatNumber`	`int $pageIndex` (in base 0)	`prefix` + valore con riempimento di zeri (`startNumber + pageIndex`) + `suffix`	`string`	—	Un numero più largo di `padding` non viene troncato.
`BatesNumberConfig::getRange`	`int $pageCount`	Primo e ultimo timbro formattato della sequenza	`array{first: string, last: string}`	—	Presuppone `pageCount >= 1`; un conteggio pari a 0 formatta l’indice di pagina -1.
`BatesNumberer::__construct`	`BatesNumberConfig $config`	Associa la configurazione	`BatesNumberer`	—	La classe è final e readonly.
`BatesNumberer::generate`	`int $pageCount`, `array $pageSizes`, `string $prefix = ''`, `int $startFrom = 1`	Percorso rapido statico con aspetto predefinito	`list<string>`	—	Suffisso, posizione, font, opacità e layer restano ai valori predefiniti.
`BatesNumberer::generateStreams`	`int $pageCount`, `list<array{width: float, height: float}> $pageSizes`	Un frammento autonomo per pagina	`list<string>`	Non solleva mai eccezioni; una voce di dimensione mancante ricade su A4 verticale	Il numero di frammenti è pari a `pageCount`; le voci di dimensione in eccesso vengono ignorate.
`BatesNumberer::buildPageStream`	`string $text`, `float $pageWidth`, `float $pageHeight`	Costruisce il frammento del timbro di una pagina	`string`	—	Racchiuso tra `q`/`Q`; testo del timbro con escape per la sintassi delle stringhe letterali.
`BatesNumberer::getConfig`	—	Restituisce la configurazione associata	`BatesNumberConfig`	—	—
`BatesPosition`	casi enum `BottomLeft`, `BottomCenter`, `BottomRight`, `TopLeft`, `TopCenter`, `TopRight`	Vocabolario di posizioni con backing su stringa	—	—	I valori di backing sono in kebab-case (ad esempio `bottom-right`).
`BatesPosition::coordinates`	`float $pageWidth`, `float $pageHeight`, `float $textWidth`, `float $inset = 15.0`	X/Y per la baseline del timbro nello spazio nativo del PDF	`array{x: float, y: float}`	—	L’origine è in basso a sinistra; le righe superiori posizionano la baseline a `inset` dal bordo superiore.

Firme dei punti di ingresso

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

Contratto di comportamento

Numerazione

BatesNumberConfig::formatNumber calcola startNumber + pageIndex, riempie il numero a sinistra con zeri fino a padding cifre e lo racchiude con prefix e suffix. getRange restituisce il primo e l’ultimo timbro formattato per un conteggio di pagine. Utilizzarlo per concatenare la numerazione di continuazione tra più produzioni.

Anatomia del frammento

Ogni frammento è composto, nell’ordine: da un salvataggio dello stato grafico (q), un operatore di colore di riempimento, un inizio di marked-content opzionale, un blocco di testo che posiziona e mostra il timbro, una fine di marked-content opzionale e un ripristino (Q). Le coordinate e la dimensione del font sono serializzate con sei cifre decimali, quindi input identici producono byte identici. Il testo del timbro applica l’escape a \, ( e ) prima di entrare nella stringa letterale.

Associazione del font

Il blocco di testo seleziona il nome di risorsa font fisso /BatesFont. Il resource dictionary della pagina che incorpora il timbro deve mappare tale nome a un font corrispondente al fontFamily configurato, e la famiglia deve risolversi nel registro dei font. La generazione del frammento non consulta mai il registro.

Posizionamento

BatesPosition::coordinates calcola la baseline del timbro nello spazio nativo del PDF; l’origine è in basso a sinistra. Il posizionamento centrale e a destra sottrae una larghezza di testo stimata: lunghezza in byte per 0.6 per la dimensione del font, un’approssimazione monospace. I font proporzionali e il testo multibyte alterano tale stima. Il posizionamento a sinistra non ne dipende.

Layer

Con useLayer abilitato (impostazione predefinita), il frammento racchiude il testo tra gli operatori di marked-content BDC ed EMC. Il nome di marked-content ha la forma /Lyr_<name>, derivata da layerName sostituendo i caratteri non alfanumerici con trattini bassi. La racchiusura avviene solo a livello di frammento: la registrazione del corrispondente gruppo di contenuto opzionale nel documento — il passaggio che rende il layer attivabile in un viewer — spetta al writer che lo incorpora.

Opacità

Un valore di opacity inferiore a 1.0 viene emesso come riempimento in scala di grigi più chiaro. Un timbro completamente opaco viene reso in nero.

Ambito

Il motore applica la numerazione Bates esattamente come configurata. Non asserisce che un documento numerato sia ammissibile in tribunale o legalmente valido. Lo schema di numerazione, la conservazione e la gestione probatoria restano responsabilità del cliente; consultare i propri team legali e di compliance per la sufficienza procedurale.

Casi limite e modalità di errore

generateStreams non solleva mai eccezioni per una discrepanza in pageSizes. Una voce mancante ricade su A4 verticale, 595.276 per 841.890 punti; le voci in eccesso vengono ignorate.
Il numero di frammenti è sempre pari a pageCount.
Un numero più largo di padding non viene troncato; il testo del timbro si allunga semplicemente.
getRange presuppone pageCount >= 1. Un conteggio pari a 0 formatta l’indice di pagina -1, ossia startNumber - 1.
L’opacità è uno schiarimento in scala di grigi, non una trasparenza ExtGState; il contenuto sovrapposto sotto il timbro non viene fuso.
I byte del timbro diversi da \, ( e ) passano senza codifica. La correttezza della codifica per il testo non ASCII dipende dal font associato.
I marchi Bates sono contenuto sovrapposto. Non oscurano, rimuovono né cifrano alcun elemento della pagina.
Il modulo non esegue alcuna operazione crittografica; la modalità FIPS non ne altera il comportamento.

Conformità

Comportamento	Riferimento	Stato
Racchiusura in layer tramite gli operatori di marked-content `BDC`/`EMC`	ISO 32000-2:2020 §8.11.3.2	Parziale — il frammento emette la racchiusura; la registrazione del gruppo di contenuto opzionale è un passaggio del writer che lo incorpora

Queste righe registrano la specifica rispetto alla quale il modulo è costruito, non una certificazione; NextPDF non detiene alcuna certificazione di conformità. La tabella non è nemmeno una dichiarazione di validità legale o di sufficienza probatoria.

Note di sviluppo

I frammenti sono puri valori stringa. Testarli tramite confronto diretto dei byte; non è richiesto alcun contesto di documento.
buildPageStream è pubblico e testabile in isolamento a livello di unità: passare testo preformattato e dimensioni di pagina esplicite.
Per la numerazione di continuazione tra più produzioni, inizializzare startNumber dalla sequenza precedente e registrare l’output di getRange nel proprio log di produzione.
I nomi dei layer vengono sanificati a caratteri alfanumerici. Preferire nomi di layer ASCII affinché il nome di marked-content resti leggibile negli strumenti di ispezione.

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