Convertisseur

En bref

NextPDF\Pro\Converter lit un PDF existant et exporte son contenu vers l’une de trois cibles textuelles : HTML positionné, SVG simplifié ou texte brut. C’est un exportateur d’extraction de contenu, pas un moteur de rendu PDF 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é. Compare les éditions et obtiens une licence.

Aucun indicateur de capacité à l’exécution ne restreint ce module. Les classes du Converter se résolvent dès que le paquet Pro est installé et chargé automatiquement.

Installation

composer require nextpdf/pro:^3

Aperçu conceptuel

Le Converter analyse les opérateurs d’affichage de texte à l’intérieur d’un flux de contenu PDF — Tj, TJ et ' selon ISO 32000-2:2020 §9.4 — et reconstruit une représentation approximative de chaque page. Il lit le positionnement depuis les opérateurs de texte Td et Tm et la taille de police depuis Tf, puis mappe les points vers les coordonnées de sortie.

Trois convertisseurs sont exposés, un par ConversionTarget :

• PdfToHtmlConverter enveloppe chaque page dans un conteneur positionné et émet des éléments <div> en position absolue pour chaque suite de texte. La sortie est un document HTML5 autonome.
• PdfToSvgConverter analyse un ensemble limité d’opérateurs de dessin (rectangles via re, droites via m/l) plus le texte, et émet les éléments <rect>, <line> et <text> correspondants pour une page.
• PdfToTextConverter extrait uniquement le texte décodé, page par page, séparé par un marqueur de saut de page.

Il s’agit d’un exportateur délibérément borné. Il approxime la position du texte ; il ne réagence pas, ne rastérise pas et ne reproduit pas les tracés vectoriels, les dégradés, le détourage, la transparence ni les images embarquées. Pour un rendu HTML-vers-PDF en pleine fidélité dans la direction opposée, utilise le pipeline HTML de Core.

Pourquoi ça fonctionne ainsi

Un PDF stocke le texte sous forme d’opérateurs d’affichage de glyphes positionnés, et non de caractères sémantiques ; il n’existe donc aucun texte de document fiable à relire. Le Converter analyse par conséquent directement les opérateurs du flux de contenu — Tj, TJ, ', plus Td, Tm et Tf pour le placement — et reconstruit une disposition approximative au lieu de réagencer ou de rastériser la page. Ce balayage borné est ce qui maintient l’export linéaire par rapport à la longueur en octets, déterministe pour une entrée identique et sûr sur des octets non fiables sans exécuter de logique embarquée. Cela fixe aussi le plafond honnête : les glyphes ne sont pas remappés vers Unicode, de sorte que les polices à encodage personnalisé s’exportent en octets bruts et que la fidélité visuelle exacte reste hors périmètre. Contexte de conception : Pourquoi le texte d’un PDF n’est pas vraiment du texte.

Contrat de comportement

