Pro phiên bản

Converter

Tổng quan nhanh

NextPDF\Pro\Converter đọc một PDF hiện có và xuất nội dung của nó sang một trong ba đích dạng văn bản: HTML có định vị, SVG đơn giản hóa, hoặc văn bản thuần. Đây là một bộ xuất trích nội dung, không phải một bộ kết xuất PDF chính xác đến từng pixel.

Tình trạng sẵn có & cấp phép

Năng lực này có trong NextPDF Pro (nextpdf/pro) và được kích hoạt bằng một gói giấy phép bậc Pro. Một triển khai không có quyền này sẽ không nạp các lớp của năng lực. So sánh các phiên bản và nhận giấy phép.

Không có cờ năng lực lúc chạy nào kiểm soát module này. Các lớp Converter được phân giải bất cứ khi nào gói Pro được cài đặt và autoload.

Cài đặt

composer require nextpdf/pro:^3

Tổng quan khái niệm

Converter phân tích các toán tử hiển thị văn bản bên trong một content stream của PDF — Tj, TJ và ' theo ISO 32000-2:2020 §9.4 — và dựng lại một biểu diễn gần đúng của mỗi trang. Nó đọc thông tin định vị từ các toán tử văn bản Td và Tm và cỡ phông từ Tf, rồi ánh xạ các điểm sang tọa độ đầu ra.

Có ba bộ chuyển đổi được phơi bày, mỗi bộ cho một ConversionTarget:

PdfToHtmlConverter bọc mỗi trang trong một container có định vị và phát ra các phần tử <div> được định vị tuyệt đối cho mỗi đoạn văn bản. Đầu ra là một tài liệu HTML5 khép kín.
PdfToSvgConverter phân tích một tập hữu hạn các toán tử vẽ (hình chữ nhật qua re, đường qua m/l) cùng với văn bản, và phát ra các phần tử <rect>, <line> và <text> tương ứng cho một trang.
PdfToTextConverter chỉ trích xuất văn bản đã giải mã, theo từng trang, được phân tách bằng một dấu ngắt trang.

Đây là một bộ xuất có giới hạn một cách có chủ đích. Nó xấp xỉ vị trí văn bản; nó không reflow, không rasterize, và không tái tạo các đường dẫn vector, tô bóng, clipping, độ trong suốt hay hình ảnh nhúng. Để kết xuất HTML-sang-PDF đầy đủ độ trung thực theo hướng ngược lại, hãy dùng pipeline HTML của Core.

Vì sao nó hoạt động theo cách này

Một PDF lưu văn bản dưới dạng các toán tử hiển thị glyph có định vị, không phải các ký tự ngữ nghĩa, nên không có văn bản tài liệu đáng tin cậy để đọc lại. Do đó Converter quét trực tiếp các toán tử content-stream — Tj, TJ, ', cùng Td, Tm và Tf để xác định vị trí — và dựng lại một bố cục gần đúng thay vì reflow hay rasterize trang. Chính phép quét có giới hạn đó giữ cho việc xuất là tuyến tính theo độ dài byte, tất định với cùng đầu vào, và an toàn trên các byte không tin cậy mà không thực thi logic nhúng. Nó cũng đặt ra giới hạn trung thực: các glyph không được ánh xạ ngược sang Unicode, nên các phông mã hóa tùy chỉnh được xuất ra dưới dạng byte thô và độ trung thực trực quan chính xác nằm ngoài phạm vi. Bối cảnh thiết kế: Vì sao văn bản trong một PDF không thực sự là văn bản.

Hợp đồng hành vi

