Pro edizione

Documento

In breve

Il modulo Document suddivide un PDF in segmenti per intervallo di pagine e assembla PDF Portfolio (Collection) con colonne di schema ordinabili. Entrambe le operazioni sono delimitate a fronte di input ostili.

Disponibilità e licenza

Questa funzionalità è distribuita 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à. Document fa parte dell’edizione Pro, senza un flag di licenza separato per funzionalità. Confronta le edizioni e ottieni una licenza.

Installazione

composer require nextpdf/pro:^3

Il codice risiede sotto lo spazio dei nomi NextPDF\Pro\Document.

Panoramica concettuale

Vengono fornite due capacità:

PdfSplitter estrae intervalli di pagine in segmenti PDF autonomi. Rileva le pagine scansionando gli oggetti pagina nell’input grezzo e racchiude le pagine selezionate in un catalogo e un albero delle pagine minimali. Supporta la suddivisione per intervallo, la suddivisione a dimensione fissa (splitEvery) e l’estrazione di un singolo intervallo (extractPages).
PdfPortfolio costruisce un dizionario PDF Collection che aggrega allegati di file con uno schema definito. Supporta le modalità di visualizzazione tile, detail e hidden ed emette un dizionario adatto all’inclusione nel catalogo del documento.

Perché funziona così

Suddividere un PDF non è una fetta di byte. Un oggetto pagina fa riferimento a risorse, font e content stream condivisi tramite riferimento indiretto. Eredita inoltre /MediaBox e /Resources dai suoi antenati nell’albero delle pagine. Perciò lo splitter ricostruisce ogni segmento come un grafo di oggetti autosufficiente: attraversa la chiusura transitiva dei riferimenti delle pagine selezionate, materializza gli attributi ereditati, rinumera in uno spazio di id nuovo e scrive una tabella di cross-reference con offset precisi al byte. L’attraversamento della chiusura è delimitato, poiché un grafo con fan-out ostile potrebbe altrimenti trascinare una quantità illimitata di lavoro in un solo segmento. Il risultato si apre come un PDF autonomo valido, non come un frammento con riferimenti pendenti.

Contesto progettuale: L’anatomia di un file PDF.

Contratto di comportamento

PdfSplitter::split($pdfData, $ranges, $maxBytes = 100_000_000, $maxRanges = 1000) applica un limite sulla dimensione dell’input e un limite sul numero di intervalli, e rifiuta input che non inizia con l’header PDF.
splitEvery($pdfData, $pagesPerSegment) rifiuta una dimensione del segmento inferiore a 1; il segmento finale può contenere meno pagine.
PdfPortfolio rifiuta in fase di costruzione qualsiasi modalità di visualizzazione diversa da tile, detail o hidden.
addSchema() e addEntry() restituiscono il portfolio per il concatenamento fluente; generateCollectionDictionary() restituisce la stringa del dizionario Collection.
I nomi dei campi dello schema vengono sanificati per l’uso come oggetti name del PDF; i valori stringa vengono sottoposti a escape per le stringhe letterali del PDF.

Esempio di codice — Avvio rapido

Quanto segue riflette l’API pubblica documentata. Il repository non distribuisce un esempio eseguibile per questo modulo.

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

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

Esempio di codice — Produzione

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).
}

Casi limite e insidie

Lo splitter ricostruisce ogni segmento come un grafo di oggetti nuovo con una tabella di cross-reference reale e precisa al byte; i segmenti sono PDF autonomi validi. Rinumera in uno spazio di id nuovo anziché preservare il layout di byte sorgente, perciò affidare i byte del segmento al modulo Writer per i flussi di aggiornamento incrementale o di firma.
Un intervallo che non corrisponde ad alcuna pagina produce un segmento minimale di una pagina anziché un errore.
L’ordinamento del portfolio adotta per impostazione predefinita il primo campo dello schema, in ordine crescente.

Prestazioni

La suddivisione e l’assemblaggio del portfolio sono lineari rispetto alla dimensione dell’input e al numero di voci. Il limite predefinito dell’input è 100 MB e il limite predefinito degli intervalli è 1000; entrambi sono regolabili verso il basso dal chiamante. Misurare con documenti rappresentativi.

Note sulla sicurezza

Trattare l’input come non attendibile. I guard di dimensione e di conteggio delimitano l’uso delle risorse. Il modulo sanifica i nomi dei campi e sottopone a escape i valori stringa prima che raggiungano il dizionario di output. Non registra alcun contenuto del documento.

Conformità

Il dizionario Portfolio segue il modello PDF Collections e lo splitter segue il modello degli oggetti pagina definito da ISO 32000-2; la fonte annota le clausole pertinenti. Il corpus RAG non era disponibile al momento della stesura, quindi questa pagina non asserisce alcun identificatore di clausola esterno e limita le dichiarazioni di conformità al comportamento verificato dai test del modulo.

Nota sul confine Enterprise

Enterprise non modifica il comportamento di Document. Enterprise aggiunge funzionalità di fascia superiore di archiviazione e compliance documentate separatamente; non sono richieste per la suddivisione o l’assemblaggio del Portfolio.

Core fallback / alternativa

Senza Pro, usare le primitive documentali di base di NextPDF Core; la suddivisione per intervallo di pagine e l’assemblaggio del Portfolio sono aggiunte di Pro. Vedere /modules/document/.

Confine di pubblicazione

Questa pagina documenta solo il comportamento osservabile dall’esterno e la superficie dell’API pubblica supportata. Percorsi di spazi dei nomi interni, classi helper, tabelle di meccanismi, nomi di file di runbook e prefissi di ticket sono fuori ambito.