Skip to content
PDF Oxide

Referencia de la API de PHP

PDF Oxide incluye un binding en PHP puro construido sobre la extensión FFI integrada de PHP. El código PHP es una capa fina sobre la misma libpdf_oxide cdylib que utilizan los bindings de Python, Node, Go, C#, Ruby y Java.

composer require oxide/pdf-oxide

Todas las clases residen bajo el namespace PdfOxide\. Se requiere PHP 8.2+ con ext-ffi habilitado. El hook post-instalación de Composer descarga la librería nativa precompilada correspondiente; define PDF_OXIDE_CDYLIB_PATH para apuntar a una compilación propia, o PDF_OXIDE_SKIP_DOWNLOAD=1 para omitir la descarga.

Para la API de Rust, consulta la Referencia de la API de Rust. Para la API de Python, consulta la Referencia de la API de Python. Para la API de JavaScript, consulta la Referencia de la API de Node.js o la Referencia de la API WASM.

El binding expone 10 clases:

Clase Propósito
PdfOxide\PdfDocument Abrir, leer, extraer e iterar páginas de PDF
PdfOxide\Pdf Crear PDF (Markdown a PDF, HTML a PDF), versión, prefetch de modelos
PdfOxide\PdfPage Vista ligera por página
PdfOxide\MarkdownConverter Conversión estática a Markdown / HTML / texto plano
PdfOxide\AutoExtractor Extracción con motivo tipado y clasificación de páginas
PdfOxide\AutoExtractResult Objeto de valor de solo lectura para el resultado de AutoExtractor
PdfOxide\DocumentEditor Editar, depurar metadatos, redacción destructiva y guardar
PdfOxide\PdfSigner Firma PAdES B-B / B-T / B-LT / B-LTA
PdfOxide\PdfValidator Comprobaciones de conformidad PDF/A, PDF/UA y PDF/X
PdfOxide\PdfPolicy Política de gobernanza criptográfica global del proceso, establecida una sola vez

PdfDocument

La clase principal para abrir, leer y extraer archivos PDF.

use PdfOxide\PdfDocument;

Constructores / Métodos de fábrica

PdfDocument::open(string $path): self

Abre un PDF a partir de una ruta de archivo.

PdfDocument::openBytes(string $bytes): self

Abre un PDF a partir de una cadena de bytes en memoria (por ejemplo, descargada de S3 o recibida por HTTP).

PdfDocument::extractTextOnce(string $path): string

Abre un archivo, extrae todo el texto en una sola llamada y libera el handle.

Información del documento

$doc->pageCount(): int

Devuelve el número de páginas del documento.

$doc->version(): array

Devuelve la versión del PDF como un array de enteros [major, minor].

$doc->hasStructureTree(): bool

Comprueba si el documento es un PDF etiquetado con árbol de estructura.

$doc->hasFormFields(): bool

Comprueba si el documento contiene campos de formulario AcroForm.

$doc->hasSignatures(): bool

Comprueba si el documento contiene firmas digitales.

$doc->getSourcePath(): ?string

Devuelve la ruta del archivo de origen desde el que se abrió el documento, o null para documentos cargados desde bytes.

Extracción de texto

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

Extrae texto plano de una sola página con índice de base cero.

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

Extrae el contenido estructurado de la página (spans, caracteres y dimensiones) como array asociativo.

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

Extrae texto de una página con selección automática entre texto nativo y OCR.

Conversión

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

Convierte una sola página a Markdown.

$doc->toMarkdownAll(): string

Convierte el documento completo a Markdown.

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

Convierte una sola página a HTML.

Acceso a páginas

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

Devuelve una vista ligera PdfPage para el índice de base cero indicado.

$doc->pages(): array

Devuelve todas las páginas como un array de objetos PdfPage.

$doc->pagesIter(): \Generator

Itera de forma perezosa sobre las páginas, generando un PdfPage cada vez.

Ciclo de vida

$doc->isOpen(): bool

Devuelve si el handle nativo sigue abierto.

$doc->close(): void

Libera el handle nativo. También se invoca automáticamente desde __destruct().

$doc->getHandle(): CData

Devuelve el handle FFI en crudo (uso avanzado / interoperabilidad).

Pdf

Crea nuevos PDF a partir de contenido de origen y accede a utilidades a nivel de librería.

use PdfOxide\Pdf;

Métodos de fábrica

Pdf::fromMarkdown(string $markdown): self

Crea un PDF a partir de contenido Markdown.

Pdf::fromHtml(string $html): self

Crea un PDF a partir de contenido HTML.

Pdf::fromText(string $text): self

Crea un PDF a partir de texto plano.

Guardado

$pdf->save(): string

Renderiza el PDF y devuelve sus bytes como cadena.

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

