PHP API リファレンス

PDF Oxide は、PHP 標準の FFI 拡張の上に構築された純 PHP バインディングを提供します。この PHP コードは、Python・Node・Go・C#・Ruby・Java の各バインディングと同じ libpdf_oxide cdylib をラップした薄いレイヤーです。

composer require oxide/pdf-oxide

すべてのクラスは PdfOxide\ 名前空間の下に置かれます。ext-ffi を有効にした PHP 8.2 以降が必要です。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 to PDF、HTML to 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

メモリ上のバイト文字列 (例: S3 からダウンロードしたり HTTP で受信したもの) から PDF を開きます。

PdfDocument::extractTextOnce(string $path): string

ファイルを開き、すべてのテキストを 1 回の呼び出しで抽出し、ハンドルを解放します。

ドキュメント情報

$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 を 1 つずつ生成します。

ライフサイクル

$doc->isOpen(): bool

ネイティブハンドルがまだ開いているかどうかを返します。

$doc->close(): void

ネイティブハンドルを解放します。__destruct() によって自動的にも呼ばれます。

$doc->getHandle(): CData

生の FFI ハンドルを返します (高度な用途 / 相互運用用)。

---

Pdf

ソースコンテンツから新しい PDF を生成し、ライブラリレベルのヘルパーにアクセスします。

use PdfOxide\Pdf;

ファクトリメソッド

Pdf::fromMarkdown(string $markdown): self

Markdown コンテンツから PDF を生成します。

Pdf::fromHtml(string $html): self

HTML コンテンツから PDF を生成します。

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 定数	値
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 定数	値
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 をその場で編集します。メタデータの除去、破壊的な墨消しの適用、Producer の設定、保存を行います。

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

B-B、B-T、B-LT、B-LTA の適合レベルに対応した PAdES デジタル署名を行います。

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

開かれた PdfDocument に対する静的な PDF/A、PDF/UA、PDF/X の適合性チェックです。

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 には現在、C ABI で公開された PDF/X バリデータが存在しません。呼び出すと常に 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();

他の言語のバインディング

PDF Oxide はあらゆる主要なエコシステム向けにネイティブバインディングを提供しています： Rust, Python, Node.js, WASM, C#, Golang, Java, Ruby, C++, Swift, Kotlin, Dart, R, Julia, Zig, Scala, Clojure, Objective-C, Elixir。

次のステップ

• 型と列挙型 — すべての共有型と列挙型
• Page API リファレンス — バインディング間で一貫したページ単位の反復処理
• PHP 入門 — チュートリアル