Referência da API PHP

A PDF Oxide oferece um binding em PHP puro, construído sobre a extensão FFI nativa do PHP. O código PHP é uma camada fina sobre a mesma cdylib libpdf_oxide usada pelos bindings de Python, Node, Go, C#, Ruby e Java.

composer require oxide/pdf-oxide

Todas as classes ficam sob o namespace PdfOxide\. É necessário PHP 8.2+ com ext-ffi habilitado. O hook de pós-instalação do Composer baixa a biblioteca nativa pré-compilada correspondente; defina PDF_OXIDE_CDYLIB_PATH para apontar para uma build personalizada, ou PDF_OXIDE_SKIP_DOWNLOAD=1 para pular o download.

Para a API Rust, consulte a Referência da API Rust. Para a API Python, consulte a Referência da API Python. Para a API JavaScript, consulte a Referência da API JavaScript (Node.js) ou a Referência da API JavaScript (WASM).

O binding expõe 10 classes:

Classe	Finalidade
PdfOxide\PdfDocument	Abrir, ler, extrair e iterar páginas de PDFs
PdfOxide\Pdf	Criar PDFs (Markdown para PDF, HTML para PDF), versão, prefetch de modelos
PdfOxide\PdfPage	Visão leve por página
PdfOxide\MarkdownConverter	Conversão estática para Markdown / HTML / texto puro
PdfOxide\AutoExtractor	Extração com motivo tipado e classificação de páginas
PdfOxide\AutoExtractResult	Objeto de valor somente leitura, resultado de AutoExtractor
PdfOxide\DocumentEditor	Editar, limpar metadados, redação destrutiva, salvar
PdfOxide\PdfSigner	Assinatura PAdES B-B / B-T / B-LT / B-LTA
PdfOxide\PdfValidator	Verificações de conformidade PDF/A, PDF/UA e PDF/X
PdfOxide\PdfPolicy	Política de governança criptográfica global do processo, definida uma única vez

---

PdfDocument

A classe principal para abrir, ler e extrair arquivos PDF.

use PdfOxide\PdfDocument;

Construtores / Métodos de fábrica

PdfDocument::open(string $path): self

Abre um PDF a partir de um caminho de arquivo.

PdfDocument::openBytes(string $bytes): self

Abre um PDF a partir de uma string de bytes em memória (por exemplo, baixada do S3 ou recebida via HTTP).

PdfDocument::extractTextOnce(string $path): string

Abre um arquivo, extrai todo o texto em uma única chamada e libera o handle.

Informações do documento

$doc->pageCount(): int

Retorna o número de páginas do documento.

$doc->version(): array

Retorna a versão do PDF como um array de inteiros [major, minor].

$doc->hasStructureTree(): bool

Verifica se o documento é um PDF marcado (Tagged PDF) com árvore de estrutura.

$doc->hasFormFields(): bool

Verifica se o documento contém campos de formulário AcroForm.

$doc->hasSignatures(): bool

Verifica se o documento contém assinaturas digitais.

$doc->getSourcePath(): ?string

Retorna o caminho do arquivo de origem a partir do qual o documento foi aberto, ou null para documentos carregados a partir de bytes.

Extração de texto

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

Extrai texto puro de uma única página com índice baseado em zero.

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

Extrai o conteúdo estruturado da página (spans, caracteres e dimensões) como um array associativo.

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

Extrai texto de uma página usando seleção automática entre texto nativo e OCR.

Conversão

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

Converte uma única página para Markdown.

$doc->toMarkdownAll(): string

Converte o documento inteiro para Markdown.

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

Converte uma única página para HTML.

Acesso a páginas

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

Retorna uma visão leve PdfPage para o índice baseado em zero informado.

$doc->pages(): array

Retorna todas as páginas como um array de objetos PdfPage.

$doc->pagesIter(): \Generator

Itera de forma preguiçosa sobre as páginas, produzindo uma PdfPage por vez.

Ciclo de vida

$doc->isOpen(): bool

Retorna se o handle nativo ainda está aberto.

$doc->close(): void

Libera o handle nativo. Também é chamado automaticamente por __destruct().

$doc->getHandle(): CData

Retorna o handle FFI bruto (uso avançado / interoperabilidade).

---

Pdf

Cria novos PDFs a partir de conteúdo de origem e dá acesso a helpers de nível de biblioteca.

use PdfOxide\Pdf;

Métodos de fábrica

Pdf::fromMarkdown(string $markdown): self

Cria um PDF a partir de conteúdo Markdown.

Pdf::fromHtml(string $html): self

Cria um PDF a partir de conteúdo HTML.

Pdf::fromText(string $text): self

Cria um PDF a partir de texto puro.

Salvando

$pdf->save(): string

Renderiza o PDF e retorna seus bytes como uma string.

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

Renderiza o PDF e o grava em um caminho de arquivo.

Helpers de biblioteca

Pdf::version(): string

Retorna a string de versão da biblioteca nativa subjacente.

Pdf::prefetchAvailable(): bool

