Skip to content
PDF Oxide

Primeros pasos con PDF Oxide (PHP)

PDF Oxide es la librería PDF para PHP más rápida en extracción de texto: 0,8 ms de media y 100 % de aciertos sobre 3.830 PDF. Una sola librería para extraer, convertir y crear PDF, construida sobre el mismo núcleo en Rust que utilizan los bindings de Python, Node, Go, C#, Ruby y Java.

Instalación

composer require oxide/pdf-oxide

El hook post-instalación de Composer descarga la librería nativa precompilada correspondiente a tu plataforma en 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) con ext-ffi habilitado. Compruébalo con php -m | grep -i ffi. Algunos hostings gestionados desactivan ext-ffi; en ese caso, usa una imagen de Docker como php:8.3-cli.

Abrir un PDF

Usa PdfDocument::open() para cargar un archivo e inspeccionar sus metadatos.

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();   // o confía en __destruct()

Extracción de texto

Una sola página

Extrae texto plano de cualquier página por su índice de base cero.

use PdfOxide\PdfDocument;

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

Todas las 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();

Extracción en un solo paso

extractTextOnce() es un método auxiliar estático que abre el archivo, extrae la página 0 y lo cierra en una sola llamada.

use PdfOxide\PdfDocument;

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

Extracción con enrutado automático

extractTextAuto() devuelve el texto nativo cuando existe y recurre de forma transparente a cualquier texto que se pueda recuperar; nunca lanza una excepción en la ruta de respaldo.

use PdfOxide\PdfDocument;

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

API de páginas

pages() devuelve un array de vistas PdfPage, y pagesIter() las genera de forma perezosa junto con su índice. Cada página delega la extracción de vuelta al documento.

use PdfOxide\PdfDocument;

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

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

// O toma una sola página directamente:
$page = $doc->page(0);
echo $page->toMarkdown();

$doc->close();

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

Conversión a Markdown y HTML

Convierte una sola página o el documento entero a Markdown, o renderiza una página a HTML.

use PdfOxide\PdfDocument;

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

echo $doc->toMarkdown(0);     // una página (por defecto, la página 0)
echo $doc->toMarkdownAll();   // documento completo
echo $doc->toHtml(0);         // una página como HTML

$doc->close();

El MarkdownConverter estático expone las mismas conversiones sin necesidad de fijar un índice de página en la llamada del 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();

Extracción estructurada

extractStructured() devuelve una vista de la página consciente del diseño en forma de array asociativo: regiones con su tipo, texto, caja delimitadora e índice de columna.

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

Abrir desde bytes

Abre un PDF a partir de una cadena en memoria; resulta útil cuando lo obtienes de S3, HTTP o una base de datos.

use PdfOxide\PdfDocument;

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

Inspeccionar las características del documento

Examina un documento antes de procesarlo.

use PdfOxide\PdfDocument;

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

var_dump($doc->hasStructureTree());   // ¿PDF etiquetado?
var_dump($doc->hasFormFields());      // ¿campos de AcroForm?
var_dump($doc->hasSignatures());      // ¿firmas digitales?

$doc->close();

Creación de PDF

La clase Pdf proporciona métodos de fábrica para construir PDF a partir de Markdown, HTML o texto plano.

use PdfOxide\Pdf;

$pdf = Pdf::fromMarkdown("# Invoice\n\n**Total:** \$42.00\n");
$pdf->saveTo('invoice.pdf');           // escribe en una ruta
$pdf->close();

$pdf = Pdf::fromHtml('<h1>Report</h1><p>Quarterly figures.</p>');
$bytes = $pdf->save();                 // o obtén los bytes en crudo
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 pasos