Contratos / Extracción

Vistazo general

El dominio de extracción reúne los contratos para leer y validar PDF, y convertir su contenido en datos estructurados. Incluye el inspector, los validadores de conformidad, el gestor de PDF/A, los contratos de objetos importados, los contratos de embedding e índice vectorial y el subespacio de nombres del validador de factura electrónica.

Instalación

composer require nextpdf/core:^3

Resumen conceptual

InspectorInterface lee un PDF en bruto. Devuelve un InspectResult estructurado. El resultado enumera los objetos del archivo. Debe usarse para cualquier herramienta que lea un PDF que el motor no escribió.

ExternalComplianceValidatorInterface actúa como puente con un verificador externo como veraPDF. El verificador comprueba PDF/A y PDF/UA. La implementación nula devuelve un resultado «no disponible» cuando no hay ningún verificador configurado. Un sitio sin veraPDF sigue funcionando. ProfileValidatorInterface comprueba el entorno de ejecución frente a un perfil de despliegue. Examina las extensiones requeridas y recomendadas. Devuelve un veredicto tipado.

PdfAManagerInterface mantiene un archivo PDF/A conforme a la especificación mientras se escribe. Bloquea JavaScript, las acciones de formulario en JavaScript y el cifrado integrado. PDF/A prohíbe los tres elementos. También comprueba que todas las fuentes estén incrustadas. Establece metadatos conformes a la especificación. Escribe los objetos necesarios antes del catálogo. La implementación real se incluye en la edición Pro. Core la encuentra con class_exists() y la adapta al contrato. Así, el motor de código abierto no tiene ninguna dependencia de pago.

Dos contratos cubren los objetos importados: ImportedFormObjectInterface y EmbeddedPdfObjectInterface. Dan acceso tipado a los objetos leídos de un PDF existente. A partir de ahí, el motor puede volver a incrustarlos. La vía sin pérdidas conserva los bytes del diccionario en bruto. Una vía alternativa proporciona un array con el diccionario analizado para los objetos tomados de flujos de objetos. Cada objeto reincrustado es un objeto indirecto de PDF. Un número de objeto y un número de generación lo identifican — ISO 32000-2 §7.3.10.

Los contratos de embedding sirven al trabajo de búsqueda. EmbeddingServiceInterface convierte texto en un vector denso. Informa de la dimensión y el nombre del modelo. El código llamador se adapta en tiempo de ejecución. La edición Pro ejecuta un modelo de CPU. La edición Enterprise ejecuta un modelo de GPU. VectorIndexInterface construye un índice de vecinos más cercanos y lo consulta. Es el índice pequeño en proceso para uso de core. Las búsquedas de mayor tamaño residen en un contrato exclusivo de Enterprise.

El grupo EInvoice contiene el verificador multinivel de factura electrónica. ValidatorInterface ejecuta comprobaciones previas sobre una carga útil CII o UBL. SchematronRunnerInterface ejecuta la fase de reglas de negocio. ValidationResult recopila los hallazgos y las infracciones de reglas. El verificador debe rechazar las entradas incorrectas con un resultado, no con una excepción. También debe protegerse frente a DOCTYPE y cargas útiles de tamaño excesivo.

Superficie de la API