Retorna se o prefetch de modelos de OCR está disponível nesta build.

Pdf::prefetchModels(array $languages): string

Faz o prefetch dos modelos de OCR para os códigos de idioma informados; retorna uma string de status.

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

Ciclo de vida

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

Inspeciona, libera ou acessa o handle nativo bruto.

---

PdfPage

Uma visão leve por página retornada por PdfDocument::page(), pages() ou pagesIter().

use PdfOxide\PdfPage;

Métodos

$page->parent(): PdfDocument

Retorna o PdfDocument proprietário.

$page->index(): int

Retorna o índice da página baseado em zero.

$page->text(): string

Extrai texto puro desta página.

$page->textAuto(): string

Extrai texto desta página usando seleção automática entre texto nativo e OCR.

$page->toMarkdown(): string

Converte esta página para Markdown.

$page->toHtml(): string

Converte esta página para HTML.

$page->__toString(): string

Retorna o texto puro da página quando o objeto é usado em contexto de string.

---

MarkdownConverter

Helpers estáticos para converter um PdfDocument aberto em Markdown, HTML ou texto puro.

use PdfOxide\MarkdownConverter;

Métodos

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

Converte uma única página para Markdown.

MarkdownConverter::toMarkdownAll(PdfDocument $doc): string

Converte o documento inteiro para Markdown.

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

Converte uma única página para HTML.

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

Converte uma única página para texto puro.

---

AutoExtractor

Extração com motivo tipado, seleção entre texto nativo e OCR e classificação do documento por página.

use PdfOxide\AutoExtractor;

Constantes

Constante	Valor	Significado
AutoExtractor::MODE_AUTO	0	Seleciona automaticamente texto nativo ou OCR
AutoExtractor::MODE_TEXT_ONLY	1	Apenas texto nativo, nunca OCR
AutoExtractor::MODE_FORCE_OCR	2	Sempre executa OCR

Métodos de fábrica

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

Cria um extrator sobre um documento com um modo explícito.

AutoExtractor::fast(PdfDocument $doc): self

Cria um extrator otimizado para velocidade.

AutoExtractor::balanced(PdfDocument $doc): self

Cria um extrator que equilibra velocidade e fidelidade.

AutoExtractor::highFidelity(PdfDocument $doc): self

Cria um extrator otimizado para máxima fidelidade.

Extração

$ex->extractText(): string

Extrai texto do documento inteiro.

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

Extrai texto de uma única página.

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

Extrai uma única página, retornando um AutoExtractResult tipado com motivo e confiança.

$ex->extractAutoDocument(): AutoExtractResult

Extrai o documento inteiro, retornando um AutoExtractResult tipado.

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

Extrai uma única página como uma string JSON.

$ex->extractDocumentJson(): string

Extrai o documento inteiro como uma string JSON.

Classificação

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

Classifica uma única página (por exemplo, text_layer, scanned, image_text, mixed, empty).

$ex->classifyDocumentKinds(): array

Classifica todas as páginas, retornando um array de strings de tipo de página.

Acessores

$ex->document(): PdfDocument

Retorna o PdfDocument subjacente.

$ex->mode(): int

Retorna a constante do modo de extração ativo.

---

AutoExtractResult

Objeto de valor somente leitura retornado por AutoExtractor::extractAutoPage() e extractAutoDocument().

use PdfOxide\AutoExtractResult;

Propriedades

Propriedade	Tipo	Descrição
text	string	Texto extraído
reason	string	Uma das constantes REASON_*
confidence	float	Confiança em [0.0, 1.0]
ocrUsed	bool	Se o OCR foi executado para este resultado
regions	array	Detalhamento rico por região
pagesNeedingOcr	array	Índices de páginas que ainda precisam de OCR

Constantes

Constante de motivo	Valor
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

Constante de tipo	Valor
KIND_TEXT_LAYER	text_layer
KIND_SCANNED	scanned
KIND_IMAGE_TEXT	image_text
KIND_MIXED	mixed
KIND_EMPTY	empty

Métodos

$result->isOk(): bool

Retorna se a extração foi bem-sucedida sem degradação.

$result->isOcrFallback(): bool

Retorna se um caminho de fallback de OCR indisponível ou de baixa confiança foi acionado.

---

DocumentEditor

Edita um PDF in place: limpa metadados, aplica redações destrutivas, define o producer e salva.

use PdfOxide\DocumentEditor;

Construtor

DocumentEditor::open(string $path): self

Abre um PDF para edição.

Redação

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

Enfileira uma região retangular de redação (coordenadas em pontos PDF). Fluente — retorna $this.

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

Retorna o número de redações pendentes em uma página.

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

Aplica permanentemente todas as redações enfileiradas (falha fechando em caso de erro). Retorna o número aplicado; opcionalmente limpa os metadados.

Metadados

$editor->scrubMetadata(): self

Remove os metadados do documento. Fluente — retorna $this.

$editor->getProducer(): string

Retorna a string Producer do documento.

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

Define a string Producer do documento. Fluente — retorna $this.