Renderiza el PDF y lo escribe en una ruta de archivo.

Utilidades de librería

Pdf::version(): string

Devuelve la cadena de versión de la librería nativa subyacente.

Pdf::prefetchAvailable(): bool

Devuelve si el prefetch de modelos de OCR está disponible en esta compilación.

Pdf::prefetchModels(array $languages): string

Precarga los modelos de OCR para los códigos de idioma indicados; devuelve una cadena de estado.

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

Ciclo de vida

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

Inspecciona, libera o accede al handle nativo en crudo.

PdfPage

Una vista ligera por página devuelta por PdfDocument::page(), pages() o pagesIter().

use PdfOxide\PdfPage;

Métodos

$page->parent(): PdfDocument

Devuelve el PdfDocument propietario.

$page->index(): int

Devuelve el índice de la página con base cero.

$page->text(): string

Extrae texto plano de esta página.

$page->textAuto(): string

Extrae texto de esta página con selección automática entre texto nativo y OCR.

$page->toMarkdown(): string

Convierte esta página a Markdown.

$page->toHtml(): string

Convierte esta página a HTML.

$page->__toString(): string

Devuelve el texto plano de la página cuando el objeto se usa en contexto de cadena.

MarkdownConverter

Utilidades estáticas para convertir un PdfDocument abierto a Markdown, HTML o texto plano.

use PdfOxide\MarkdownConverter;

Métodos

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

Convierte una sola página a Markdown.

MarkdownConverter::toMarkdownAll(PdfDocument $doc): string

Convierte el documento completo a Markdown.

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

Convierte una sola página a HTML.

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

Convierte una sola página a texto plano.

AutoExtractor

Extracción con motivo tipado, selección entre texto nativo y OCR, y clasificación de documentos por página.

use PdfOxide\AutoExtractor;

Constantes

Constante Valor Significado
AutoExtractor::MODE_AUTO 0 Selecciona automáticamente texto nativo u OCR
AutoExtractor::MODE_TEXT_ONLY 1 Solo texto nativo, nunca OCR
AutoExtractor::MODE_FORCE_OCR 2 Ejecuta siempre OCR

Métodos de fábrica

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

Crea un extractor sobre un documento con un modo explícito.

AutoExtractor::fast(PdfDocument $doc): self

Crea un extractor optimizado para la velocidad.

AutoExtractor::balanced(PdfDocument $doc): self

Crea un extractor que equilibra velocidad y fidelidad.

AutoExtractor::highFidelity(PdfDocument $doc): self

Crea un extractor optimizado para la máxima fidelidad.

Extracción

$ex->extractText(): string

Extrae texto del documento completo.

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

Extrae texto de una sola página.

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

Extrae una sola página y devuelve un AutoExtractResult tipado con motivo y confianza.

$ex->extractAutoDocument(): AutoExtractResult

Extrae el documento completo y devuelve un AutoExtractResult tipado.

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

Extrae una sola página como cadena JSON.

$ex->extractDocumentJson(): string

Extrae el documento completo como cadena JSON.

Clasificación

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

Clasifica una sola página (por ejemplo, text_layer, scanned, image_text, mixed, empty).

$ex->classifyDocumentKinds(): array

Clasifica todas las páginas y devuelve un array de cadenas con el tipo de cada página.

Accesores

$ex->document(): PdfDocument

Devuelve el PdfDocument subyacente.

$ex->mode(): int

Devuelve la constante del modo de extracción activo.

AutoExtractResult

Objeto de valor de solo lectura devuelto por AutoExtractor::extractAutoPage() y extractAutoDocument().

use PdfOxide\AutoExtractResult;

Propiedades

Propiedad Tipo Descripción
text string Texto extraído
reason string Una de las constantes REASON_*
confidence float Confianza en [0.0, 1.0]
ocrUsed bool Si se ejecutó OCR para este resultado
regions array Detalle enriquecido por región
pagesNeedingOcr array Índices de las páginas que aún necesitan 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

Devuelve si la extracción tuvo éxito sin degradación.

$result->isOcrFallback(): bool

Devuelve si se activó una ruta de respaldo por OCR no disponible o de baja confianza.

DocumentEditor

Edita un PDF in situ: depura metadatos, aplica redacciones destructivas, establece el productor y guarda.

use PdfOxide\DocumentEditor;

Constructor

DocumentEditor::open(string $path): self

Abre un PDF para editarlo.

Redacción

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

Pone en cola una región de redacción rectangular (coordenadas en puntos PDF). Fluido — devuelve $this.

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

Devuelve el número de redacciones pendientes en una página.

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

Aplica de forma permanente todas las redacciones en cola (falla de forma segura ante errores). Devuelve el número aplicado; opcionalmente depura los metadatos.

Metadatos

$editor->scrubMetadata(): self

