Skip to content
PDF Oxide

Справочник PHP API

PDF Oxide поставляется с привязкой на чистом PHP, построенной на встроенном расширении PHP FFI. PHP-код — это тонкий слой над тем же cdylib libpdf_oxide, что используют привязки для Python, Node, Go, C#, Ruby и Java.

composer require oxide/pdf-oxide

Все классы находятся в пространстве имён PdfOxide\. Требуется PHP 8.2+ с включённым ext-ffi. Хук Composer, срабатывающий после установки, загружает подходящую готовую нативную библиотеку; задайте PDF_OXIDE_CDYLIB_PATH, чтобы указать на собственную сборку, или PDF_OXIDE_SKIP_DOWNLOAD=1, чтобы пропустить загрузку.

Справочник по Rust API см. в разделе Справочник Rust API. По Python API — в разделе Справочник Python API. По JavaScript API — в разделах Справочник Node.js API и Справочник WASM API.

Привязка предоставляет 10 классов:

Класс Назначение
PdfOxide\PdfDocument Открытие, чтение, извлечение и постраничный обход PDF
PdfOxide\Pdf Создание PDF (Markdown в PDF, HTML в PDF), версия, предзагрузка моделей
PdfOxide\PdfPage Лёгкое представление отдельной страницы
PdfOxide\MarkdownConverter Статическая конвертация в Markdown / HTML / обычный текст
PdfOxide\AutoExtractor Извлечение с типизированной причиной и классификация страниц
PdfOxide\AutoExtractResult Неизменяемый объект-значение с результатом для AutoExtractor
PdfOxide\DocumentEditor Редактирование, очистка метаданных, безвозвратное удаление (redaction), сохранение
PdfOxide\PdfSigner Подписание PAdES B-B / B-T / B-LT / B-LTA
PdfOxide\PdfValidator Проверки соответствия PDF/A, PDF/UA и PDF/X
PdfOxide\PdfPolicy Глобальная для процесса политика управления криптографией, задаваемая один раз

PdfDocument

Основной класс для открытия, чтения и извлечения PDF-файлов.

use PdfOxide\PdfDocument;

Конструкторы / фабричные методы

PdfDocument::open(string $path): self

Открыть PDF по пути к файлу.

PdfDocument::openBytes(string $bytes): self

Открыть PDF из строки байтов в памяти (например, загруженной из S3 или полученной по HTTP).

PdfDocument::extractTextOnce(string $path): string

Открыть файл, извлечь весь текст за один вызов и освободить дескриптор.

Сведения о документе

$doc->pageCount(): int

Вернуть количество страниц в документе.

$doc->version(): array

Вернуть версию PDF в виде массива целых чисел [major, minor].

$doc->hasStructureTree(): bool

Проверить, является ли документ тегированным PDF со структурным деревом.

$doc->hasFormFields(): bool

Проверить, содержит ли документ поля формы AcroForm.

$doc->hasSignatures(): bool

Проверить, содержит ли документ цифровые подписи.

$doc->getSourcePath(): ?string

Вернуть путь к исходному файлу, из которого был открыт документ, или null для документов, загруженных из байтов.

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

$doc->extractText(int $pageIndex): string

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

$doc->extractStructured(int $page): array

Извлечь структурированное содержимое страницы (фрагменты, символы и размеры) в виде ассоциативного массива.

$doc->extractTextAuto(int $pageIndex): string

Извлечь текст со страницы с автоматическим выбором между нативным текстом и OCR.

Конвертация

$doc->toMarkdown(int $pageIndex = 0): string

Преобразовать одну страницу в Markdown.

$doc->toMarkdownAll(): string

Преобразовать весь документ в Markdown.

$doc->toHtml(int $pageIndex = 0): string

Преобразовать одну страницу в HTML.

Доступ к страницам

$doc->page(int $index): PdfPage

Вернуть лёгкое представление PdfPage для указанного индекса, отсчитываемого с нуля.

$doc->pages(): array

Вернуть все страницы в виде массива объектов PdfPage.

