Pro editie

Document — Diepe referentie

In een oogopslag

De Document-module levert drie Pro-samenstellingsprimitieven: splitsing op paginabereik, samenvoeging van meerdere documenten en de opbouw van de PDF Portfolio-dictionary (Collection). PdfSplitter haalt paginabereiken op naar zelfstandige, structureel conforme PDF’s en voegt hele documenten samen tot één hernummerd bestand. PdfPortfolio bouwt de Collection-dictionary die ingesloten bestanden presenteert met sorteerbare schemakolommen. Elk instappunt begrenst de invoergrootte en het aantal objecten tegen vijandige invoer.

Beschikbaarheid en licentie

Deze mogelijkheid wordt geleverd in NextPDF Pro (nextpdf/pro) en activeert met een licentie-envelop van het Pro-niveau. Een implementatie zonder dat recht laadt de klassen van de mogelijkheid niet. Vergelijk edities en verkrijg een licentie.

Publiek API-oppervlak

Alle moduletypen leven in de namespace NextPDF\Pro\Document. PageRange en MergeResult zijn Core-waardeobjecten uit NextPDF\Document.

Symbool	Parameters	Standaardgedrag	Retourneert	Gooit of faalt met	Opmerkingen
`PdfSplitter::split()`	`string $pdfData`, `list<PageRange> $ranges`, `int $maxBytes = 100_000_000`, `int $maxRanges = 1000`	Bouwt één zelfstandig PDF-segment per bereik	`SplitResult`	`InvalidArgumentException` bij een ontbrekende `%PDF`-header; `OverflowException` bij de grootte-, bereik-aantal- of closure-bewaking	Bewakingen draaien vóór elke parsing
`PdfSplitter::splitEvery()`	`string $pdfData`, `int $pagesPerSegment`	Leidt aaneengesloten N-paginabereiken af; het laatste segment kan korter zijn	`SplitResult`	`InvalidArgumentException` wanneer `$pagesPerSegment < 1` of de header ontbreekt	Delegeert aan `split()` met standaardplafonds
`PdfSplitter::extractPages()`	`string $pdfData`, `PageRange $range`	Retourneert één bereik als zelfstandige PDF-bytes	`string`	`InvalidArgumentException` bij een ontbrekende header; `OverflowException` bij de closure-bewaking	Geen plafondparameters op dit pad
`PdfSplitter::mergeDocuments()`	`list<string> $pdfs`, `int $maxInputs = 100`, `int $maxBytesEach = 100_000_000`	Voegt invoeren op volgorde samen tot één hernummerde PDF	`MergeResult`	`InvalidArgumentException` bij een lege lijst of niet-PDF-invoer; `OverflowException` bij de aantal-, per-invoer-grootte- of closure-bewaking	Sinds 3.1.0; de hoogste invoerversie bepaalt de uitvoer-header
`SplitResult`	readonly `$segments`, `$ranges`, `$totalPages`	Draagt ruwe segmentbytes plus bronmetadata	—	—	`final readonly` waardeobject
`SplitResult::count()`	—	Telt geproduceerde segmenten	`int`	—	—
`SplitResult::segment()`	`int $index`	Retourneert de bytes van één segment	`string`	`OutOfRangeException` bij een index buiten bereik	Nulgebaseerde index
`PdfPortfolio::__construct()`	`string $viewMode = 'tile'`	Valideert de weergavemodus bij constructie	—	`InvalidArgumentException` bij een andere modus dan `tile`, `detail`, `hidden`	—
`PdfPortfolio::addSchema()`	`PortfolioField $field`	Voegt een schemakolom toe	`self`	—	Vloeiend
`PdfPortfolio::addEntry()`	`PortfolioEntry $entry`	Voegt een bestandsvermelding toe	`self`	—	Vloeiend
`PdfPortfolio::getSchema()`	—	Retourneert de verzamelde schemavelden	`list<PortfolioField>`	—	—
`PdfPortfolio::getEntries()`	—	Retourneert de verzamelde bestandsvermeldingen	`list<PortfolioEntry>`	—	—
`PdfPortfolio::count()`	—	Telt bestandsvermeldingen	`int`	—	—
`PdfPortfolio::generateCollectionDictionary()`	—	Zendt de string van de Collection-dictionary uit	`string`	—	Schema- en sorteerblokken verschijnen alleen wanneer er velden bestaan
`PortfolioEntry`	`$filename`, `$data`, `$description = ''`, `$mimeType = 'application/octet-stream'`, `$customFields = []`	Onveranderbaar bestandsvermelding-waardeobject	—	—	`size()` retourneert de bytelengte van de data
`PortfolioField`	`$name`, `PortfolioFieldType $type`, `$displayName = ''`, `$order = 0`, `$visible = true`	Onveranderbaar schemakolom-waardeobject	—	—	`effectiveDisplayName()` valt terug op `$name`
`PortfolioFieldType`	String-enum: `Text`, `Date`, `Number`, `FileName`, `Description`, `Size`, `ModDate`, `CreationDate`	Wijst elke case toe aan een PDF `/Subtype` via `pdfSubtype()`	`string` (`S`, `D`, `N`, `F`, `Desc`)	—	Datumachtige cases delen subtype `D`; numerieke cases delen `N`

