Skip to content
PDF Oxide

PHP-API-Referenz

PDF Oxide bringt ein reines PHP-Binding mit, das auf der eingebauten FFI-Erweiterung von PHP aufbaut. Der PHP-Code ist eine dünne Schicht über derselben libpdf_oxide-cdylib, die auch die Bindings für Python, Node, Go, C#, Ruby und Java nutzen.

composer require oxide/pdf-oxide

Alle Klassen liegen im Namespace PdfOxide\. Vorausgesetzt wird PHP 8.2+ mit aktiviertem ext-ffi. Composers Post-Install-Hook lädt die passende vorkompilierte native Bibliothek herunter; setzen Sie PDF_OXIDE_CDYLIB_PATH, um auf einen eigenen Build zu verweisen, oder PDF_OXIDE_SKIP_DOWNLOAD=1, um den Download zu überspringen.

Zur Rust-API siehe die Rust-API-Referenz. Zur Python-API siehe die Python-API-Referenz. Zur JavaScript-API siehe die Node.js-API-Referenz oder die WASM-API-Referenz.

Das Binding stellt 10 Klassen bereit:

Klasse Zweck
PdfOxide\PdfDocument PDFs öffnen, lesen, extrahieren und seitenweise durchlaufen
PdfOxide\Pdf PDFs erstellen (Markdown zu PDF, HTML zu PDF), Version, Modell-Prefetch
PdfOxide\PdfPage Leichtgewichtige Ansicht pro Seite
PdfOxide\MarkdownConverter Statische Konvertierung nach Markdown / HTML / Klartext
PdfOxide\AutoExtractor Extraktion mit typisiertem Grund und Seitenklassifizierung
PdfOxide\AutoExtractResult Schreibgeschütztes Ergebnis-Wertobjekt für AutoExtractor
PdfOxide\DocumentEditor Bearbeiten, Metadaten entfernen, destruktive Schwärzung, Speichern
PdfOxide\PdfSigner PAdES-Signierung B-B / B-T / B-LT / B-LTA
PdfOxide\PdfValidator Konformitätsprüfungen für PDF/A, PDF/UA und PDF/X
PdfOxide\PdfPolicy Einmalig setzbare, prozessweite Crypto-Governance-Policy

PdfDocument

Die zentrale Klasse zum Öffnen, Lesen und Extrahieren von PDF-Dateien.

use PdfOxide\PdfDocument;

Konstruktoren / Factory-Methoden

PdfDocument::open(string $path): self

Öffnet ein PDF über einen Dateipfad.

PdfDocument::openBytes(string $bytes): self

Öffnet ein PDF aus einem Byte-String im Arbeitsspeicher (z. B. von S3 heruntergeladen oder per HTTP empfangen).

PdfDocument::extractTextOnce(string $path): string

Öffnet eine Datei, extrahiert in einem einzigen Aufruf den gesamten Text und gibt das Handle wieder frei.

Dokumentinformationen

$doc->pageCount(): int

Gibt die Anzahl der Seiten im Dokument zurück.

$doc->version(): array

Gibt die PDF-Version als Integer-Array [major, minor] zurück.

$doc->hasStructureTree(): bool

Prüft, ob das Dokument ein Tagged PDF mit Strukturbaum ist.

$doc->hasFormFields(): bool

Prüft, ob das Dokument AcroForm-Formularfelder enthält.

$doc->hasSignatures(): bool

Prüft, ob das Dokument digitale Signaturen enthält.

$doc->getSourcePath(): ?string

Gibt den Quelldateipfad zurück, aus dem das Dokument geöffnet wurde, oder null bei aus Bytes geladenen Dokumenten.

Textextraktion

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

Extrahiert reinen Text aus einer einzelnen, nullbasiert indizierten Seite.

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

Extrahiert strukturierten Seiteninhalt (Spans, Zeichen und Abmessungen) als assoziatives Array.

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

Extrahiert Text aus einer Seite mit automatischer Auswahl zwischen nativem Text und OCR.

Konvertierung

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

Konvertiert eine einzelne Seite nach Markdown.

$doc->toMarkdownAll(): string

Konvertiert das gesamte Dokument nach Markdown.

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

Konvertiert eine einzelne Seite nach HTML.

Seitenzugriff

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

Gibt eine leichtgewichtige PdfPage-Ansicht für den angegebenen nullbasierten Index zurück.

$doc->pages(): array

