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의 post-install 훅이 사용 환경에 맞는 사전 빌드된 네이티브 라이브러리를 내려받습니다. 커스텀 빌드를 가리키게 하려면 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

파일을 열고, 한 번의 호출로 모든 텍스트를 추출한 뒤, 핸들을 해제합니다.

문서 정보

$doc->pageCount(): int

문서의 페이지 수를 반환합니다.

$doc->version(): array

PDF 버전을 [major, minor] 정수 배열로 반환합니다.

$doc->hasStructureTree(): bool

문서가 구조 트리를 가진 Tagged PDF인지 확인합니다.

$doc->hasFormFields(): bool

문서에 AcroForm 폼 필드가 들어 있는지 확인합니다.

$doc->hasSignatures(): bool

문서에 디지털 서명이 들어 있는지 확인합니다.

$doc->getSourcePath(): ?string

문서를 연 원본 파일 경로를 반환하며, 바이트로 불러온 문서의 경우 null을 반환합니다.

텍스트 추출

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

0부터 시작하는 인덱스의 단일 페이지에서 일반 텍스트를 추출합니다.

$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

주어진 0부터 시작하는 인덱스에 대한 경량 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

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

0부터 시작하는 페이지 인덱스를 반환합니다.

$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를 그 자리에서 편집합니다. 메타데이터 제거, 비가역적 묵음 처리 적용, 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();

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

다음 단계

• 타입 & 열거형 — 모든 공유 타입과 열거형
• Page API 레퍼런스 — 바인딩 간 일관된 페이지 단위 순회
• PHP 시작하기 — 튜토리얼