Pro édition

Document

En un coup d’œil

Le module Document divise un PDF en segments par plage de pages et assemble des PDF Portfolios (Collections) avec des colonnes de schéma triables. Les deux opérations sont bornées face à des entrées hostiles.

Disponibilité et licence

Cette capacité est livrée dans NextPDF Pro (nextpdf/pro) et s’active avec une enveloppe de licence de niveau Pro. Un déploiement dépourvu de cette autorisation ne charge pas les classes de la capacité. Document fait partie de l’édition Pro, sans indicateur de licence distinct par fonctionnalité. Compare les éditions et obtiens une licence.

Installation

composer require nextpdf/pro:^3

Le code réside sous l’espace de noms NextPDF\Pro\Document.

Aperçu conceptuel

Deux capacités sont fournies :

PdfSplitter extrait des plages de pages dans des segments PDF autonomes. Il détecte les pages en balayant les objets de page de l’entrée brute et enveloppe les pages sélectionnées dans un catalogue et un arbre de pages minimaux. Il prend en charge la division par plages, la division à taille fixe (splitEvery) et l’extraction d’une plage unique (extractPages).
PdfPortfolio construit un dictionnaire PDF Collection qui agrège les pièces jointes avec un schéma défini. Il prend en charge les modes d’affichage tuile, détail et masqué, et émet un dictionnaire propre à être inclus dans le catalogue du document.

Pourquoi ça fonctionne ainsi

Diviser un PDF n’est pas une découpe d’octets. Un objet de page référence des ressources, des polices et des flux de contenu partagés par référence indirecte. Il hérite aussi de /MediaBox et /Resources de ses ancêtres dans l’arbre de pages. Le diviseur reconstruit donc chaque segment comme un graphe d’objets autonome : il parcourt la fermeture transitive des références des pages sélectionnées, matérialise les attributs hérités, renumérote dans un espace d’identifiants neuf et écrit une table de références croisées avec des décalages exacts à l’octet près. Le parcours de la fermeture est borné, car un graphe à éventail hostile pourrait sinon injecter un travail non borné dans un seul segment. Le résultat s’ouvre comme un PDF autonome valide, et non comme un fragment aux références pendantes.

Contexte de conception : L’anatomie d’un fichier PDF.

Contrat de comportement

PdfSplitter::split($pdfData, $ranges, $maxBytes = 100_000_000, $maxRanges = 1000) applique une limite de taille d’entrée et une limite de nombre de plages, et rejette une entrée qui ne commence pas par l’en-tête PDF.
splitEvery($pdfData, $pagesPerSegment) rejette une taille de segment inférieure à 1 ; le segment final peut contenir moins de pages.
PdfPortfolio rejette à la construction tout mode d’affichage autre que tuile, détail ou masqué.
addSchema() et addEntry() renvoient le portfolio pour un chaînage fluide ; generateCollectionDictionary() renvoie la chaîne du dictionnaire Collection.
Les noms de champ de schéma sont assainis pour servir d’objets de nom PDF ; les valeurs de chaîne sont échappées pour les chaînes littérales PDF.

Exemple de code — Démarrage rapide

Ce qui suit reflète l’API publique documentée. Le dépôt ne fournit pas d’exemple exécutable pour ce module.

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

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

Exemple de code — Production

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

Cas limites et pièges

Le diviseur reconstruit chaque segment comme un graphe d’objets neuf doté d’une vraie table de références croisées exacte à l’octet près ; les segments sont des PDF autonomes valides. Il renumérote dans un espace d’identifiants neuf plutôt que de préserver la disposition d’octets source, alors confie les octets de segment au module Writer pour les flux de mise à jour incrémentale ou de signature.
Une plage qui ne correspond à aucune page produit un segment minimal d’une page plutôt qu’une erreur.
Le tri du portfolio se fait par défaut sur le premier champ de schéma, en ordre croissant.

Performance

La division et l’assemblage de portfolio sont linéaires par rapport à la taille de l’entrée et au nombre d’entrées. Le plafond d’entrée par défaut est de 100 Mo et le plafond de plages par défaut est de 1000 ; les deux sont ajustables à la baisse par l’appelant. Mesure avec des documents représentatifs.

Notes de sécurité

Traite l’entrée comme non fiable. Les garde-fous de taille et de nombre bornent l’usage des ressources. Le module assainit les noms de champ et échappe les valeurs de chaîne avant qu’elles n’atteignent le dictionnaire de sortie. Il ne journalise aucun contenu de document.

Conformité

Le dictionnaire Portfolio suit le modèle PDF Collections et le diviseur suit le modèle d’objet de page défini par ISO 32000-2 ; la source annote les clauses pertinentes. Le corpus RAG était indisponible au moment de la rédaction ; cette page n’affirme donc aucun identifiant de clause externe et limite ses énoncés de conformité au comportement vérifié par les tests du module.

Note de frontière Enterprise

Enterprise ne change pas le comportement de Document. Enterprise ajoute des fonctionnalités d’archivage et de conformité de niveau supérieur, documentées séparément ; elles ne sont pas requises pour la division ou l’assemblage de Portfolio.

Repli / alternative Core

Sans Pro, utilise les primitives de document de base de NextPDF Core ; la division par plage de pages et l’assemblage de Portfolio sont des ajouts de Pro. Voir /modules/document/.

Frontière de publication

Cette page ne documente que le comportement observable de l’extérieur et la surface d’API publique prise en charge. Les chemins d’espaces de noms internes, les classes d’assistance, les tables de mécanismes, les noms de fichiers de runbook et les préfixes de tickets sont hors périmètre.