Pro editie

Legal — Diepe referentie

In één oogopslag

Genereert sequentiële Bates-nummerstempels als PDF-content-stream-fragmenten per pagina.
Drie publieke types: BatesNumberConfig (onveranderlijke configuratie), BatesNumberer (engine), BatesPosition (positie-enum met zes cases).
Elk fragment staat op zichzelf. De graphics state wordt opgeslagen en hersteld, zodat toevoegen de bestaande pagina-inhoud nooit verstoort.
De uitvoer is deterministisch: een fragment is een pure functie van configuratie, stempeltekst en paginaformaat.
De module gooit geen exceptions. Invoer buiten bereik degradeert volgens de gedocumenteerde fallback-regels.

Beschikbaarheid en licentie

Deze functionaliteit wordt geleverd in NextPDF Pro (nextpdf/pro) en activeert met een licentie-envelope op Pro-niveau. Een deployment zonder die entitlement laadt de klassen van de functionaliteit niet. Vergelijk edities en vraag een licentie aan.

Er bestaat geen licentieflag per functie. Dit is een functionaliteit op Pro-editieniveau.

composer require nextpdf/pro:^3

Publiek API-oppervlak

Symbool	Parameters	Standaardgedrag	Retourneert	Gooit of faalt met	Opmerkingen
`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`	Onveranderlijke configuratie van weergave en nummering	`BatesNumberConfig`	—	Alle elf properties zijn public en readonly.
`BatesNumberConfig::formatNumber`	`int $pageIndex` (0-gebaseerd)	`prefix` + met nullen opgevuld (`startNumber + pageIndex`) + `suffix`	`string`	—	Een getal breder dan `padding` wordt niet afgekapt.
`BatesNumberConfig::getRange`	`int $pageCount`	Eerste en laatste geformatteerde stempels voor de run	`array{first: string, last: string}`	—	Gaat uit van `pageCount >= 1`; een telling van 0 formatteert pagina-index -1.
`BatesNumberer::__construct`	`BatesNumberConfig $config`	Bindt de configuratie	`BatesNumberer`	—	De klasse is final en readonly.
`BatesNumberer::generate`	`int $pageCount`, `array $pageSizes`, `string $prefix = ''`, `int $startFrom = 1`	Statisch snelpad met standaardweergave	`list<string>`	—	Suffix, positie, lettertype, dekking en layer blijven op hun standaardwaarden.
`BatesNumberer::generateStreams`	`int $pageCount`, `list<array{width: float, height: float}> $pageSizes`	Eén op zichzelf staand fragment per pagina	`list<string>`	Gooit nooit; een ontbrekende formaat-entry valt terug op A4 staand	Het aantal fragmenten is gelijk aan `pageCount`; extra formaat-entries worden genegeerd.
`BatesNumberer::buildPageStream`	`string $text`, `float $pageWidth`, `float $pageHeight`	Bouwt het stempelfragment van één pagina	`string`	—	Verpakt in `q`/`Q`; stempeltekst ge-escaped voor literal-string-syntaxis.
`BatesNumberer::getConfig`	—	Retourneert de gebonden configuratie	`BatesNumberConfig`	—	—
`BatesPosition`	enum-cases `BottomLeft`, `BottomCenter`, `BottomRight`, `TopLeft`, `TopCenter`, `TopRight`	String-backed positievocabulaire	—	—	De backing-waarden zijn kebab-case (bijvoorbeeld `bottom-right`).
`BatesPosition::coordinates`	`float $pageWidth`, `float $pageHeight`, `float $textWidth`, `float $inset = 15.0`	X/Y voor de stempel-baseline in PDF-native ruimte	`array{x: float, y: float}`	—	De oorsprong ligt linksonder; bovenste rijen plaatsen de baseline `inset` vanaf de bovenrand.

Entry-point-signatures

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

Gedragscontract

Nummering

BatesNumberConfig::formatNumber berekent startNumber + pageIndex, vult het getal links met nullen op tot padding cijfers en verpakt het met prefix en suffix. getRange retourneert het eerste en laatste geformatteerde stempel voor een paginatelling. Gebruik het om vervolgnummering over producties heen aan elkaar te koppelen.

Anatomie van een fragment

Elk fragment is, op volgorde: een save van de graphics state (q), een fill-color-operator, een optioneel marked-content-begin, een tekstblok dat het stempel positioneert en toont, een optioneel marked-content-eind en een restore (Q). Coördinaten en de lettergrootte worden geserialiseerd met zes decimalen, zodat identieke invoer identieke bytes oplevert. De stempeltekst escaped \, ( en ) voordat die in de literal string terechtkomt.

