Pro édition

Convertisseur — référence approfondie

En bref

NextPDF\Pro\Converter exporte un PDF existant vers du HTML positionné, du SVG simplifié ou du texte brut, et segmente le contenu du document en régions structurelles typées. Cette référence approfondie énumère la surface de l’API publique, la matrice de couverture des opérateurs, le contrat de comportement et les modes de défaillance. C’est un exporteur d’extraction de contenu, pas un moteur de rendu au pixel près.

Disponibilité et licence

Cette fonctionnalité est fournie dans NextPDF Pro (nextpdf/pro) et s’active avec une enveloppe de licence de niveau Pro. Un déploiement sans ce droit ne charge pas les classes de la fonctionnalité. Comparer les éditions et obtenir une licence.

Aucun indicateur de fonctionnalité à l’exécution ne conditionne ce module. Les classes du convertisseur se résolvent dès que le paquet Pro est installé et sous licence.

Surface de l’API publique

Symbole	Paramètres	Comportement par défaut	Retour	Lève ou échoue avec	Notes
`PdfToHtmlConverter::convert()`	`string $pdfData`, `?ConversionConfig $config = null`	Exporte chaque page contenant du texte vers un seul document HTML5 autonome	`ConversionResult` (cible `Html5`)	`InvalidArgumentException` quand `$pdfData` est vide	Une config nulle utilise `ConversionTarget::Html5` par défaut
`PdfToSvgConverter::convert()`	`string $pdfData`, `int $pageIndex = 0`, `?ConversionConfig $config = null`	Exporte une page vers un document SVG autonome	`ConversionResult` (cible `Svg` ; `pageCount` vaut toujours 1)	`InvalidArgumentException` quand `$pdfData` est vide	Un `$pageIndex` hors plage produit un SVG limité à l’arrière-plan
`PdfToTextConverter::convert()`	`string $pdfData`	Extrait le texte décodé de toutes les pages, séparées par un marqueur de saut de page	`ConversionResult` (cible `PlainText`)	`InvalidArgumentException` quand `$pdfData` est vide	Seule cette cible décode les échappements de chaînes littérales
`PdfToTextConverter::extractPage()`	`string $pdfData`, `int $pageIndex`	Extrait le texte décodé d’une page indexée à partir de zéro	`string`	Ne lève pas ; renvoie `''` pour une page absente ou une entrée vide	Contrairement à `convert()`, aucune protection contre une entrée vide
`DocumentSegmentationEngine::segment()`	`string $pdfData`	Classe le contenu des pages en segments structurels typés à l’aide d’heuristiques spatiales et de police	`NextPDF\Pro\Interop\V1\Segment\DocumentSegmentation`	`InvalidArgumentException` quand l’entrée est vide ou que la structure du PDF ne peut pas être analysée	À base de règles ; n’effectue aucune inférence par IA
`ConversionConfig::__construct()`	`ConversionTarget $target`, `bool $embedFonts = false`, `bool $embedImages = true`, `float $scaleFactor = 1.0`, `string $cssClass = 'pdf-page'`	Paramètres de conversion immuables	`ConversionConfig`	—	`embedFonts` et `embedImages` sont acceptés mais non consommés en 3.1.0
`ConversionResult::size()`	—	Longueur en octets de la sortie produite	`int`	—	Champs publics en lecture seule : `output`, `target`, `pageCount`, `processingTimeMs`
`ConversionResult::isValid()`	—	Indique si la sortie est non vide	`bool`	—	Les coquilles de document HTML et SVG ne sont jamais vides ; vérifie plutôt `pageCount`
`ConversionTarget`	Cas adossés à des chaînes `Html5`, `Svg`, `PlainText`	Sélectionne la cible d’export	`mimeType(): string`, `fileExtension(): string`	—	`fileExtension()` correspond à `html`, `svg`, `txt`

Signatures des points d’entrée :

public function convert(string $pdfData, ?ConversionConfig $config = null): ConversionResult

public function convert(
    string $pdfData,
    int $pageIndex = 0,
    ?ConversionConfig $config = null,
): ConversionResult

