Pro edycja

Konwerter

W skrócie

NextPDF\Pro\Converter odczytuje istniejący plik PDF i eksportuje jego zawartość do jednego z trzech celów tekstowych: rozmieszczonego HTML, uproszczonego SVG lub zwykłego tekstu. Jest eksporterem ekstrakcji zawartości, a nie rendererem PDF z dokładnością co do piksela.

Dostępność i licencjonowanie

Ta funkcja jest dostarczana w NextPDF Pro (nextpdf/pro) i aktywuje się z kopertą licencyjną poziomu Pro. Wdrożenie bez tego uprawnienia nie ładuje klas tej funkcji. Porównaj edycje i uzyskaj licencję.

Żadna flaga możliwości w czasie wykonywania nie bramkuje tego modułu. Klasy Converter rozwiązują się zawsze, gdy pakiet Pro jest zainstalowany i ładowany automatycznie.

Instalacja

composer require nextpdf/pro:^3

Przegląd koncepcyjny

Converter parsuje operatory pokazywania tekstu wewnątrz strumienia zawartości PDF — Tj, TJ oraz ' zgodnie z ISO 32000-2:2020 §9.4 — i odbudowuje przybliżoną reprezentację każdej strony. Odczytuje pozycjonowanie z operatorów tekstu Td i Tm oraz rozmiar czcionki z Tf, a następnie mapuje punkty na współrzędne wyjściowe.

Udostępnione są trzy konwertery, po jednym na ConversionTarget:

PdfToHtmlConverter zawija każdą stronę w pozycjonowany kontener i emituje bezwzględnie pozycjonowane elementy <div> dla każdego biegu tekstu. Wyjście to samodzielny dokument HTML5.
PdfToSvgConverter parsuje ograniczony zestaw operatorów rysujących (prostokąty przez re, linie przez m/l) oraz tekst i emituje pasujące elementy <rect>, <line> i <text> dla jednej strony.
PdfToTextConverter wyodrębnia wyłącznie zdekodowany tekst, strona po stronie, rozdzielony znacznikiem podziału strony.

To celowo ograniczony eksporter. Przybliża pozycję tekstu; nie wykonuje ponownego przepływu, nie rasteryzuje i nie odtwarza ścieżek wektorowych, cieniowania, przycinania, przezroczystości ani osadzonych obrazów. Aby uzyskać renderowanie HTML do PDF o pełnej wierności w przeciwnym kierunku, użyj potoku HTML z Core.

Dlaczego działa w ten sposób

PDF przechowuje tekst jako pozycjonowane operatory pokazywania glifów, a nie znaki semantyczne, więc nie istnieje wiarygodny tekst dokumentu do odczytania z powrotem. Dlatego Converter skanuje bezpośrednio operatory strumienia zawartości — Tj, TJ, ', plus Td, Tm i Tf dla rozmieszczenia — i odbudowuje przybliżony układ zamiast ponownego przepływu lub rasteryzacji strony. To ograniczone skanowanie sprawia, że eksport pozostaje liniowy względem długości bajtów, deterministyczny dla identycznego wejścia i bezpieczny na niezaufanych bajtach bez wykonywania osadzonej logiki. Wyznacza też uczciwy pułap: glify nie są odwrotnie mapowane na Unicode, więc czcionki z niestandardowym kodowaniem eksportują się jako surowe bajty, a dokładna wierność wizualna pozostaje poza zakresem. Tło projektowe: Dlaczego tekst w pliku PDF to nie naprawdę tekst.

Kontrakt zachowania

Wejście. Surowe bajty PDF (string). Pusty ciąg zgłasza InvalidArgumentException.
Wyjście. Obiekt wartości ConversionResult przechowujący wytworzony ciąg, ConversionTarget, liczbę przetworzonych stron oraz pomiar czasu przetwarzania.
Pokrycie. Eksport tekstu (Tj/TJ/') to ścieżka zweryfikowana, ćwiczona przez pakiet testów jednostkowych. Eksport SVG obejmuje wyłącznie prostokąty, proste linie i tekst. Kolor obrysu RGB nie jest jeszcze propagowany do wyjścia SVG.
Determinizm. Dla identycznego wejścia i konfiguracji wytworzony strumień bajtów HTML, SVG lub tekstu jest stabilny. Pole processingTimeMs to pomiar zegarowy i nie jest częścią deterministycznej powierzchni.
Kodowanie. Wyjście HTML jest poddawane ucieczce przez htmlspecialchars; wyjście SVG jest poddawane ucieczce XML. Powszechne sekwencje ucieczki ciągów PDF (\n, \r, \t, $, $, \\) są dekodowane dla celu tekstowego.

Publiczna powierzchnia API

Typ	Rodzaj	Kluczowe składowe
`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`

Przykład kodu — Szybki start

<?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;

Przykład kodu — Produkcja

<?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;
}

Przypadki brzegowe i pułapki

Plik PDF bez bloków tekstu BT/ET daje puste wyjście lub samą skorupę strony; zeskanowane (wyłącznie obrazowe) pliki PDF nie wytwarzają tekstu, ponieważ nie ma kroku OCR.
PdfToSvgConverter konwertuje jedną stronę na raz, wybieraną przez $pageIndex; indeks poza zakresem daje pusty strumień strony.
Pozycjonowanie jest przybliżone. Tekst umieszczony z przekształceniami nietekstowymi, tekst obrócony lub przepływ kolumnowy mogą nie odtworzyć pierwotnego układu wizualnego.
Mapowanie glifów na Unicode nie jest stosowane; tekst z czcionek używających niestandardowych kodowań może być eksportowany jako surowa sekwencja bajtów.

Wydajność

Parsowanie jest liniowe względem długości bajtów PDF. Pamięć śledzi wejście plus wytworzony ciąg wyjściowy. Frontmatter performance_budget to odniesienie na wywołanie dla typowego dokumentu biurowego.

Uwagi dotyczące bezpieczeństwa

Converter parsuje niezaufane bajty PDF z ograniczonym skanowaniem strpos/substr po operatorach tekstu; nie wykonuje osadzonego JavaScriptu ani nie podąża za odniesieniami zewnętrznymi. Traktuj wyeksportowany HTML jako zawartość niezaufaną i poddaj go odpowiedniej ucieczce dla jego celu. Zobacz model bezpieczeństwa Core.

Konformancja

Twierdzenie	Klauzula specyfikacji	Status
Operator pokazywania tekstu `Tj` sparsowany	ISO 32000-2:2020 §9.4	Verified (unit suite)
Operator tablicowy pokazywania tekstu `TJ` sparsowany	ISO 32000-2:2020 §9.4	Verified (unit suite)
Pełna wierność strony wektorowej/rastrowej	—	Not supported (out of scope)

Rozwiązanie awaryjne / alternatywa w Core

Nie istnieje odpowiednik w Core dla eksportu PDF. Dla kierunku do przodu (tworzenie pliku PDF z HTML) obsługiwaną ścieżką jest otwartoźródłowy potok HTML z Core. Zobacz /modules/core/html/.

Nota o granicy Enterprise

Converter to eksporter tekstu/kształtów poziomu Pro. Nie wykonuje OCR, rekonstrukcji semantycznej ani rozumienia dokumentu. To osobne kwestie, nieobsługiwane przez ten moduł.

Granica publikacji

Ta strona dokumentuje wyłącznie zachowanie obserwowalne zewnętrznie oraz obsługiwaną publiczną powierzchnię API. Wewnętrzne ścieżki przestrzeni nazw, klasy pomocnicze, tabele mechanizmów, nazwy plików runbooków oraz prefiksy zgłoszeń są poza zakresem.