Gibt alle Seiten als Array von PdfPage-Objekten zurück.

$doc->pagesIter(): \Generator

Durchläuft die Seiten verzögert (lazy) und liefert jeweils eine PdfPage aus.

Lebenszyklus

$doc->isOpen(): bool

Gibt zurück, ob das native Handle noch offen ist.

$doc->close(): void

Gibt das native Handle frei. Wird auch automatisch von __destruct() aufgerufen.

$doc->getHandle(): CData

Gibt das rohe FFI-Handle zurück (für fortgeschrittene Nutzung / Interop).

Pdf

Erstellt neue PDFs aus Quellinhalten und stellt Helfer auf Bibliotheksebene bereit.

use PdfOxide\Pdf;

Factory-Methoden

Pdf::fromMarkdown(string $markdown): self

Erstellt ein PDF aus Markdown-Inhalt.

Pdf::fromHtml(string $html): self

Erstellt ein PDF aus HTML-Inhalt.

Pdf::fromText(string $text): self

Erstellt ein PDF aus reinem Text.

Speichern

$pdf->save(): string

Rendert das PDF und gibt seine Bytes als String zurück.

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

Rendert das PDF und schreibt es an einen Dateipfad.

Bibliotheks-Helfer

Pdf::version(): string

Gibt die Versionszeichenkette der zugrunde liegenden nativen Bibliothek zurück.

Pdf::prefetchAvailable(): bool

Gibt zurück, ob das Prefetching von OCR-Modellen in diesem Build verfügbar ist.

Pdf::prefetchModels(array $languages): string

Lädt OCR-Modelle für die angegebenen Sprachcodes vorab; gibt eine Statuszeichenkette zurück.

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

Lebenszyklus

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

Das rohe native Handle prüfen, freigeben oder darauf zugreifen.

PdfPage

Eine leichtgewichtige Ansicht pro Seite, die von PdfDocument::page(), pages() oder pagesIter() zurückgegeben wird.

use PdfOxide\PdfPage;

Methoden

$page->parent(): PdfDocument

Gibt das zugehörige PdfDocument zurück.

$page->index(): int

Gibt den nullbasierten Seitenindex zurück.

$page->text(): string

Extrahiert reinen Text aus dieser Seite.

$page->textAuto(): string

Extrahiert Text aus dieser Seite mit automatischer Auswahl zwischen nativem Text und OCR.

$page->toMarkdown(): string

Konvertiert diese Seite nach Markdown.

$page->toHtml(): string

Konvertiert diese Seite nach HTML.

$page->__toString(): string

Gibt den reinen Text der Seite zurück, wenn das Objekt in einem String-Kontext verwendet wird.

MarkdownConverter

Statische Helfer, um ein offenes PdfDocument nach Markdown, HTML oder Klartext zu konvertieren.

use PdfOxide\MarkdownConverter;

Methoden

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

Konvertiert eine einzelne Seite nach Markdown.

MarkdownConverter::toMarkdownAll(PdfDocument $doc): string

Konvertiert das gesamte Dokument nach Markdown.

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

Konvertiert eine einzelne Seite nach HTML.

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

Konvertiert eine einzelne Seite nach Klartext.

AutoExtractor

Extraktion mit typisiertem Grund, Auswahl zwischen nativem Text und OCR sowie seitenweiser Dokumentklassifizierung.

use PdfOxide\AutoExtractor;

Konstanten

Konstante Wert Bedeutung
AutoExtractor::MODE_AUTO 0 Nativen Text oder OCR automatisch auswählen
AutoExtractor::MODE_TEXT_ONLY 1 Nur nativer Text, niemals OCR
AutoExtractor::MODE_FORCE_OCR 2 Immer OCR ausführen

Factory-Methoden

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

Erstellt einen Extractor über ein Dokument mit explizitem Modus.

AutoExtractor::fast(PdfDocument $doc): self

Erstellt einen auf Geschwindigkeit ausgelegten Extractor.

AutoExtractor::balanced(PdfDocument $doc): self

Erstellt einen Extractor, der Geschwindigkeit und Genauigkeit ausbalanciert.

AutoExtractor::highFidelity(PdfDocument $doc): self

Erstellt einen auf maximale Genauigkeit ausgelegten Extractor.

Extraktion

$ex->extractText(): string

Extrahiert Text aus dem gesamten Dokument.

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

Extrahiert Text aus einer einzelnen Seite.

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