$doc->pagesIter(): \Generator

Лениво обойти страницы, выдавая по одному объекту PdfPage за раз.

Жизненный цикл

$doc->isOpen(): bool

Вернуть, открыт ли ещё нативный дескриптор.

$doc->close(): void

Освободить нативный дескриптор. Также вызывается автоматически в __destruct().

$doc->getHandle(): CData

Вернуть сырой дескриптор FFI (для продвинутого использования / взаимодействия).

Pdf

Создание новых PDF из исходного содержимого и доступ к вспомогательным методам уровня библиотеки.

use PdfOxide\Pdf;

Фабричные методы

Pdf::fromMarkdown(string $markdown): self

Создать PDF из содержимого Markdown.

Pdf::fromHtml(string $html): self

Создать PDF из содержимого HTML.

Pdf::fromText(string $text): self

Создать PDF из обычного текста.

Сохранение

$pdf->save(): string

Отрендерить PDF и вернуть его байты в виде строки.

$pdf->saveTo(string $path): void

Отрендерить PDF и записать его по пути к файлу.

Вспомогательные методы библиотеки

Pdf::version(): string

Вернуть строку версии нижележащей нативной библиотеки.

Pdf::prefetchAvailable(): bool

Вернуть, доступна ли в этой сборке предзагрузка моделей OCR.

Pdf::prefetchModels(array $languages): string

Предзагрузить модели OCR для указанных кодов языков; возвращает строку статуса.

Pdf::VERSION  // string constant, e.g. "0.3.69"

Жизненный цикл

$pdf->isOpen(): bool
$pdf->close(): void
$pdf->getHandle(): CData

Проверить, освободить или получить сырой нативный дескриптор.

PdfPage

Лёгкое представление отдельной страницы, возвращаемое методами PdfDocument::page(), pages() или pagesIter().

use PdfOxide\PdfPage;

Методы

$page->parent(): PdfDocument

Вернуть документ-владелец PdfDocument.

$page->index(): int

Вернуть индекс страницы, отсчитываемый с нуля.

$page->text(): string

Извлечь обычный текст с этой страницы.

$page->textAuto(): string

Извлечь текст с этой страницы с автоматическим выбором между нативным текстом и OCR.

$page->toMarkdown(): string

Преобразовать эту страницу в Markdown.

$page->toHtml(): string

Преобразовать эту страницу в HTML.

$page->__toString(): string

Вернуть обычный текст страницы, когда объект используется в строковом контексте.

MarkdownConverter

Статические помощники для конвертации открытого PdfDocument в Markdown, HTML или обычный текст.

use PdfOxide\MarkdownConverter;

Методы

MarkdownConverter::toMarkdown(PdfDocument $doc, int $pageIndex): string

Преобразовать одну страницу в Markdown.

MarkdownConverter::toMarkdownAll(PdfDocument $doc): string

Преобразовать весь документ в Markdown.

MarkdownConverter::toHtml(PdfDocument $doc, int $pageIndex): string

Преобразовать одну страницу в HTML.

MarkdownConverter::toPlainText(PdfDocument $doc, int $pageIndex): string

Преобразовать одну страницу в обычный текст.

AutoExtractor

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

use PdfOxide\AutoExtractor;

Константы

Константа Значение Смысл
AutoExtractor::MODE_AUTO 0 Автоматический выбор нативного текста или OCR
AutoExtractor::MODE_TEXT_ONLY 1 Только нативный текст, без OCR
AutoExtractor::MODE_FORCE_OCR 2 Всегда запускать OCR

Фабричные методы

AutoExtractor::of(PdfDocument $doc, int $mode = self::MODE_AUTO): self

Создать экстрактор для документа с явно заданным режимом.

AutoExtractor::fast(PdfDocument $doc): self

Создать экстрактор, настроенный на скорость.

AutoExtractor::balanced(PdfDocument $doc): self

Создать экстрактор, балансирующий между скоростью и точностью.

AutoExtractor::highFidelity(PdfDocument $doc): self

