Skip to content
PDF Oxide

Начало работы с PDF Oxide (PHP)

PDF Oxide — самая быстрая PHP-библиотека для извлечения текста из PDF: в среднем 0,8 мс, 100% успешных тестов на 3830 PDF. Одна библиотека для извлечения, конвертации и создания PDF, построенная на том же ядре Rust, что и привязки для Python, Node, Go, C#, Ruby и Java.

Установка

composer require oxide/pdf-oxide

Хук Composer, срабатывающий после установки, загружает подходящую готовую нативную библиотеку для вашей платформы в vendor/oxide/pdf-oxide/lib/ (linux-x86_64, linux-aarch64, darwin-x86_64, darwin-arm64, windows-x64).

Требования: PHP 8.2+ (8.2, 8.3, 8.4, 8.5) с включённым ext-ffi. Проверьте командой php -m | grep -i ffi. На некоторых управляемых хостингах ext-ffi отключён; в этом случае используйте Docker-образ, например php:8.3-cli.

Открытие PDF

Используйте PdfDocument::open(), чтобы загрузить файл и изучить его метаданные.

use PdfOxide\PdfDocument;

$doc = PdfDocument::open('research-paper.pdf');
echo $doc->pageCount(), " pages\n";

$version = $doc->version();   // ['major' => int, 'minor' => int]
printf("PDF version: %d.%d\n", $version['major'], $version['minor']);

$doc->close();   // или положитесь на __destruct()

Извлечение текста

Одна страница

Извлеките обычный текст с любой страницы по её индексу, отсчитываемому с нуля.

use PdfOxide\PdfDocument;

$doc = PdfDocument::open('report.pdf');
echo $doc->extractText(0);
$doc->close();

Все страницы

use PdfOxide\PdfDocument;

$doc = PdfDocument::open('book.pdf');
for ($i = 0; $i < $doc->pageCount(); $i++) {
    echo "--- Page " . ($i + 1) . " ---\n";
    echo $doc->extractText($i), "\n";
}
$doc->close();

Извлечение за один вызов

extractTextOnce() — это статический помощник, который открывает файл, извлекает текст со страницы 0 и закрывает документ за один вызов.

use PdfOxide\PdfDocument;

echo PdfDocument::extractTextOnce('report.pdf');

Извлечение с автоматическим выбором стратегии

extractTextAuto() возвращает нативный текст, если он есть, и аккуратно откатывается к любому тексту, который удаётся восстановить, — на этом резервном пути он никогда не выбрасывает исключение.

use PdfOxide\PdfDocument;

$doc = PdfDocument::open('mixed.pdf');
echo $doc->extractTextAuto(0);
$doc->close();

Page API

pages() возвращает массив представлений PdfPage, а pagesIter() лениво выдаёт их вместе с индексом. Каждая страница делегирует извлечение обратно документу.

use PdfOxide\PdfDocument;

$doc = PdfDocument::open('paper.pdf');

foreach ($doc->pagesIter() as $index => $page) {
    echo "Page {$index}:\n";
    echo $page->text(), "\n";
}

// Или возьмите одну страницу напрямую:
$page = $doc->page(0);
echo $page->toMarkdown();

$doc->close();

Методы PdfPage: index(), parent(), text(), textAuto(), toMarkdown(), toHtml().

Конвертация в Markdown и HTML

Преобразуйте отдельную страницу или весь документ в Markdown либо отрендерите страницу в HTML.

use PdfOxide\PdfDocument;

$doc = PdfDocument::open('paper.pdf');

echo $doc->toMarkdown(0);     // одна страница (по умолчанию страница 0)
echo $doc->toMarkdownAll();   // весь документ
echo $doc->toHtml(0);         // одна страница в виде HTML

$doc->close();

Статический MarkdownConverter предоставляет те же преобразования, не требуя хранить индекс страницы на стороне вызова документа.

use PdfOxide\PdfDocument;
use PdfOxide\MarkdownConverter;

$doc = PdfDocument::open('paper.pdf');

echo MarkdownConverter::toMarkdown($doc, 0);
echo MarkdownConverter::toMarkdownAll($doc);
echo MarkdownConverter::toHtml($doc, 0);
echo MarkdownConverter::toPlainText($doc, 0);

$doc->close();

Структурированное извлечение

extractStructured() возвращает представление страницы с учётом её разметки в виде ассоциативного массива — области с их типом, текстом, ограничивающим прямоугольником и индексом колонки.

use PdfOxide\PdfDocument;

$doc = PdfDocument::open('paper.pdf');
$structured = $doc->extractStructured(0);

printf("Page %d: %.0f x %.0f\n",
    $structured['page_index'],
    $structured['page_width'],
    $structured['page_height']);

foreach ($structured['regions'] as $region) {
    echo "[{$region['kind']}] {$region['text']}\n";
}

$doc->close();

Открытие из байтов

Откройте PDF из строки в памяти — удобно, когда вы получаете данные из S3, по HTTP или из базы данных.

use PdfOxide\PdfDocument;

$bytes = file_get_contents('report.pdf');
$doc = PdfDocument::openBytes($bytes);
echo $doc->extractText(0);
$doc->close();

Проверка возможностей документа

Изучите документ перед его обработкой.

use PdfOxide\PdfDocument;

$doc = PdfDocument::open('form.pdf');

var_dump($doc->hasStructureTree());   // тегированный PDF?
var_dump($doc->hasFormFields());      // поля AcroForm?
var_dump($doc->hasSignatures());      // цифровые подписи?

$doc->close();

Создание PDF

Класс Pdf предоставляет фабричные методы для построения PDF из Markdown, HTML или обычного текста.

use PdfOxide\Pdf;

$pdf = Pdf::fromMarkdown("# Invoice\n\n**Total:** \$42.00\n");
$pdf->saveTo('invoice.pdf');           // записать по пути
$pdf->close();

$pdf = Pdf::fromHtml('<h1>Report</h1><p>Quarterly figures.</p>');
$bytes = $pdf->save();                 // или получить сырые байты
file_put_contents('report.pdf', $bytes);
$pdf->close();

$pdf = Pdf::fromText("Plain text document.\n\nSecond paragraph.");
$pdf->saveTo('notes.pdf');
$pdf->close();

Дальнейшие шаги