Elimina los metadatos del documento. Fluido — devuelve $this.

$editor->getProducer(): string

Devuelve la cadena Producer del documento.

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

Establece la cadena Producer del documento. Fluido — devuelve $this.

Información del documento

$editor->version(): array

Devuelve la versión del PDF como un array [major, minor].

$editor->pageCount(): int

Devuelve el número de páginas.

$editor->isModified(): bool

Devuelve si el documento tiene modificaciones sin guardar.

$editor->sourcePath(): string

Devuelve la ruta del archivo de origen.

Guardado

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

Escribe el PDF editado en una ruta de archivo.

$editor->save(): string

Renderiza el PDF editado y devuelve sus bytes como cadena.

Ciclo de vida

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

Inspecciona, libera o accede al handle nativo en crudo.

PdfSigner

Firma digital PAdES con los niveles de conformidad B-B, B-T, B-LT y B-LTA.

use PdfOxide\PdfSigner;

Constantes

Constante Valor Nivel
PdfSigner::LEVEL_B_B 0 PAdES B-B (baseline)
PdfSigner::LEVEL_B_T 1 PAdES B-T (con marca de tiempo)
PdfSigner::LEVEL_B_LT 2 PAdES B-LT (largo plazo)
PdfSigner::LEVEL_B_LTA 3 PAdES B-LTA (largo plazo con marca de tiempo de archivo)

Constructor / Fábrica

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

Crea un firmante a partir de un almacén de claves PKCS#12 (.p12 / .pfx).

Firma

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

Firma los bytes del PDF y devuelve los bytes del PDF firmado. Los niveles superiores a B-B requieren un tsaUrl. $level acepta el ordinal LEVEL_B_* o una etiqueta corta ('b', 't', 'lt', 'lta').

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

Atajo estático: firma sin construir una instancia gestionada de firmante. El llamante conserva la propiedad de $certificateHandle.

Verificación

PdfSigner::verify(string $pdfBytes): bool

Devuelve si los bytes del PDF incluyen un diccionario de firma y un rango de bytes.

Ciclo de vida

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

Inspecciona o libera las credenciales de firma.

PdfValidator

Comprobaciones estáticas de conformidad PDF/A, PDF/UA y PDF/X contra un PdfDocument abierto.

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

Devuelve si el documento cumple el nivel PDF/A indicado.

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

Devuelve si el documento cumple el nivel PDF/UA indicado.

PdfValidator::isPdfX(PdfDocument $doc): bool

No implementado — pdf_oxide actualmente no expone ningún validador público de PDF/X en el ABI de C. Llamarlo siempre lanza BadMethodCallException.

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

Ejecuta una validación PDF/A completa y devuelve un array de resultado estructurado (indicador de conformidad más cualquier infracción).

PdfPolicy

Política de gobernanza criptográfica global del proceso, establecida una sola vez. Debe configurarse antes de abrir cualquier PDF.

use PdfOxide\PdfPolicy;

Constantes

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

Métodos

PdfPolicy::current(): string

Devuelve el modo de política activo.

PdfPolicy::set(string $mode): void

Establece la política global del proceso (una de las constantes de política). Se establece una sola vez por proceso.

PdfPolicy::fipsAvailable(): bool

Devuelve si hay disponible un proveedor criptográfico validado para FIPS.

PdfPolicy::activeProvider(): string

Devuelve el nombre del proveedor criptográfico activo.

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

Accesores de conveniencia que devuelven la cadena del modo de política correspondiente.

Manejo de errores

Todos los errores específicos de PDF extienden PdfOxide\Exceptions\PdfException. Las subclases especializadas permiten capturar categorías de fallo más concretas.

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()}");
}
Excepción (bajo PdfOxide\Exceptions\) Causa
PdfException Clase base de todos los errores de PDF
ParseException PDF malformado o imposible de parsear
IoException Fallo de lectura/escritura de archivo
NotFoundException Archivo, página u objeto inexistente
EncryptionException Fallo de cifrado / contraseña
ValidationException Argumento o entrada no válidos
SignatureException Fallo de firma o de verificación de firma
RedactionException Fallo de redacción
SearchException Fallo de búsqueda
OptimizationException Fallo de optimización
ComplianceException Fallo de conformidad PDF/A o PDF/UA
AccessibilityException Fallo de accesibilidad / etiquetado
UnsupportedException Función u operación no soportada
InvalidStateException Operación sobre un handle cerrado o no válido
InternalError Error nativo interno

Ejemplo 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

PDF Oxide ofrece bindings nativos para todos los ecosistemas principales: Rust, Python, Node.js, WASM, C#, Golang, Java, Ruby, C++, Swift, Kotlin, Dart, R, Julia, Zig, Scala, Clojure, Objective-C y Elixir.

Próximos pasos