Đầu vào. Các byte PDF thô (string). Một chuỗi rỗng sẽ làm phát sinh InvalidArgumentException.
Đầu ra. Một đối tượng giá trị ConversionResult chứa chuỗi được tạo ra, ConversionTarget, số trang đã xử lý, và một phép đo thời gian xử lý.
Phạm vi. Xuất văn bản (Tj/TJ/') là đường đã được xác minh, được kiểm thử bởi bộ kiểm thử đơn vị. Xuất SVG chỉ bao gồm hình chữ nhật, đường thẳng và văn bản. Màu stroke RGB chưa được truyền vào đầu ra SVG.
Tính tất định. Với cùng đầu vào và cấu hình, chuỗi byte HTML, SVG hoặc văn bản được tạo ra là ổn định. Trường processingTimeMs là một phép đo thực tế và không thuộc về bề mặt tất định.
Mã hóa. Đầu ra HTML được escape bằng htmlspecialchars; đầu ra SVG được escape XML. Các chuỗi escape chuỗi PDF thông dụng (\n, \r, \t, $, $, \\) được giải mã cho đích văn bản.

Bề mặt API công khai

Kiểu	Loại	Thành viên chính
`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`

Mẫu mã — Khởi đầu nhanh

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

Mẫu mã — 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;
}

Trường hợp biên & lưu ý

Một PDF không có khối văn bản BT/ET sẽ cho ra đầu ra rỗng hoặc chỉ có vỏ-trang; các PDF được quét (chỉ-hình-ảnh) không tạo ra văn bản nào vì không có bước OCR.
PdfToSvgConverter chuyển đổi mỗi lần một trang, được chọn bằng $pageIndex; một chỉ số ngoài phạm vi sẽ cho ra một luồng trang rỗng.
Việc định vị là gần đúng. Văn bản được đặt bằng các phép biến đổi phi-văn-bản, văn bản xoay, hoặc luồng theo cột có thể không tái tạo bố cục trực quan ban đầu của nó.
Ánh xạ glyph-sang-Unicode không được áp dụng; văn bản từ các phông sử dụng mã hóa tùy chỉnh có thể được xuất ra dưới dạng chuỗi byte thô.

Hiệu năng

Việc phân tích là tuyến tính theo độ dài byte của PDF. Bộ nhớ theo sát đầu vào cộng với chuỗi đầu ra được tạo ra. Front-matter performance_budget là tham chiếu cho mỗi lần gọi với một tài liệu văn phòng điển hình.

Ghi chú về bảo mật

Bộ chuyển đổi phân tích các byte PDF không tin cậy bằng quét strpos/substr có giới hạn trên các toán tử văn bản; nó không thực thi JavaScript nhúng hay đi theo các tham chiếu ngoài. Hãy xem HTML đã xuất là nội dung không tin cậy và escape nó cho phù hợp với đích đến. Xem mô hình bảo mật của Core.

Sự phù hợp tiêu chuẩn

Tuyên bố	Điều khoản tiêu chuẩn	Trạng thái
Toán tử hiển thị văn bản `Tj` được phân tích	ISO 32000-2:2020 §9.4	Đã xác minh (bộ kiểm thử đơn vị)
Toán tử hiển thị văn bản mảng `TJ` được phân tích	ISO 32000-2:2020 §9.4	Đã xác minh (bộ kiểm thử đơn vị)
Độ trung thực trang vector/raster đầy đủ	—	Không hỗ trợ (ngoài phạm vi)

Phương án dự phòng / thay thế trong Core

Không có tương đương trong Core cho việc xuất PDF. Đối với hướng thuận (soạn một PDF từ HTML), pipeline HTML của Core mã nguồn mở là đường được hỗ trợ. Xem /modules/core/html/.

Ghi chú ranh giới Enterprise

Converter là một bộ xuất văn bản/hình dạng bậc Pro. Nó không thực hiện OCR, tái dựng ngữ nghĩa hay hiểu tài liệu. Đó là những mối quan tâm riêng và không được module này cung cấp.

Ranh giới xuất bản

Trang này chỉ ghi lại hành vi có thể quan sát từ bên ngoài và bề mặt API công khai được hỗ trợ. Các đường dẫn namespace nội bộ, lớp trợ giúp, bảng cơ chế, tên tệp runbook và tiền tố ticket nằm ngoài phạm vi.