Lettertypebinding

Het tekstblok selecteert de vaste font-resourcenaam /BatesFont. Het resource dictionary van de inbeddende pagina moet die naam mappen op een lettertype dat overeenkomt met de geconfigureerde fontFamily, en de familie moet in het lettertyperegister kunnen worden geresolved. De fragmentgeneratie zelf raadpleegt het register nooit.

Plaatsing

BatesPosition::coordinates berekent de stempel-baseline in PDF-native ruimte; de oorsprong ligt linksonder. Plaatsing in het midden en rechts trekt een geschatte tekstbreedte af: bytelengte maal 0,6 maal de lettergrootte, een monospace-benadering. Proportionele lettertypen en multibyte-tekst verschuiven die schatting. Plaatsing links is er niet van afhankelijk.

Lagen

Met useLayer ingeschakeld (de standaard) zet het fragment de tekst tussen de marked-content-operators BDC en EMC. De marked-content-naam heeft de vorm /Lyr_<name>, afgeleid van layerName waarbij niet-woordtekens worden vervangen door underscores. Het inklemmen is uitsluitend op fragmentniveau: het registreren van de bijbehorende optional content group in het document — de stap die de layer schakelbaar maakt in een viewer — hoort bij de inbeddende writer.

Dekking

Een opacity onder 1.0 wordt uitgestuurd als een lichtere grayscale-fill. Een volledig dekkend stempel rendert zwart.

Reikwijdte

De engine past Bates-nummering exact toe zoals geconfigureerd. Het stelt niet dat een genummerd document toelaatbaar is bij de rechtbank of juridisch geldig is. Het nummeringschema, de bewaring en de bewijsrechtelijke afhandeling blijven de verantwoordelijkheid van de klant; raadpleeg je juridische en compliance-teams voor procedurele toereikendheid.

Randgevallen en faalmodi

generateStreams gooit nooit bij een mismatch van pageSizes. Een ontbrekende entry valt terug op A4 staand, 595.276 bij 841.890 punten; extra entries worden genegeerd.
Het aantal fragmenten is altijd gelijk aan pageCount.
Een getal breder dan padding wordt niet afgekapt; de stempeltekst wordt gewoon langer.
getRange gaat uit van pageCount >= 1. Een telling van 0 formatteert pagina-index -1, dat wil zeggen startNumber - 1.
Dekking is een grayscale-verlichting, geen ExtGState-transparantie; overlappende inhoud onder het stempel wordt niet geblend.
Andere stempelbytes dan \, ( en ) gaan ongecodeerd door. De juistheid van de codering voor niet-ASCII-tekst hangt af van het gebonden lettertype.
Bates-markeringen zijn overlay-inhoud. Ze redigeren, verwijderen of versleutelen niets op de pagina.
De module voert geen cryptografische bewerkingen uit; de FIPS-modus verandert het gedrag niet.

Conformiteit

Gedrag	Referentie	Status
Layer-inklemming via de marked-content-operators `BDC`/`EMC`	ISO 32000-2:2020 §8.11.3.2	Gedeeltelijk — het fragment stuurt de inklemming uit; de registratie van de optional content group is de stap van de inbeddende writer

Deze rijen leggen de specificatie vast waartegen de module is gebouwd, niet een certificering; NextPDF beschikt over geen enkele conformiteitscertificering. De tabel is ook geen verklaring van juridische geldigheid of bewijsrechtelijke toereikendheid.

Ontwikkelnotities

Fragmenten zijn pure string-waarden. Test ze via directe byte-vergelijking; er is geen documentcontext nodig.
buildPageStream is public en geïsoleerd unit-testbaar: geef vooraf geformatteerde tekst en expliciete pagina-afmetingen mee.
Voor vervolgnummering over producties heen seed je startNumber vanuit de vorige run en leg je de uitvoer van getRange vast in je productielogboek.
Layer-namen worden gesaneerd tot woordtekens. Geef de voorkeur aan ASCII-layer-namen zodat de marked-content-naam leesbaar blijft in inspectietools.

Publicatiegrens

Deze pagina documenteert uitsluitend extern waarneembaar gedrag en het ondersteunde publieke API-oppervlak. Interne namespace-paden, helper-klassen, mechanismetabellen, runbook-bestandsnamen en ticket-prefixen vallen buiten de reikwijdte.