• Entrée. Octets PDF bruts (string). Une chaîne vide lève une InvalidArgumentException.
• Sortie. Un objet-valeur ConversionResult contenant la chaîne produite, le ConversionTarget, le nombre de pages traitées et une mesure du temps de traitement.
• Couverture. L’export de texte (Tj/TJ/') est le chemin vérifié, exercé par la suite unitaire. L’export SVG couvre uniquement les rectangles, les droites et le texte. La couleur de trait RGB n’est pas encore propagée à la sortie SVG.
• Déterminisme. Pour une entrée et une configuration identiques, le flux d’octets HTML, SVG ou texte produit est stable. Le champ processingTimeMs est une mesure de temps réel et ne fait pas partie de la surface déterministe.
• Encodage. La sortie HTML est échappée par htmlspecialchars ; la sortie SVG est échappée pour XML. Les séquences d’échappement de chaîne PDF courantes (\n, \r, \t, \(, \), \\) sont décodées pour la cible texte.

Surface d’API publique

Type	Genre	Membres clés
NextPDF\Pro\Converter\PdfToHtmlConverter	final class	convert(string $pdfData, ?ConversionConfig $config = null): ConversionResult
NextPDF\Pro\Converter\PdfToSvgConverter	final class	convert(string $pdfData, int $pageIndex = 0, ?ConversionConfig $config = null): ConversionResult
NextPDF\Pro\Converter\PdfToTextConverter	final class	convert(string $pdfData): ConversionResult, extractPage(string $pdfData, int $pageIndex): string
NextPDF\Pro\Converter\ConversionConfig	final readonly class	__construct(ConversionTarget $target, bool $embedFonts = false, bool $embedImages = true, float $scaleFactor = 1.0, string $cssClass = 'pdf-page')
NextPDF\Pro\Converter\ConversionResult	final readonly class	string $output, ConversionTarget $target, int $pageCount, float $processingTimeMs, size(): int, isValid(): bool
NextPDF\Pro\Converter\ConversionTarget	enum	Html5, Svg, PlainText ; mimeType(): string, fileExtension(): string

Exemple de code — Démarrage rapide

<?php

declare(strict_types=1);

use NextPDF\Pro\Converter\PdfToTextConverter;

$pdf    = file_get_contents('report.pdf');
$result = (new PdfToTextConverter())->convert($pdf);

echo $result->pageCount, " pages, ", $result->size(), " bytes of text\n";
echo $result->output;

Exemple de code — Production

<?php

declare(strict_types=1);

use NextPDF\Pro\Converter\ConversionConfig;
use NextPDF\Pro\Converter\ConversionTarget;
use NextPDF\Pro\Converter\PdfToHtmlConverter;

function exportPreview(string $pdfBytes): string
{
    if ($pdfBytes === '') {
        throw new InvalidArgumentException('empty PDF payload');
    }

    $config = new ConversionConfig(
        target: ConversionTarget::Html5,
        scaleFactor: 1.0,
        cssClass: 'doc-preview',
    );

    $result = (new PdfToHtmlConverter())->convert($pdfBytes, $config);

    if (! $result->isValid()) {
        throw new RuntimeException('converter produced no output');
    }

    return $result->output;
}

Cas limites et pièges

• Un PDF sans bloc de texte BT/ET produit une sortie vide ou réduite à la coque de page ; les PDF scannés (uniquement composés d’images) ne produisent aucun texte, car il n’y a pas d’étape d’OCR.
• PdfToSvgConverter convertit une seule page à la fois, sélectionnée par $pageIndex ; un indice hors plage produit un flux de page vide.
• Le positionnement est approximatif. Le texte placé avec des transformations non textuelles, le texte pivoté ou la mise en colonnes peut ne pas reproduire sa disposition visuelle d’origine.
• Le mappage glyphe-vers-Unicode n’est pas appliqué ; le texte issu de polices utilisant des encodages personnalisés peut s’exporter sous la forme de la séquence d’octets brute.

Performance

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 performance_budget du front-matter est la référence par invocation pour un document de bureau typique.

Notes de sécurité

Le convertisseur analyse des octets PDF non fiables avec un balayage borné par strpos/substr sur les opérateurs de texte ; il n’exécute aucun JavaScript embarqué et ne suit aucune référence externe. Traite le HTML exporté comme du contenu non fiable et échappe-le de façon appropriée pour sa destination. Voir le modèle de sécurité de Core.

Conformité

Affirmation	Clause de spécification	Statut
Opérateur d’affichage de texte Tj analysé	ISO 32000-2:2020 §9.4	Vérifié (suite unitaire)
Opérateur de tableau d’affichage de texte TJ analysé	ISO 32000-2:2020 §9.4	Vérifié (suite unitaire)
Fidélité de page vectorielle/raster complète	—	Non pris en charge (hors périmètre)

Repli / alternative Core

Il n’existe aucun équivalent Core pour l’export de PDF. Pour la direction inverse (créer un PDF à partir de HTML), le pipeline HTML open source de Core est le chemin pris en charge. Voir /modules/core/html/.

Note de frontière Enterprise

Le Converter est un exportateur de texte/formes de l’édition Pro. Il n’effectue ni OCR, ni reconstruction sémantique, ni compréhension de document. Ce sont des préoccupations distinctes qui ne sont pas fournies par ce module.

Frontière de publication

Cette page documente uniquement le comportement observable de l’extérieur et la surface d’API publique prise en charge. Les chemins de namespace 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.

Voir aussi

• Converter — Référence détaillée
• Extraction
• Diff
• Pipeline HTML de Core