Создать экстрактор, настроенный на максимальную точность.

Извлечение

$ex->extractText(): string

Извлечь текст из всего документа.

$ex->extractTextForPage(int $pageIndex): string

Извлечь текст с одной страницы.

$ex->extractAutoPage(int $pageIndex): AutoExtractResult

Извлечь одну страницу, вернув типизированный AutoExtractResult с причиной и уверенностью.

$ex->extractAutoDocument(): AutoExtractResult

Извлечь весь документ, вернув типизированный AutoExtractResult.

$ex->extractPageJson(int $pageIndex): string

Извлечь одну страницу в виде строки JSON.

$ex->extractDocumentJson(): string

Извлечь весь документ в виде строки JSON.

Классификация

$ex->classifyPageKind(int $pageIndex): string

Классифицировать одну страницу (например, text_layer, scanned, image_text, mixed, empty).

$ex->classifyDocumentKinds(): array

Классифицировать каждую страницу, вернув массив строк с типами страниц.

Аксессоры

$ex->document(): PdfDocument

Вернуть нижележащий PdfDocument.

$ex->mode(): int

Вернуть константу активного режима извлечения.

AutoExtractResult

Неизменяемый объект-значение, возвращаемый методами AutoExtractor::extractAutoPage() и extractAutoDocument().

use PdfOxide\AutoExtractResult;

Свойства

Свойство Тип Описание
text string Извлечённый текст
reason string Одна из констант REASON_*
confidence float Уверенность в диапазоне [0.0, 1.0]
ocrUsed bool Запускался ли OCR для этого результата
regions array Подробные сведения по каждой области
pagesNeedingOcr array Индексы страниц, которым всё ещё нужен OCR

Константы

Константа причины Значение
REASON_OK ok
REASON_NATIVE_TEXT_HIGH_CONFIDENCE native_text_high_confidence
REASON_NO_TEXT_LAYER_PRESENT no_text_layer_present
REASON_OCR_REQUESTED_BUT_UNAVAILABLE ocr_requested_but_unavailable
REASON_OCR_LOW_CONFIDENCE_FALLBACK ocr_low_confidence_fallback
REASON_IMAGE_TABLE_RECONSTRUCTED image_table_reconstructed
REASON_EMPTY empty
Константа типа Значение
KIND_TEXT_LAYER text_layer
KIND_SCANNED scanned
KIND_IMAGE_TEXT image_text
KIND_MIXED mixed
KIND_EMPTY empty

Методы

$result->isOk(): bool

Вернуть, прошло ли извлечение успешно без деградации.

$result->isOcrFallback(): bool

Вернуть, был ли задействован резервный путь из-за недоступности OCR или низкой уверенности.

DocumentEditor

Редактирование PDF на месте: очистка метаданных, применение безвозвратных удалений (redaction), установка производителя (producer) и сохранение.

use PdfOxide\DocumentEditor;

Конструктор

DocumentEditor::open(string $path): self

Открыть PDF для редактирования.

Удаление (redaction)

$editor->addRedaction(int $pageIndex, float $x1, float $y1, float $x2, float $y2): self

Поставить в очередь прямоугольную область удаления (координаты в пунктах PDF). Поддерживает цепочку вызовов — возвращает $this.

$editor->redactionCount(int $pageIndex): int

Вернуть количество ожидающих удалений на странице.

$editor->applyRedactionsDestructive(bool $scrubMetadata = true): int

Безвозвратно применить все поставленные в очередь удаления (при ошибке завершается отказом). Возвращает количество применённых; при необходимости очищает метаданные.

Метаданные

$editor->scrubMetadata(): self

Удалить метаданные документа. Поддерживает цепочку вызовов — возвращает $this.

$editor->getProducer(): string

Вернуть строку Producer документа.

$editor->setProducer(string $producer): self

Установить строку Producer документа. Поддерживает цепочку вызовов — возвращает $this.

Сведения о документе

$editor->version(): array

Вернуть версию PDF в виде массива [major, minor].

$editor->pageCount(): int