Informações do documento

$editor->version(): array

Retorna a versão do PDF como um array [major, minor].

$editor->pageCount(): int

Retorna o número de páginas.

$editor->isModified(): bool

Retorna se o documento tem modificações não salvas.

$editor->sourcePath(): string

Retorna o caminho do arquivo de origem.

Salvando

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

Grava o PDF editado em um caminho de arquivo.

$editor->save(): string

Renderiza o PDF editado e retorna seus bytes como uma string.

Ciclo de vida

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

Inspeciona, libera ou acessa o handle nativo bruto.

---

PdfSigner

Assinatura digital PAdES com os níveis de conformidade B-B, B-T, B-LT e B-LTA.

use PdfOxide\PdfSigner;

Constantes

Constante	Valor	Nível
PdfSigner::LEVEL_B_B	0	PAdES B-B (baseline)
PdfSigner::LEVEL_B_T	1	PAdES B-T (com timestamp)
PdfSigner::LEVEL_B_LT	2	PAdES B-LT (longo prazo)
PdfSigner::LEVEL_B_LTA	3	PAdES B-LTA (longo prazo com timestamp de arquivamento)

Construtor / Fábrica

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

Cria um signer a partir de um keystore PKCS#12 (.p12 / .pfx).

Assinatura

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

Assina os bytes do PDF e retorna os bytes do PDF assinado. Níveis acima de B-B exigem uma tsaUrl. $level aceita o ordinal LEVEL_B_* ou uma tag curta ('b', 't', 'lt', 'lta').

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

Conveniência estática: assina sem construir uma instância de signer gerenciada. O chamador mantém a propriedade de $certificateHandle.

Verificação

PdfSigner::verify(string $pdfBytes): bool

Retorna se os bytes do PDF carregam um dicionário de assinatura e um byte range.

Ciclo de vida

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

Inspeciona ou libera as credenciais de assinatura.

---

PdfValidator

Verificações estáticas de conformidade PDF/A, PDF/UA e PDF/X contra um PdfDocument aberto.

use PdfOxide\PdfValidator;

Constantes

Constante PDF/A	Valor		Constante PDF/UA	Valor
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

Métodos

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

Retorna se o documento está em conformidade com o nível PDF/A informado.

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

Retorna se o documento está em conformidade com o nível PDF/UA informado.

PdfValidator::isPdfX(PdfDocument $doc): bool

Não implementado — o pdf_oxide atualmente não expõe nenhum validador de PDF/X público na ABI C. Chamar este método sempre lança BadMethodCallException.

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

Executa uma validação PDF/A completa e retorna um array de resultado estruturado (flag de conformidade mais quaisquer violações).

---

PdfPolicy

Política de governança criptográfica global do processo, definida uma única vez. Deve ser configurada antes de abrir qualquer PDF.

use PdfOxide\PdfPolicy;

Constantes

Constante	Valor
PdfPolicy::COMPAT	compat
PdfPolicy::STRICT	strict
PdfPolicy::FIPS_STRICT	fips_strict

Métodos

PdfPolicy::current(): string

Retorna o modo de política ativo.

PdfPolicy::set(string $mode): void

Define a política global do processo (uma das constantes de política). Definida uma única vez por processo.

PdfPolicy::fipsAvailable(): bool

Retorna se um provedor de criptografia validado por FIPS está disponível.

PdfPolicy::activeProvider(): string

Retorna o nome do provedor de criptografia ativo.

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

Acessores de conveniência que retornam a string de modo de política correspondente.

---

Tratamento de erros

Todos os erros específicos de PDF estendem PdfOxide\Exceptions\PdfException. Subclasses especializadas permitem capturar categorias de falha mais restritas.

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()}");
}

Exceção (sob PdfOxide\Exceptions\)	Causa
PdfException	Classe base para todos os erros de PDF
ParseException	PDF malformado ou não analisável
IoException	Falha de leitura/gravação de arquivo
NotFoundException	Arquivo, página ou objeto ausente
EncryptionException	Falha de criptografia / senha
ValidationException	Argumento ou entrada inválida
SignatureException	Falha de assinatura ou de verificação de assinatura
RedactionException	Falha de redação
SearchException	Falha de busca
OptimizationException	Falha de otimização
ComplianceException	Falha de conformidade PDF/A ou PDF/UA
AccessibilityException	Falha de acessibilidade / marcação (tagging)
UnsupportedException	Recurso ou operação não suportada
InvalidStateException	Operação sobre um handle fechado ou inválido
InternalError	Erro nativo interno

---

Exemplo completo

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

O PDF Oxide oferece bindings nativos para todos os principais ecossistemas: Rust, Python, Node.js, WASM, C#, Golang, Java, Ruby, C++, Swift, Kotlin, Dart, R, Julia, Zig, Scala, Clojure, Objective-C e Elixir.

Próximos passos

• Tipos e Enums — todos os tipos e enums compartilhados
• Referência da API Page — iteração consistente por página entre os bindings
• Primeiros Passos com PHP — tutorial