Handtekeningen van instappunten:

public function split(string $pdfData, array $ranges, int $maxBytes = 100_000_000, int $maxRanges = 1000): SplitResult

public function mergeDocuments(
    array $pdfs,
    int $maxInputs = 100,
    int $maxBytesEach = 100_000_000,
): MergeResult

public function __construct(
    private readonly string $viewMode = 'tile',
)

public function generateCollectionDictionary(): string

Gedragscontract

Splitsen en samenvoegen delen één objectgrafiek-pipeline:

Invoer moet beginnen met de %PDF-header. Grootte- en aantalbewakingen draaien vóór het parsen en werpen OverflowException bij overschrijding.
Bladpagina’s worden gedetecteerd door te scannen op pagina-objectmarkeringen; pagina-boomknopen worden uitgesloten van de telling.
De parser indexeert elk ongecomprimeerd indirect object met een stream-bewuste terminatorscan. Het eerste voorkomen van een object-id wint, dus incrementele-update-overschrijvingen worden niet toegepast.
Overerfbare pagina-boomattributen (/Resources, /MediaBox, /CropBox, /Rotate) worden op elke geëxtraheerde pagina gematerialiseerd door zijn /Parent-keten te doorlopen, zodat segmenten zelfstandig zijn.
De transitieve indirecte-referentie-closure van elke pagina wordt verzameld, met uitsluiting van de /Parent-terugverwijzing, en hernummerd naar een verse aaneengesloten id-ruimte.
De serializer zendt de header, de Catalog, de Pages-boom, de pagina-objecten en de closure-objecten uit, gevolgd door een kruisverwijzingstabel met byte-nauwkeurige offsets en een startxref die naar het xref-sleutelwoord wijst.
mergeDocuments herhaalt de pipeline per invoer in één gedeelde id-ruimte. De hoogste invoer-PDF-versie bepaalt de uitvoer-header. Het is de conforme vervanging voor de uitgeschakelde Core-merger, die fail-closed blijft.
De uitvoer is deterministisch. Er worden geen tijdstempels of willekeurige identifiers uitgezonden, dus identieke invoer levert identieke bytes op.

Portfolio-samenstelling:

De constructor valideert de weergavemodus. Het uitgezonden /View-token is /T, /D of /H voor respectievelijk tile, detail en hidden.
generateCollectionDictionary() zendt /Type /Collection, het /View-token, een /Schema-blok wanneer er velden bestaan, en een /Sort-directief op het eerste schemaveld, oplopend, uit.
Elk schemaveld zendt /Subtype (uit pdfSubtype()), /N (opgeschoonde weergavenaam), /O (volgorde) en /V (zichtbaarheid) uit.
Veldnamen worden opgeschoond naar geldige PDF-naamtokens; niet-woordtekens worden underscores. String-waarden worden ge-escaped als PDF-literaalstrings.
Bestandsvermeldingen worden blootgesteld via getEntries() voor inbedding door de schrijflaag. De Collection-dictionary zelf draagt alleen weergave, schema en sortering.

Randgevallen en foutmodi

Een bereik dat met geen enkele pagina overeenkomt levert een minimaal segment van één pagina op (612 x 792 MediaBox), geen fout.
Een document zonder detecteerbare pagina-markeringen wordt als één pagina geteld.
Pagina’s die binnen objectstreams zijn opgeslagen worden niet gedetecteerd; alleen ongecomprimeerde indirecte objecten nemen deel aan de extractie.
Wanneer er dubbele object-id’s bestaan, wordt de revisie met de laagste offset gebruikt; latere incrementele-update-revisies worden genegeerd.
De per-segment-referentie-closure is begrensd op 50.000 objecten; een kwaadwillig zelfverwijzende of fan-out-grafiek werpt OverflowException.
Standaardplafonds: 100 MB invoer, 1.000 bereiken, 100 samenvoeginvoeren. Alle zijn per aanroep instelbaar door de aanroeper.
splitEvery() weigert een segmentgrootte onder 1 met InvalidArgumentException.
SplitResult::segment() weigert een index buiten bereik met OutOfRangeException.
Twee schemaveldnamen die alleen in interpunctie verschillen worden opgeschoond naar dezelfde dictionary-sleutel; het latere veld overschaduwt stil het eerdere in het uitgezonden schema.
Deze module voert geen cryptografische bewerkingen uit; de FIPS-modus wijzigt zijn gedrag niet.

Conformiteit

De uitvoer van segment en samenvoeging volgt het pagina-objectmodel van ISO 32000-2; de bron annoteert de relevante clausules. Extern controleerbare claims:

Trailer-lay-out, startxref-byte-offset en de %%EOF-terminator volgen ISO 32000-2:2020, §7.5.5 — referentie ef0f2a4b563b84f81b3e6428612bc47c510d94fc8096849d339abf0f3247d845.
De /View-waarden van de Collection-dictionary (/T, /D, /H) volgen ISO 32000-2:2020, §12.3.5 — referentie 5cefaaeb40f3ff98e3aba135ac57c9424a05c43144c1b9b5156bfd4295e08ddd.
De /Subtype-, /N-, /O- en /V-vermeldingen van het Collection-veld volgen ISO 32000-2:2020, §12.3.5 (collection field dictionary) — referentie 6300fbfdc8a913a8dc6f6ae34eff99f2bd03c4313a77777cdd5a8dd856d9537a.

Deze uitspraken beschrijven geïmplementeerde mogelijkheden die door de tests van de module zijn geverifieerd. Ondersteuning voor een constructie is geen conformiteitsclaim, en conformiteit is geen certificering; NextPDF houdt geen certificering door derden voor deze module.

Ontwikkelnotities

Alle moduleklassen zijn final; de resultaat- en waardeobjecttypen zijn readonly. De splitter- en Portfolio-typen dateren van 1.9.0; mergeDocuments() werd toegevoegd in 3.1.0.
PageRange en MergeResult zijn Core-typen, dus aanroepplekken blijven editie-porteerbaar.
Segment-trailers dragen alleen /Size en /Root; er wordt geen /ID-bestandsidentifier of /Info-dictionary uitgezonden.
Geef voor incrementele-update- of ondertekeningsworkflows de segmentbytes aan de Writer-module in plaats van ze ter plaatse na te bewerken.
De module logt geen documentinhoud.

Publicatiegrens

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