public function convert(string $pdfData): ConversionResult
public function extractPage(string $pdfData, int $pageIndex): string

public function segment(string $pdfData): DocumentSegmentation

Contrat de comportement

Les entrées sont des octets PDF bruts ; les sorties sont un objet valeur ConversionResult. Les trois convertisseurs d’export partagent un modèle d’analyse : localiser les limites stream/endstream, isoler les blocs de texte BT/ET et analyser les opérateurs d’affichage de texte. Ils n’analysent pas la table de références croisées et ne décompressent pas les flux compressés. DocumentSegmentationEngine diffère : il résout le trailer, le catalogue et l’arbre des pages, et décompresse le contenu de page FlateDecode avant la classification.

Couverture des opérateurs :

Opérateur PDF	HTML	SVG	Texte
`Tj` (afficher une chaîne)	oui	oui	oui
`TJ` (afficher un tableau)	oui	oui	oui
`'` (déplacer + afficher)	non	non	oui
`Td` / `Tm` (position)	oui	oui	s.o.
`Tf` (taille de police)	oui	oui	s.o.
`re` (rectangle)	non	oui	non
`m` / `l` (ligne)	non	oui	non
`RG` (contour RVB)	non	oui (appliqué au contour des rectangles/lignes)	non
courbes, dégradés, détourage, images	non	non	non

Positionnement. Chaque bloc BT/ET résout une position à partir de sa première correspondance Td ou Tm ; Tm a la priorité quand les deux apparaissent. L’axe Y est inversé de l’espace utilisateur PDF vers l’espace de sortie en haut à gauche. La taille de police vaut 12 pt par défaut en l’absence de Tf.
Géométrie de page. HTML et SVG supposent une boîte de page A4 (595 x 842 pt) multipliée par scaleFactor. La racine SVG porte des attributs viewBox, largeur et hauteur correspondants au-dessus d’un rectangle d’arrière-plan blanc.
Couleur de contour. Les opérateurs RG sont résolus par position, de sorte qu’un flux qui change plusieurs fois de couleur de contour colore chaque rectangle et chaque ligne selon l’opérateur précédent le plus récent. Les composantes sont bornées à la plage 0..1 avant la conversion hexadécimale. Le remplissage des rectangles est toujours noir ; l’opérateur de remplissage rg n’est pas évalué.
Décodage des chaînes. La cible texte décode les échappements de chaînes littérales selon ISO 32000-2:2020 §7.3.4.2 : échappements nommés, codes octaux \ddd masqués sur un octet, continuations de ligne par barre oblique inverse et suppression des barres obliques inverses isolées. Les cibles HTML et SVG émettent les octets bruts entre parenthèses après échappement HTML ou XML ; elles ne décodent pas les échappements.
Assemblage de la sortie. La cible texte joint les textes des blocs par une espace, et les pages par --- Page Break --- encadré de lignes vides. La cible HTML émet un <div> positionné en absolu par bloc de texte à l’intérieur d’un conteneur par page portant la classe CSS configurée et un attribut data-page.
Déterminisme. Pour une entrée et une configuration identiques, les octets HTML, SVG ou texte produits sont stables. processingTimeMs est une mesure d’horloge murale et est exclu de la surface déterministe.

Cas limites et modes de défaillance