Вернуть количество страниц.

$editor->isModified(): bool

Вернуть, есть ли в документе несохранённые изменения.

$editor->sourcePath(): string

Вернуть путь к исходному файлу.

Сохранение

$editor->saveTo(string $path): void

Записать отредактированный PDF по пути к файлу.

$editor->save(): string

Отрендерить отредактированный PDF и вернуть его байты в виде строки.

Жизненный цикл

$editor->isOpen(): bool
$editor->close(): void
$editor->getHandle(): CData

Проверить, освободить или получить сырой нативный дескриптор.

PdfSigner

Цифровое подписание PAdES с уровнями соответствия B-B, B-T, B-LT и B-LTA.

use PdfOxide\PdfSigner;

Константы

Константа Значение Уровень
PdfSigner::LEVEL_B_B 0 PAdES B-B (базовый)
PdfSigner::LEVEL_B_T 1 PAdES B-T (с меткой времени)
PdfSigner::LEVEL_B_LT 2 PAdES B-LT (долгосрочный)
PdfSigner::LEVEL_B_LTA 3 PAdES B-LTA (долгосрочный с архивной меткой времени)

Конструктор / фабрика

PdfSigner::fromPkcs12(string $keystorePath, string $password): self

Создать подписанта из хранилища ключей PKCS#12 (.p12 / .pfx).

Подписание

$signer->sign(
    string $pdfBytes,
    string|int $level = self::LEVEL_B_B,
    ?string $tsaUrl = null,
    ?string $reason = null,
    ?string $location = null,
): string

Подписать байты PDF и вернуть байты подписанного PDF. Уровни выше B-B требуют tsaUrl. $level принимает порядковый номер LEVEL_B_* или короткий тег ('b', 't', 'lt', 'lta').

PdfSigner::signWithHandle(
    string $pdfBytes,
    CData $certificateHandle,
    string|int $level,
    ?string $tsaUrl = null,
    ?string $reason = null,
    ?string $location = null,
): string

Статический удобный метод: подписание без создания управляемого экземпляра подписанта. Вызывающая сторона сохраняет владение $certificateHandle.

Проверка

PdfSigner::verify(string $pdfBytes): bool

Вернуть, содержат ли байты PDF словарь подписи и диапазон байтов.

Жизненный цикл

$signer->isOpen(): bool
$signer->close(): void

Проверить или освободить учётные данные для подписания.

PdfValidator

Статические проверки соответствия PDF/A, PDF/UA и PDF/X для открытого PdfDocument.

use PdfOxide\PdfValidator;

Константы

Константа PDF/A Значение Константа PDF/UA Значение
PDFA_1B 0 PDFUA_1 1
PDFA_1A 1 PDFUA_2 2
PDFA_2B 2
PDFA_2A 3
PDFA_2U 4
PDFA_3B 5
PDFA_3A 6
PDFA_3U 7

Методы

PdfValidator::isPdfA(PdfDocument $doc, int $level = self::PDFA_1B): bool

Вернуть, соответствует ли документ заданному уровню PDF/A.

PdfValidator::isPdfUa(PdfDocument $doc, int $level = self::PDFUA_1): bool

Вернуть, соответствует ли документ заданному уровню PDF/UA.

PdfValidator::isPdfX(PdfDocument $doc): bool

Не реализовано — в pdf_oxide пока нет публичного валидатора PDF/X, доступного через C ABI. Вызов всегда выбрасывает BadMethodCallException.

PdfValidator::validatePdfA(PdfDocument $doc, int $level = self::PDFA_1B): array

Выполнить полную проверку PDF/A и вернуть структурированный массив с результатом (флаг соответствия плюс все нарушения).

PdfPolicy

Глобальная для процесса политика управления криптографией, задаваемая один раз. Должна быть настроена до открытия любого PDF.

use PdfOxide\PdfPolicy;

Константы

Константа Значение
PdfPolicy::COMPAT compat
PdfPolicy::STRICT strict
PdfPolicy::FIPS_STRICT fips_strict

Методы

