Skip to content
PDF Oxide

Довідник PHP API

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

composer require oxide/pdf-oxide

Усі класи розташовані в просторі імен PdfOxide\. Потрібен PHP 8.2+ з увімкненим ext-ffi. Post-install хук Composer завантажує відповідну готову нативну бібліотеку; задайте PDF_OXIDE_CDYLIB_PATH, щоб указати на власну збірку, або PDF_OXIDE_SKIP_DOWNLOAD=1, щоб пропустити завантаження.

Про Rust API див. Довідник Rust API. Про Python API див. Довідник Python API. Про Node.js API див. Довідник Node.js API, а про WASM 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 Редагування, очищення метаданих, безповоротне вилучення, збереження
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 на місці: очищення метаданих, застосування безповоротних вилучень, встановлення продюсера та збереження.

use PdfOxide\DocumentEditor;

Конструктор

DocumentEditor::open(string $path): self

Відкрити PDF для редагування.

Вилучення

$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 Збій вилучення
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.

Наступні кроки