Entrée vide : chaque point d’entrée convert() et segment() lève InvalidArgumentException (« PDF data must not be empty »). Aucune sortie partielle n’est produite. extractPage() fait exception : il renvoie '' sans lever.
Les flux sans BT/ET sont ignorés par les convertisseurs HTML et texte. Un PDF ne contenant que de tels flux produit un pageCount de zéro avec une sortie texte vide ou une coquille HTML sans pages.
isValid() vérifie seulement que la sortie est non vide. Les convertisseurs HTML et SVG émettent toujours une coquille de document, donc isValid() reste true même quand aucun texte n’a été trouvé ; utilise pageCount (HTML, texte) pour détecter une extraction vide.
Le contenu FlateDecode n’est pas décompressé par les trois convertisseurs d’export. Les PDF uniquement compressés en exportent peu ou pas de contenu. segment(), lui, décompresse les flux de page FlateDecode.
segment() borne la décompression par la taille de chaque flux, le taux de compression et un budget cumulé. Un flux qui franchit un plafond dégrade vers un contenu de page vide au lieu d’épuiser la mémoire ; il ne lève pas.
segment() lève InvalidArgumentException quand le trailer, le décalage de références croisées, le catalogue du document ou l’arbre des pages ne peuvent pas être résolus.
L’indexation des pages diffère selon le convertisseur. Les convertisseurs HTML et texte comptent uniquement les flux contenant du texte ; le convertisseur SVG compte les flux contenant un opérateur graphique ou texte reconnu. Le même $pageIndex peut donc désigner des flux différents.
Les ajustements de crénage numériques TJ sont ignorés ; les chaînes du tableau sont concaténées sans espacement inter-glyphes.
Le mappage glyphe-vers-Unicode n’est pas appliqué. Le texte composé dans des polices à encodages personnalisés s’exporte sous forme de séquence d’octets brute.
Le texte pivoté, les transformations non textuelles et le flux en colonnes sont approximés par le positionnement de première correspondance et peuvent ne pas reproduire la mise en page d’origine.
Aucune opération cryptographique n’a lieu dans ce module, donc le mode FIPS n’a aucun comportement spécifique au module.

Conformité

NextPDF documente ses fonctionnalités au regard des clauses citées. Les déclarations de prise en charge décrivent le comportement implémenté ; ce ne sont pas des résultats de tests de conformité ni des certifications, et NextPDF ne détient aucune certification.

Affirmation	Clause de la spécification	Statut
Opérateur d’affichage de texte `Tj` analysé	ISO 32000-2:2020 §9.4	Vérifié (suite unitaire)
Opérateur d’affichage de texte par tableau `TJ` analysé	ISO 32000-2:2020 §9.4	Vérifié (suite unitaire)
Opérateur de déplacement et d’affichage `'` analysé (cible texte uniquement)	ISO 32000-2:2020 §9.4	Vérifié (suite unitaire)
Échappements de chaînes littérales décodés (cible texte uniquement)	ISO 32000-2:2020 §7.3.4.2	Implémenté ; octets renvoyés tels quels, l’interprétation du jeu de caractères est en aval
Construction de chemin `re`, `m`, `l` reconnue (cible SVG)	ISO 32000-2:2020 §8.5.2	Partiel : sous-ensemble sans courbes, fermeture ni évaluation du mode de peinture
Machine à états de texte complète et rendu de page	—	Non pris en charge (hors périmètre)

Le convertisseur analyse les opérateurs d’affichage de texte pour récupérer le contenu ; il n’implémente pas la machine à états de texte complète, de sorte que le positionnement des glyphes est approximatif plutôt qu’exact selon la spécification.

Notes de développement

L’analyse est linéaire par rapport à la longueur en octets du PDF. La mémoire suit l’entrée plus la chaîne de sortie produite. Le front matter performance_budget est la référence par invocation pour un document bureautique typique.
Les convertisseurs analysent des octets PDF non fiables avec un balayage borné strpos/substr. Ils n’exécutent aucun JavaScript embarqué et ne suivent aucune référence externe. Traite le HTML exporté comme du contenu non fiable et échappe-le pour sa destination.
La sortie HTML est échappée avec htmlspecialchars (ENT_QUOTES, HTML5) ; le texte SVG est échappé en XML. La classe cssClass configurée est échappée avant émission.
Consommation de la config : scaleFactor s’applique aux cibles HTML et SVG ; cssClass s’applique au HTML uniquement ; embedFonts et embedImages sont réservés et actuellement inutilisés ; le champ target ne remplace pas le format de sortie propre à un convertisseur.
Les convertisseurs d’export sont fournis depuis la 1.9.0 ; DocumentSegmentationEngine est fourni depuis la 2.1.0 et sous-tend l’outil MCP Pro segment_document et le contrat de segmentation Interop.
PdfPageExtractor et PdfPageData dans le même espace de noms sont internes au moteur de segmentation et ne font pas partie de l’API publique.

Périmètre de publication

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