PdfPolicy::current(): string

Вернуть активный режим политики.

PdfPolicy::set(string $mode): void

Установить глобальную для процесса политику (одну из констант политики). Задаётся один раз на процесс.

PdfPolicy::fipsAvailable(): bool

Вернуть, доступен ли криптопровайдер, прошедший валидацию FIPS.

PdfPolicy::activeProvider(): string

Вернуть имя активного криптопровайдера.

PdfPolicy::compat(): string
PdfPolicy::strict(): string
PdfPolicy::fipsStrict(): string

Удобные аксессоры, возвращающие строку соответствующего режима политики.

Обработка ошибок

Все ошибки, специфичные для PDF, наследуются от PdfOxide\Exceptions\PdfException. Специализированные подклассы позволяют перехватывать более узкие категории сбоев.

use PdfOxide\PdfDocument;
use PdfOxide\Exceptions\PdfException;

try {
    $doc = PdfDocument::open('file.pdf');
    echo $doc->extractText(0);
} catch (PdfException $e) {
    error_log("PDF error: {$e->getMessage()}");
}
Исключение (в PdfOxide\Exceptions\) Причина
PdfException Базовый класс для всех ошибок PDF
ParseException Некорректный или неразбираемый PDF
IoException Ошибка чтения/записи файла
NotFoundException Отсутствующий файл, страница или объект
EncryptionException Ошибка шифрования / пароля
ValidationException Недопустимый аргумент или ввод
SignatureException Ошибка подписания или проверки подписи
RedactionException Ошибка удаления (redaction)
SearchException Ошибка поиска
OptimizationException Ошибка оптимизации
ComplianceException Ошибка соответствия PDF/A или PDF/UA
AccessibilityException Ошибка доступности / тегирования
UnsupportedException Неподдерживаемая возможность или операция
InvalidStateException Операция над закрытым или недопустимым дескриптором
InternalError Внутренняя нативная ошибка

Полный пример

use PdfOxide\PdfDocument;
use PdfOxide\Pdf;
use PdfOxide\AutoExtractor;
use PdfOxide\DocumentEditor;
use PdfOxide\PdfSigner;
use PdfOxide\PdfValidator;

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

for ($i = 0; $i < $doc->pageCount(); $i++) {
    echo "Page {$i}: ", strlen($doc->extractText($i)), " chars\n";
}
echo $doc->toMarkdownAll();

// --- Auto-extraction with typed reasons ---
$ex = AutoExtractor::of($doc);
$result = $ex->extractAutoPage(0);
if (!$result->isOk()) {
    error_log("degraded extraction: {$result->reason}");
}
$doc->close();

// --- Creation ---
$pdf = Pdf::fromMarkdown("# Invoice\n\n**Total:** \$42.00\n");
$pdf->saveTo('invoice.pdf');
$pdf->close();

// --- Destructive redaction ---
$editor = DocumentEditor::open('in.pdf');
$editor->addRedaction(0, 100.0, 700.0, 300.0, 720.0);
$editor->applyRedactionsDestructive();
$editor->saveTo('redacted.pdf');
$editor->close();

// --- PAdES B-T signature ---
$signer = PdfSigner::fromPkcs12('certs/sign.p12', 'p12-password');
$signed = $signer->sign(
    pdfBytes: file_get_contents('contract.pdf'),
    level:    PdfSigner::LEVEL_B_T,
    tsaUrl:   'https://freetsa.org/tsr',
    reason:   'Final contract',
);
file_put_contents('signed.pdf', $signed);
$signer->close();

// --- Compliance check ---
$doc = PdfDocument::open('archive.pdf');
var_dump(PdfValidator::isPdfA($doc, PdfValidator::PDFA_2B));
$doc->close();

Other Language Bindings

PDF Oxide предоставляет нативные привязки для всех основных экосистем: Rust, Python, Node.js, WASM, C#, Golang, Java, Ruby, C++, Swift, Kotlin, Dart, R, Julia, Zig, Scala, Clojure, Objective-C, и Elixir.

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