Pro editie

Document

In het kort

De Document-module splitst een PDF in segmenten op paginabereik en stelt PDF Portfolio’s (Collections) samen met sorteerbare schemakolommen. Beide bewerkingen zijn begrensd tegen vijandige invoer.

Beschikbaarheid en licentie

Deze functie zit in NextPDF Pro (nextpdf/pro) en wordt geactiveerd met een licentie-envelope van het Pro-niveau. Een deployment zonder die entitlement laadt de klassen van de functie niet. Document maakt deel uit van de Pro-editie, zonder aparte licentievlag per functie. Vergelijk edities en vraag een licentie aan.

Installatie

composer require nextpdf/pro:^3

De code bevindt zich onder de namespace NextPDF\Pro\Document.

Conceptueel overzicht

Er worden twee mogelijkheden geboden:

PdfSplitter extraheert paginabereiken naar op zichzelf staande PDF-segmenten. Deze detecteert pagina’s door te scannen naar paginaobjecten in de ruwe invoer en wikkelt de geselecteerde pagina’s in een minimale catalogus en paginaboom. Deze ondersteunt bereikgebaseerd splitsen, splitsen met vaste grootte (splitEvery) en extractie van één bereik (extractPages).
PdfPortfolio bouwt een PDF Collection-dictionary die bijlagen aggregeert met een gedefinieerd schema. Deze ondersteunt de weergavemodi tile, detail en hidden en zendt een dictionary uit die geschikt is voor opname in de documentcatalogus.

Waarom het zo werkt

Een PDF splitsen is geen byte-slice. Een paginaobject verwijst via indirecte referentie naar gedeelde resources, fonts en contentstreams. Het erft ook /MediaBox en /Resources van zijn voorouders in de paginaboom. Daarom reconstrueert de splitter elk segment als een op zichzelf staande objectgraaf: hij loopt de transitieve referentiesluiting van de geselecteerde pagina’s af, materialiseert de geërfde attributen, hernummert naar een verse id-ruimte en schrijft een cross-referencetabel met byte-nauwkeurige offsets. De sluitingswandeling is begrensd, want een vijandige fan-out-graaf zou anders onbegrensd werk in één segment kunnen trekken. Het resultaat opent als een geldige op zichzelf staande PDF, niet als een fragment met bungelende referenties.

Ontwerpachtergrond: De anatomie van een PDF-bestand.

Gedragscontract

PdfSplitter::split($pdfData, $ranges, $maxBytes = 100_000_000, $maxRanges = 1000) dwingt een invoergroottelimiet en een limiet op het aantal bereiken af, en wijst invoer af die niet met de PDF-header begint.
splitEvery($pdfData, $pagesPerSegment) wijst een segmentgrootte onder 1 af; het laatste segment kan minder pagina’s bevatten.
PdfPortfolio wijst bij constructie elke andere weergavemodus dan tile, detail of hidden af.
addSchema() en addEntry() retourneren de portfolio voor vloeiende chaining; generateCollectionDictionary() retourneert de Collection-dictionarystring.
Schemaveldnamen worden opgeschoond voor gebruik als PDF-name-objecten; stringwaarden worden ge-escaped voor PDF-letterlijke strings.

Codevoorbeeld — Snelstart

Het volgende weerspiegelt de gedocumenteerde publieke API. De repository levert geen uitvoerbaar voorbeeld voor deze module.

use NextPDF\Pro\Document\PdfSplitter;
use NextPDF\Document\PageRange;

$result = (new PdfSplitter())->split($pdfBytes, [new PageRange(1, 5)]);

Codevoorbeeld — Productie

use NextPDF\Pro\Document\PdfSplitter;
use NextPDF\Document\PageRange;

$splitter = new PdfSplitter();

try {
    $result = $splitter->split(
        $pdfBytes,
        [new PageRange(1, 10), new PageRange(11, 20)],
        maxBytes: 50_000_000,
        maxRanges: 100,
    );
} catch (\InvalidArgumentException $e) {
    // Input rejected (not a PDF, or limits exceeded).
}

Randgevallen en valkuilen

De splitter reconstrueert elk segment als een verse objectgraaf met een echte, byte-nauwkeurige cross-referencetabel; segmenten zijn geldige op zichzelf staande PDF’s. Hij hernummert naar een nieuwe id-ruimte in plaats van de bytelay-out van de bron te behouden, dus geef segmentbytes door aan de Writer-module voor workflows met incrementele update of ondertekening.
Een bereik dat met geen enkele pagina overeenkomt, levert een minimaal segment van één pagina op in plaats van een fout.
Portfoliosortering valt standaard terug op het eerste schemaveld, oplopend.

Prestaties

Splitsen en portfoliosamenstelling zijn lineair in de invoergrootte en het aantal vermeldingen. Het standaard invoerplafond is 100 MB en het standaard bereikplafond is 1000; beide zijn door de caller naar beneden bij te stellen. Meet met representatieve documenten.

Beveiligingsnotities

Behandel invoer als niet-vertrouwd. Grootte- en aantalbewakingen begrenzen het resourcegebruik. De module schoont veldnamen op en escapet stringwaarden voordat ze de uitvoer-dictionary bereiken. Deze logt geen documentinhoud.

Conformiteit

De Portfolio-dictionary volgt het PDF Collections-model en de splitter volgt het paginaobjectmodel zoals gedefinieerd door ISO 32000-2; de bron annoteert de relevante clausules. Het RAG-corpus was niet beschikbaar op het moment van schrijven, dus deze pagina beweert geen externe clausule-identifiers en beperkt conformiteitsuitspraken tot gedrag dat door de tests van de module is geverifieerd.

Enterprise-grensnotitie

Enterprise verandert het Document-gedrag niet. Enterprise voegt hoger-niveau archiverings- en compliancefuncties toe die apart worden gedocumenteerd; ze zijn niet vereist voor splitsen of Portfolio-samenstelling.

Core-fallback / alternatief

Zonder Pro gebruik je de basale documentprimitieven van NextPDF Core; splitsen op paginabereik en Portfolio-samenstelling zijn Pro-toevoegingen. Zie /modules/document/.

Publicatiegrens

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