Skip to content
PDF Oxide

Primeiros passos com a PDF Oxide (PHP)

A PDF Oxide é a biblioteca PDF para PHP mais rápida em extração de texto — média de 0,8 ms e 100% de taxa de aprovação em 3.830 PDFs. Uma única biblioteca para extrair, converter e criar PDFs, construída sobre o mesmo núcleo em Rust usado pelos bindings de Python, Node, Go, C#, Ruby e Java.

Instalação

composer require oxide/pdf-oxide

O hook de pós-instalação do Composer baixa a biblioteca nativa pré-compilada correspondente à sua plataforma para vendor/oxide/pdf-oxide/lib/ (linux-x86_64, linux-aarch64, darwin-x86_64, darwin-arm64, windows-x64).

Requisitos: PHP 8.2+ (8.2, 8.3, 8.4, 8.5) com ext-ffi habilitado. Confirme com php -m | grep -i ffi. Alguns provedores de hospedagem gerenciada desabilitam o ext-ffi; nesse caso, use uma imagem Docker como php:8.3-cli.

Abrindo um PDF

Use PdfDocument::open() para carregar um arquivo e inspecionar seus metadados.

use PdfOxide\PdfDocument;

$doc = PdfDocument::open('research-paper.pdf');
echo $doc->pageCount(), " pages\n";

$version = $doc->version();   // ['major' => int, 'minor' => int]
printf("PDF version: %d.%d\n", $version['major'], $version['minor']);

$doc->close();   // ou deixe o __destruct() cuidar disso

Extração de texto

Página única

Extraia texto puro de qualquer página pelo seu índice baseado em zero.

use PdfOxide\PdfDocument;

$doc = PdfDocument::open('report.pdf');
echo $doc->extractText(0);
$doc->close();

Todas as páginas

use PdfOxide\PdfDocument;

$doc = PdfDocument::open('book.pdf');
for ($i = 0; $i < $doc->pageCount(); $i++) {
    echo "--- Page " . ($i + 1) . " ---\n";
    echo $doc->extractText($i), "\n";
}
$doc->close();

Extração em uma única chamada

extractTextOnce() é um helper estático que abre o arquivo, extrai a página 0 e fecha tudo em uma só chamada.

use PdfOxide\PdfDocument;

echo PdfDocument::extractTextOnce('report.pdf');

Extração com roteamento automático

extractTextAuto() retorna o texto nativo quando ele existe e recorre, de forma elegante, a qualquer texto recuperável — nunca lança exceção no caminho de fallback.

use PdfOxide\PdfDocument;

$doc = PdfDocument::open('mixed.pdf');
echo $doc->extractTextAuto(0);
$doc->close();

API de páginas

pages() retorna um array de visões PdfPage, e pagesIter() as produz de forma preguiçosa junto com o índice. Cada página delega a extração de volta ao documento.

use PdfOxide\PdfDocument;

$doc = PdfDocument::open('paper.pdf');

foreach ($doc->pagesIter() as $index => $page) {
    echo "Page {$index}:\n";
    echo $page->text(), "\n";
}

// Ou pegue uma página específica diretamente:
$page = $doc->page(0);
echo $page->toMarkdown();

$doc->close();

Métodos de PdfPage: index(), parent(), text(), textAuto(), toMarkdown(), toHtml().

Conversão para Markdown e HTML

Converta uma única página ou o documento inteiro para Markdown, ou renderize uma página em HTML.

use PdfOxide\PdfDocument;

$doc = PdfDocument::open('paper.pdf');

echo $doc->toMarkdown(0);     // uma página (padrão: página 0)
echo $doc->toMarkdownAll();   // documento inteiro
echo $doc->toHtml(0);         // uma página em HTML

$doc->close();

O MarkdownConverter estático oferece as mesmas conversões sem precisar passar o índice da página no ponto de chamada do documento.

use PdfOxide\PdfDocument;
use PdfOxide\MarkdownConverter;

$doc = PdfDocument::open('paper.pdf');

echo MarkdownConverter::toMarkdown($doc, 0);
echo MarkdownConverter::toMarkdownAll($doc);
echo MarkdownConverter::toHtml($doc, 0);
echo MarkdownConverter::toPlainText($doc, 0);

$doc->close();

Extração estruturada

extractStructured() retorna uma visão da página com reconhecimento de layout, na forma de um array associativo — regiões com seu tipo, texto, bounding box e índice de coluna.

use PdfOxide\PdfDocument;

$doc = PdfDocument::open('paper.pdf');
$structured = $doc->extractStructured(0);

printf("Page %d: %.0f x %.0f\n",
    $structured['page_index'],
    $structured['page_width'],
    $structured['page_height']);

foreach ($structured['regions'] as $region) {
    echo "[{$region['kind']}] {$region['text']}\n";
}

$doc->close();

Abrindo a partir de bytes

Abra um PDF a partir de uma string em memória — útil ao buscar dados do S3, de HTTP ou de um banco de dados.

use PdfOxide\PdfDocument;

$bytes = file_get_contents('report.pdf');
$doc = PdfDocument::openBytes($bytes);
echo $doc->extractText(0);
$doc->close();

Inspecionando recursos do documento

Examine um documento antes de processá-lo.

use PdfOxide\PdfDocument;

$doc = PdfDocument::open('form.pdf');

var_dump($doc->hasStructureTree());   // PDF marcado (tagged)?
var_dump($doc->hasFormFields());      // campos AcroForm?
var_dump($doc->hasSignatures());      // assinaturas digitais?

$doc->close();

Criação de PDF

A classe Pdf oferece métodos de fábrica para gerar PDFs a partir de Markdown, HTML ou texto puro.

use PdfOxide\Pdf;

$pdf = Pdf::fromMarkdown("# Invoice\n\n**Total:** \$42.00\n");
$pdf->saveTo('invoice.pdf');           // grava em um caminho
$pdf->close();

$pdf = Pdf::fromHtml('<h1>Report</h1><p>Quarterly figures.</p>');
$bytes = $pdf->save();                 // ou obtenha os bytes brutos
file_put_contents('report.pdf', $bytes);
$pdf->close();

$pdf = Pdf::fromText("Plain text document.\n\nSecond paragraph.");
$pdf->saveTo('notes.pdf');
$pdf->close();

Próximos passos