Extrahiert eine einzelne Seite und gibt ein typisiertes AutoExtractResult mit Grund und Konfidenz zurück.

$ex->extractAutoDocument(): AutoExtractResult

Extrahiert das gesamte Dokument und gibt ein typisiertes AutoExtractResult zurück.

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

Extrahiert eine einzelne Seite als JSON-String.

$ex->extractDocumentJson(): string

Extrahiert das gesamte Dokument als JSON-String.

Klassifizierung

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

Klassifiziert eine einzelne Seite (z. B. text_layer, scanned, image_text, mixed, empty).

$ex->classifyDocumentKinds(): array

Klassifiziert jede Seite und gibt ein Array von Seitenart-Zeichenketten zurück.

Zugriffsmethoden

$ex->document(): PdfDocument

Gibt das zugrunde liegende PdfDocument zurück.

$ex->mode(): int

Gibt die aktive Extraktionsmodus-Konstante zurück.

AutoExtractResult

Schreibgeschütztes Wertobjekt, das von AutoExtractor::extractAutoPage() und extractAutoDocument() zurückgegeben wird.

use PdfOxide\AutoExtractResult;

Eigenschaften

Eigenschaft Typ Beschreibung
text string Extrahierter Text
reason string Eine der REASON_*-Konstanten
confidence float Konfidenz im Bereich [0.0, 1.0]
ocrUsed bool Ob für dieses Ergebnis OCR ausgeführt wurde
regions array Detaillierte Angaben pro Region
pagesNeedingOcr array Seitenindizes, die noch OCR benötigen

Konstanten

Reason-Konstante Wert
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-Konstante Wert
KIND_TEXT_LAYER text_layer
KIND_SCANNED scanned
KIND_IMAGE_TEXT image_text
KIND_MIXED mixed
KIND_EMPTY empty

Methoden

$result->isOk(): bool

Gibt zurück, ob die Extraktion ohne Qualitätseinbußen erfolgreich war.

$result->isOcrFallback(): bool

Gibt zurück, ob ein Fallback-Pfad wegen nicht verfügbarem OCR oder niedriger Konfidenz aktiviert wurde.

DocumentEditor

Bearbeitet ein PDF direkt: Metadaten entfernen, destruktive Schwärzungen anwenden, Producer setzen und speichern.

use PdfOxide\DocumentEditor;

Konstruktor

DocumentEditor::open(string $path): self

Öffnet ein PDF zur Bearbeitung.

Schwärzung

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

Reiht einen rechteckigen Schwärzungsbereich ein (Koordinaten in PDF-Punkten). Fluent — gibt $this zurück.

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

Gibt die Anzahl der ausstehenden Schwärzungen auf einer Seite zurück.

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

Wendet alle eingereihten Schwärzungen dauerhaft an (fällt im Fehlerfall sicher aus). Gibt die Anzahl der angewendeten Schwärzungen zurück; entfernt optional die Metadaten.

Metadaten

$editor->scrubMetadata(): self

Entfernt die Dokument-Metadaten. Fluent — gibt $this zurück.

$editor->getProducer(): string

Gibt die Producer-Zeichenkette des Dokuments zurück.

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

Setzt die Producer-Zeichenkette des Dokuments. Fluent — gibt $this zurück.

Dokumentinformationen

$editor->version(): array

Gibt die PDF-Version als Array [major, minor] zurück.

$editor->pageCount(): int

Gibt die Anzahl der Seiten zurück.

$editor->isModified(): bool

Gibt zurück, ob das Dokument ungespeicherte Änderungen enthält.

$editor->sourcePath(): string

Gibt den Quelldateipfad zurück.

Speichern

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

Schreibt das bearbeitete PDF an einen Dateipfad.

$editor->save(): string

Rendert das bearbeitete PDF und gibt seine Bytes als String zurück.

Lebenszyklus

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

Das rohe native Handle prüfen, freigeben oder darauf zugreifen.

PdfSigner

Digitale PAdES-Signierung mit den Konformitätsstufen B-B, B-T, B-LT und B-LTA.

use PdfOxide\PdfSigner;

Konstanten

Konstante Wert Stufe
PdfSigner::LEVEL_B_B 0 PAdES B-B (Baseline)
PdfSigner::LEVEL_B_T 1 PAdES B-T (mit Zeitstempel)
PdfSigner::LEVEL_B_LT 2 PAdES B-LT (langfristig)
PdfSigner::LEVEL_B_LTA 3 PAdES B-LTA (langfristig mit Archiv-Zeitstempel)