Tipo	Clase	Miembros clave	Estabilidad	Desde
`InspectorInterface`	interface	`inspect(string, InspectConfig): InspectResult`	experimental	2.2.0
`ExternalComplianceValidatorInterface`	interface	`validate(string, ComplianceFlavour)`, `isAvailable()`	experimental	2.4.0
`ProfileValidatorInterface`	interface	`validate(DeploymentProfile): DeploymentProfileResult`	experimental	2.4.0
`PdfAManagerInterface`	interface	`validateNoJavaScript()`, `validateFont()`, `validateNoEncryption()`, `applyOutputProfile()`, `writeRequiredObjects()`	estable	1.10.0
`ImportedFormObjectInterface`	interface	`getWidth()`, `getHeight()`, `getEmbeddedObjects()`, `getResourcesDict()`, `getMediaBox()`, `getContentStream()`	estable	1.8.0
`EmbeddedPdfObjectInterface`	interface	`getRawDictionaryBytes()`, `getRawStreamData()`, `getDictionary()`	estable	1.8.0
`EmbeddingServiceInterface`	interface	`embed()`, `batchEmbed()`, `getDimension()`, `getModelName()`	experimental	2.1.0
`VectorIndexInterface`	interface	`build()`, `search()`, `delete()`, `count()`	experimental	2.1.0
`EInvoice\ValidatorInterface`	interface	`validate(string, ValidatorContext): ValidationResult`	experimental	5.1.0
`EInvoice\ValidationResult`	final readonly class	`$isValid`, `getErrors()`, `getWarnings()`, `fail()`	experimental	5.1.0

El espacio de nombres EInvoice también expone SchematronRunnerInterface, ProfileInterface, ValidationFinding, RuleViolation y las enumeraciones ProfileType, RuleSeverity y ValidationFindingLevel.

Ejemplo de código — Inicio rápido

<?php

declare(strict_types=1);

require_once __DIR__ . '/../../vendor/autoload.php';

use NextPDF\Contracts\InspectorInterface;
use NextPDF\Inspect\InspectConfig;

/**
 * Inspect a PDF and report its object count.
 *
 * @param InspectorInterface $inspector A configured inspector.
 * @param string             $pdfData   Raw PDF bytes.
 */
function describe(InspectorInterface $inspector, string $pdfData): \NextPDF\Inspect\InspectResult
{
    return $inspector->inspect($pdfData, new InspectConfig());
}

La función depende del contrato. Cualquier implementación de inspector cumple ese contrato.

Ejemplo de código — Producción

<?php

declare(strict_types=1);

require_once __DIR__ . '/../../vendor/autoload.php';

use NextPDF\Contracts\EInvoice\ValidatorInterface;
use NextPDF\Contracts\EInvoice\ValidatorContext;
use NextPDF\Contracts\ExternalComplianceValidatorInterface;
use NextPDF\ValueObjects\ComplianceFlavour;
use Psr\Log\LoggerInterface;

final readonly class InvoiceConformanceService
{
    public function __construct(
        private ValidatorInterface $invoiceValidator,
        private ExternalComplianceValidatorInterface $pdfaValidator,
        private LoggerInterface $logger,
    ) {}

    /**
     * Validate the invoice XML, then the PDF/A-3 carrier.
     *
     * @param string $xml     The CII or UBL invoice payload.
     * @param string $pdfPath Absolute path to the PDF/A-3 carrier.
     */
    public function validate(string $xml, string $pdfPath, ValidatorContext $ctx): bool
    {
        $result = $this->invoiceValidator->validate($xml, $ctx);

        if (!$result->isValid) {
            $this->logger->warning('Invoice XML invalid', [
                'errors' => \count($result->getErrors()),
            ]);

            return false;
        }

        if (!$this->pdfaValidator->isAvailable()) {
            $this->logger->info('PDF/A validator unavailable; skipping carrier check.');

            return true;
        }

        $carrier = $this->pdfaValidator->validate($pdfPath, ComplianceFlavour::PdfA3b);

        return $carrier->isConformant();
    }
}

El servicio gestiona explícitamente el caso en que el validador no está disponible, en lugar de dar por hecho que hay uno presente.

Casos límite y trampas

EInvoice\ValidatorInterface::validate() devuelve un ValidationResult fallido para la entrada con formato incorrecto. No lanza excepciones ante infracciones de buena formación. Debe comprobarse $isValid; no debe envolverse la llamada en un try/catch para ese caso.
ExternalComplianceValidatorInterface::isAvailable() debe comprobarse antes de confiar en un veredicto. La implementación nula devuelve «no disponible». Tratar eso como «no conforme» produce falsos negativos.
EmbeddedPdfObjectInterface::getRawDictionaryBytes() devuelve null para los objetos tomados de un flujo de objetos. Debe recurrirse a getDictionary(). No debe darse por hecho que existen los bytes en bruto.
EmbeddingServiceInterface::getDimension() difiere según el nivel. El código que reserva un vector de ancho fijo debe leer la dimensión en tiempo de ejecución, no fijarla en el código.
VectorIndexInterface::build() requiere que las listas de vectores e identificadores tengan la misma longitud y dimensiones coherentes. Una discrepancia lanza InvalidArgumentException. Debe validarse antes de construir.

