Contracts / Extraction

Visão geral

O domínio de extração define os contratos que você usa para ler e validar arquivos Portable Document Format (PDF) e transformar seu conteúdo em dados estruturados. Ele inclui o inspetor, os validadores de conformidade, o gerenciador de PDF/A, os contratos de objetos importados, os contratos de embedding e índice vetorial e o subnamespace do validador de faturas eletrônicas.

Instalação

composer require nextpdf/core:^3

Visão conceitual

InspectorInterface lê bytes brutos de um PDF e retorna um InspectResult estruturado. O resultado enumera os objetos do arquivo. Use este contrato em qualquer ferramenta que leia um PDF que não tenha sido escrito pelo engine.

ExternalComplianceValidatorInterface conecta o engine a um verificador externo, como o veraPDF. O verificador testa PDF/A e PDF/Universal Accessibility (PDF/UA). Quando não há verificador configurado, a implementação nula retorna um resultado “unavailable”. Um ambiente sem o veraPDF continua funcionando. ProfileValidatorInterface verifica o runtime em relação a um perfil de implantação, incluindo as extensões obrigatórias e recomendadas. Ele retorna um veredito tipado.

PdfAManagerInterface mantém um arquivo PDF/A conforme a especificação enquanto o writer o constrói. Ele bloqueia JavaScript, ações de formulário em JavaScript e a criptografia integrada. O PDF/A proíbe os três. Ele também verifica se todas as fontes estão embutidas, define metadados conformes à especificação e grava os objetos necessários antes do catálogo. A classe concreta vem na edição Pro. O core a localiza com class_exists() e faz o cast dela para o contrato. O engine open-source não traz nenhuma dependência paga.

Dois contratos cobrem os objetos importados: ImportedFormObjectInterface e EmbeddedPdfObjectInterface. Eles fornecem acesso tipado a objetos lidos de um PDF existente, para que o engine possa reembuti-los. O caminho lossless mantém os bytes brutos do dicionário. O caminho de fallback fornece um array de dicionário já parseado para objetos retirados de fluxos de objetos (object streams). Cada objeto reembutido é um objeto indireto de PDF. Um número de objeto e um número de geração o identificam, conforme definido pela ISO 32000-2 §7.3.10.

Os contratos de embedding dão suporte à busca. EmbeddingServiceInterface transforma texto em um vetor denso e informa a dimensão e o nome do modelo, para que os chamadores possam se adaptar em tempo de execução. A edição Pro executa um modelo em central processing unit (CPU). A edição Enterprise executa um modelo em graphics processing unit (GPU). VectorIndexInterface constrói e pesquisa em um índice de vizinho mais próximo. Ele é o índice pequeno e in-process para uso do core. Buscas maiores permanecem em um contrato exclusivo da edição Enterprise.

O grupo EInvoice contém o verificador de faturas eletrônicas presente em todas as edições. ValidatorInterface executa verificações de preflight em um payload Cross Industry Invoice (CII) ou Universal Business Language (UBL). SchematronRunnerInterface executa a etapa de regras de negócio. ValidationResult reúne as constatações e as violações de regras. O verificador deve rejeitar entradas inválidas com um resultado, em vez de uma exceção. Ele também deve se proteger contra payloads com uma Document Type Declaration (DOCTYPE) e contra payloads superdimensionados.

Superfície de API

Tipo	Categoria	Membros principais	Estabilidade	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()	stable	1.10.0
ImportedFormObjectInterface	interface	getWidth(), getHeight(), getEmbeddedObjects(), getResourcesDict(), getMediaBox(), getContentStream()	stable	1.8.0
EmbeddedPdfObjectInterface	interface	getRawDictionaryBytes(), getRawStreamData(), getDictionary()	stable	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

O namespace EInvoice também publica SchematronRunnerInterface, ProfileInterface, ValidationFinding, RuleViolation e os enums ProfileType, RuleSeverity e ValidationFindingLevel.

Exemplo de código — Início rápido

examples/contracts/extraction-quickstart.php

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

A função depende do contrato. Qualquer implementação de inspetor pode atendê-lo.

Exemplo de código — Produção

examples/contracts/extraction-production.php

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

O serviço trata explicitamente o caso em que o validador está indisponível, em vez de presumir que existe um validador disponível.

Casos extremos e armadilhas