Konstruktor / Factory

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

Erstellt einen Signer aus einem PKCS#12-Keystore (.p12 / .pfx).

Signierung

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

Signiert PDF-Bytes und gibt die signierten PDF-Bytes zurück. Stufen oberhalb von B-B erfordern eine tsaUrl. $level akzeptiert die LEVEL_B_*-Ordinalzahl oder ein Kurzkürzel ('b', 't', 'lt', 'lta').

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

Statischer Komfort: signiert, ohne eine verwaltete Signer-Instanz zu konstruieren. Der Aufrufer behält das Eigentum an $certificateHandle.

Verifizierung

PdfSigner::verify(string $pdfBytes): bool

Gibt zurück, ob die PDF-Bytes ein Signatur-Dictionary und einen Byte-Range tragen.

Lebenszyklus

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

Die Signierungs-Anmeldedaten prüfen oder freigeben.

PdfValidator

Statische Konformitätsprüfungen für PDF/A, PDF/UA und PDF/X gegen ein offenes PdfDocument.

use PdfOxide\PdfValidator;

Konstanten

PDF/A-Konstante Wert PDF/UA-Konstante Wert
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

Methoden

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

Gibt zurück, ob das Dokument der angegebenen PDF/A-Stufe entspricht.

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

Gibt zurück, ob das Dokument der angegebenen PDF/UA-Stufe entspricht.

PdfValidator::isPdfX(PdfDocument $doc): bool

Nicht implementiert — pdf_oxide stellt derzeit keinen öffentlichen PDF/X-Validator über die C-ABI bereit. Der Aufruf löst immer BadMethodCallException aus.

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

Führt eine vollständige PDF/A-Validierung durch und gibt ein strukturiertes Ergebnis-Array zurück (Konformitäts-Flag plus etwaige Verstöße).

PdfPolicy

Einmalig setzbare, prozessweite Crypto-Governance-Policy. Muss konfiguriert werden, bevor ein PDF geöffnet wird.

use PdfOxide\PdfPolicy;

Konstanten

Konstante Wert
PdfPolicy::COMPAT compat
PdfPolicy::STRICT strict
PdfPolicy::FIPS_STRICT fips_strict

Methoden

PdfPolicy::current(): string

Gibt den aktiven Policy-Modus zurück.

PdfPolicy::set(string $mode): void

Setzt die prozessweite Policy (eine der Policy-Konstanten). Pro Prozess nur einmal setzbar.

PdfPolicy::fipsAvailable(): bool

Gibt zurück, ob ein FIPS-validierter Crypto-Provider verfügbar ist.

PdfPolicy::activeProvider(): string

Gibt den Namen des aktiven Crypto-Providers zurück.

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

Komfort-Zugriffsmethoden, die die jeweils zugehörige Policy-Modus-Zeichenkette zurückgeben.

Fehlerbehandlung

Alle PDF-spezifischen Fehler erben von PdfOxide\Exceptions\PdfException. Spezialisierte Unterklassen erlauben es, engere Fehlerkategorien gezielt abzufangen.

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()}");
}
Exception (unter PdfOxide\Exceptions\) Ursache
PdfException Basisklasse für alle PDF-Fehler
ParseException Fehlerhaftes oder nicht parsbares PDF
IoException Fehler beim Lesen/Schreiben einer Datei
NotFoundException Fehlende Datei, Seite oder fehlendes Objekt
EncryptionException Verschlüsselungs- / Passwortfehler
ValidationException Ungültiges Argument oder ungültige Eingabe
SignatureException Fehler beim Signieren oder bei der Signaturverifizierung
RedactionException Schwärzungsfehler
SearchException Suchfehler
OptimizationException Optimierungsfehler
ComplianceException PDF/A- oder PDF/UA-Konformitätsfehler
AccessibilityException Barrierefreiheits- / Tagging-Fehler
UnsupportedException Nicht unterstützte Funktion oder Operation
InvalidStateException Operation auf einem geschlossenen oder ungültigen Handle
InternalError Interner nativer Fehler

Vollständiges Beispiel

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 bietet native Bindings für jedes wichtige Ökosystem: Rust, Python, Node.js, WASM, C#, Golang, Java, Ruby, C++, Swift, Kotlin, Dart, R, Julia, Zig, Scala, Clojure, Objective-C und Elixir.

Nächste Schritte