Rendimiento

El coste de la inspección y la validación escala con el tamaño del documento y el recuento de objetos. El performance_budget de 1500 ms de tiempo de reloj y 64 MB de pico cubre un único documento de tamaño moderado. Una llamada externa a veraPDF añade el tiempo de procesamiento propio del validador. Ese tiempo de procesamiento queda fuera del presupuesto del motor y debería ejecutarse fuera de la ruta de la solicitud. El coste del embedding escala con la longitud del texto y es mucho menor por lotes que en bucle, sobre todo en un modelo de GPU. Debe preferirse batchEmbed(). La búsqueda vectorial es sublineal respecto al tamaño del índice para el índice en proceso. El perfil de reproducibilidad es structural. Un informe de validación registra una marca de tiempo y una huella del entorno. Dos ejecuciones difieren en esos campos, mientras que el veredicto de conformidad permanece idéntico.

Notas de seguridad

La extracción lee documentos que el motor no creó, por lo que no se debe confiar en ninguna entrada. Tanto el inspector como el validador de factura electrónica analizan bytes suministrados externamente. El validador de factura electrónica debe filtrar las cargas útiles con DOCTYPE, de tamaño excesivo y con caracteres de control prohibidos antes de analizarlas, para evitar ataques de entidades externas XML y de billion laughs. La reincrustación de objetos importados copia bytes de un PDF externo. Un objeto de origen malicioso puede transportar contenido hostil, así que la reincrustación conserva los bytes sin ejecutarlos. La imposición de PDF/A elimina JavaScript y acciones. El gestor de PDF/A rechaza JavaScript y el cifrado porque ambos están prohibidos en el perfil y ambos son vectores de abuso en un documento de archivo de larga vida. Debe tratarse el contenido inspeccionado, los objetos importados y el XML de la factura como entrada hostil en todo momento.

Conformidad

Afirmación	Estándar	Cláusula	Evidencia
PDF/A-4 prohíbe JavaScript y las acciones de formulario en JavaScript; el gestor de PDF/A rechaza ambas.	ISO 19005-4	§6.7.1	citado por cláusula (no está en el corpus)
Cada objeto vuelto a incrustar es un objeto indirecto de PDF identificado por número de objeto y generación.	ISO 32000-2	§7.3.10

ISO 19005-4 se referencia por cláusula. No está en el corpus de citas verificables, por lo que no se registra ningún reference_id. La afirmación sobre el objeto indirecto de ISO 32000-2 está fijada en el glosario. Ambas afirmaciones están parafraseadas. El motor no reproduce ningún texto normativo.

Contexto comercial

Core define y fija los contratos de extracción. El código de producción que respalda PdfAManagerInterface, EmbeddingServiceInterface y VectorIndexInterface se incluye en las ediciones Pro y Enterprise, incluidos los modelos de embedding de CPU y GPU y la vía completa de imposición de PDF/A. Core los resuelve en tiempo de ejecución con class_exists(). Por tanto, el motor de código abierto no incorpora ninguna dependencia comercial, y la API no cambia al actualizar.

Véase también

Contratos: 41 interfaces públicas (SPI) — resumen de la SPI y de los niveles de estabilidad.
Contratos / Document — contratos de documento que producen el portador PDF/A.
Contratos / Signing — archivado firmado que se combina con la imposición de PDF/A.
Inspect — la implementación del inspector que respalda InspectorInterface.
Text — extracción de texto que consume los objetos inspeccionados.
Metadata — metadatos de PDF/A configurados por el gestor.