• EInvoice\ValidatorInterface::validate() retorna um ValidationResult com falha para entradas malformadas. Ele não lança exceção para violações de well-formedness. Verifique $isValid; não envolva a chamada em um try/catch para esse caso.
• ExternalComplianceValidatorInterface::isAvailable() deve ser verificado antes de você confiar em um veredito. A implementação nula retorna “unavailable”. Tratar isso como “non-conformant” produz falsos negativos.
• EmbeddedPdfObjectInterface::getRawDictionaryBytes() retorna null para objetos retirados de um fluxo de objetos (object stream). Recorra a getDictionary(). Não presuma que os bytes brutos existem.
• EmbeddingServiceInterface::getDimension() varia conforme a edição. O código que aloca um vetor de largura fixa deve ler a dimensão em tempo de execução, e não codificá-la diretamente.
• VectorIndexInterface::build() exige listas de vetores e de ids com o mesmo comprimento e dimensões consistentes. Uma incompatibilidade lança InvalidArgumentException. Valide as listas antes de construir o índice.

Desempenho

O custo da inspeção e da validação cresce conforme o tamanho do documento e a quantidade de objetos. O performance_budget de 1500 ms de wall time e 64 MB de pico cobre um documento moderado. Uma chamada externa ao veraPDF adiciona seu próprio tempo de processo. Esse tempo fica fora do orçamento do engine e deve ser executado fora do caminho da requisição. O custo de embedding cresce conforme o tamanho do texto e é muito mais barato em lote do que em um loop, especialmente em um modelo de GPU. Prefira batchEmbed(). A busca vetorial é sublinear em relação ao tamanho do índice para o índice in-process. O perfil de reprodutibilidade é structural. Um relatório de validação registra um timestamp e uma impressão digital do ambiente. Duas execuções diferem nesses campos, enquanto o veredito de conformidade permanece idêntico.

Notas de segurança

A extração lê documentos que o engine não criou, então toda entrada deve ser tratada como não confiável. O inspetor e o validador de faturas eletrônicas parseiam bytes fornecidos externamente. O validador de faturas eletrônicas deve bloquear payloads com Document Type Declaration (DOCTYPE), superdimensionados e com caracteres de controle proibidos antes de parsear, para evitar ataques de entidade externa de Extensible Markup Language (XML) e de billion-laughs. O reembutimento de objetos importados copia bytes de um PDF externo. Um objeto de origem malicioso pode carregar conteúdo hostil, então o reembutimento preserva os bytes sem executá-los. A imposição de PDF/A remove JavaScript e ações. O gerenciador de PDF/A rejeita JavaScript e criptografia porque ambos são proibidos no perfil e também são vetores de abuso em um documento de arquivamento de longa duração. Trate o conteúdo inspecionado, os objetos importados e o XML de fatura como entrada hostil em todo o fluxo.

Conformidade

Afirmação	Padrão	Cláusula	Evidência
O PDF/A-4 proíbe JavaScript e ações de formulário em JavaScript; o gerenciador de PDF/A rejeita ambos.	ISO 19005-4	§6.7.1	citado por cláusula (não está no corpus)
Cada objeto reembutido é um objeto indireto de PDF identificado por número de objeto e geração.	ISO 32000-2	§7.3.10

ISO 19005-4 é citada por cláusula. Ela não está no corpus de citações verificáveis, então nenhum reference_id é registrado. A afirmação sobre objeto indireto da ISO 32000-2 está fixada ao glossário. Ambas as afirmações são parafraseadas. O engine não reproduz nenhum texto normativo.

Contexto comercial

O core define e congela os contratos de extração. O código de produção por trás de PdfAManagerInterface, EmbeddingServiceInterface e VectorIndexInterface vem nas edições Pro e Enterprise, incluindo os modelos de embedding em CPU e GPU e o caminho completo de imposição de PDF/A. O core resolve esses casos em tempo de execução com class_exists(). Portanto, o engine open-source não carrega nenhuma dependência comercial, e a application programming interface (API) não muda ao atualizar.

Veja também

• Contratos: 41 interfaces públicas — a visão geral da Service Provider Interface (SPI) e as faixas de estabilidade.
• Contracts / Document — os contratos de documento que produzem o carrier PDF/A.
• Contracts / Signing — arquivamento assinado que combina com a imposição de PDF/A.
• Inspect — a implementação do inspetor por trás de InspectorInterface.
• Text — extração de texto que consome objetos inspecionados.
• Metadata — metadados de PDF/A configurados pelo gerenciador.