Contracts / Extraction

In het kort

Het extractiedomein definieert de contracten waarmee u bestanden in het Portable Document Format (PDF) leest, valideert en hun inhoud omzet in gestructureerde gegevens. Het omvat de inspector, de conformiteitsvalidators, de PDF/A-manager, de contracten voor geïmporteerde objecten, de contracten voor embedding en vector-index, en de sub-namespace van de e-factuurvalidator.

Installatie

composer require nextpdf/core:^3

Conceptueel overzicht

InspectorInterface leest ruwe PDF-bytes en geeft een gestructureerd InspectResult terug. Het resultaat somt de objecten in het bestand op. Gebruik dit contract voor elke tool die een PDF leest die de engine niet heeft geschreven.

ExternalComplianceValidatorInterface koppelt de engine aan een externe checker zoals veraPDF. De checker test PDF/A en PDF/Universal Accessibility (PDF/UA). Als er geen checker is geconfigureerd, geeft de null-implementatie een “niet beschikbaar”-resultaat terug. Een site zonder veraPDF blijft werken. ProfileValidatorInterface controleert de runtime aan de hand van een deployment-profiel, inclusief vereiste en aanbevolen extensies. Het geeft een getypeerd oordeel terug.

PdfAManagerInterface houdt een PDF/A-bestand conform de specificatie terwijl de writer het opbouwt. Het blokkeert JavaScript, JavaScript-formulieracties en ingebouwde versleuteling. PDF/A verbiedt alle drie. Het controleert ook dat elk lettertype is ingesloten, stelt metadata volgens de specificatie in en schrijft de benodigde objecten vóór de catalogus. De daadwerkelijke klasse wordt geleverd in de Pro-editie. Core vindt die met class_exists() en cast die naar het contract. De open-source-engine heeft geen betaalde afhankelijkheid.

Twee contracten beschrijven geïmporteerde objecten: ImportedFormObjectInterface en EmbeddedPdfObjectInterface. Ze bieden getypeerde toegang tot objecten die uit een bestaande PDF zijn gelezen, zodat de engine ze opnieuw kan insluiten. Het verliesvrije pad behoudt de ruwe dictionary-bytes. Het fallback-pad levert een geparseerde dictionary-array voor objecten die uit object-streams zijn gehaald. Elk opnieuw ingesloten object is een PDF-indirect object. Een objectnummer en een generatienummer identificeren het, zoals ISO 32000-2 §7.3.10 definieert.

De embedding-contracten ondersteunen zoeken. EmbeddingServiceInterface zet tekst om in een dichte vector en rapporteert de dimensie en modelnaam, zodat aanroepers zich tijdens runtime kunnen aanpassen. De Pro-editie draait een model op de central processing unit (CPU). De Enterprise-editie draait een model op de graphics processing unit (GPU). VectorIndexInterface bouwt en doorzoekt een nearest-neighbor-index. Het is de kleine in-process-index voor gebruik in Core. Grootschaliger zoeken blijft ondergebracht in een Enterprise-only-contract.

De EInvoice-groep bevat de niveau-overstijgende e-factuurchecker. ValidatorInterface voert preflight-controles uit op een payload van het type Cross Industry Invoice (CII) of Universal Business Language (UBL). SchematronRunnerInterface voert de bedrijfsregelcontrole uit. ValidationResult verzamelt bevindingen en regelschendingen. De checker moet ongeldige invoer afwijzen met een resultaat, niet met een exception. De checker moet zich ook beschermen tegen payloads met een Document Type Declaration (DOCTYPE) en tegen te grote payloads.

API-oppervlak

Type	Soort	Belangrijkste leden	Stabiliteit	Sinds
`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

De EInvoice-namespace publiceert ook SchematronRunnerInterface, ProfileInterface, ValidationFinding, RuleViolation, en de enums ProfileType, RuleSeverity en ValidationFindingLevel.

Codevoorbeeld — Snelstart

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

De functie is afhankelijk van het contract. Elke inspector-implementatie kan eraan voldoen.

Codevoorbeeld — Productie

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

De service behandelt expliciet het geval waarin de validator niet beschikbaar is, in plaats van aan te nemen dat er een validator aanwezig is.

Randgevallen en valkuilen

EInvoice\ValidatorInterface::validate() geeft een falend ValidationResult terug voor misvormde invoer. Het werpt geen exception bij schendingen van welgevormdheid. Controleer $isValid; wikkel de aanroep voor dat geval niet in een try/catch.
ExternalComplianceValidatorInterface::isAvailable() moet worden gecontroleerd voordat u op een oordeel vertrouwt. De null-implementatie geeft “niet beschikbaar” terug. Dit behandelen als “niet-conform” levert valse negatieven op.
EmbeddedPdfObjectInterface::getRawDictionaryBytes() geeft null terug voor objecten die uit een object-stream zijn gehaald. Val terug op getDictionary(). Ga er niet van uit dat er ruwe bytes bestaan.
EmbeddingServiceInterface::getDimension() verschilt per editie. Code die een vector met vaste breedte alloceert, moet de dimensie tijdens runtime uitlezen en niet hardcoderen.
VectorIndexInterface::build() vereist vector- en id-lijsten met gelijke lengte en consistente dimensies. Een mismatch veroorzaakt InvalidArgumentException. Valideer de lijsten voordat u de index bouwt.

Prestaties

De kosten van inspectie en validatie schalen mee met de documentgrootte en het aantal objecten. Het performance_budget van 1500 ms wall en 64 MB piek dekt één document van gemiddelde grootte. Een externe veraPDF-aanroep voegt zijn eigen procestijd toe. Die tijd valt buiten het engine-budget; voer die controle daarom buiten het request-pad uit. De embedding-kosten schalen mee met de tekstlengte en zijn veel lager in een batch dan in een lus, vooral op een GPU-model. Geef de voorkeur aan batchEmbed(). Vectorzoeken is sublineair in de indexgrootte voor de in-process-index. Het reproduceerbaarheidsprofiel is structural. Een rapport op validatieniveau registreert een tijdstempel en een omgevingsvingerafdruk. Twee runs verschillen in die velden, terwijl het conformiteitsoordeel identiek blijft.

Beveiligingsnotities

Extractie leest documenten die de engine niet heeft gemaakt, dus elke invoer is onvertrouwd. De inspector en de e-factuurvalidator parseren beide extern aangeleverde bytes. De e-factuurvalidator moet payloads met een Document Type Declaration (DOCTYPE), te grote payloads en payloads met verboden stuurtekens blokkeren vóór het parseren, om aanvallen via externe entiteiten in de Extensible Markup Language (XML) en billion-laughs-aanvallen te voorkomen. Het opnieuw insluiten van geïmporteerde objecten kopieert bytes uit een externe PDF. Een kwaadaardig bronobject kan vijandige inhoud bevatten, dus het opnieuw insluiten behoudt bytes zonder ze uit te voeren. PDF/A-handhaving verwijdert JavaScript en acties. De PDF/A-manager wijst JavaScript en versleuteling af, omdat beide in het profiel verboden zijn en beide misbruikvectoren zijn in een langdurig bewaard archiefdocument. Behandel geïnspecteerde inhoud, geïmporteerde objecten en factuur-XML overal als vijandige invoer.

Conformiteit

Bewering	Standaard	Clausule	Bewijs
PDF/A-4 verbiedt JavaScript en JavaScript-formulieracties; de PDF/A-manager wijst beide af.	ISO 19005-4	§6.7.1	geciteerd op clausule (niet in corpus)
Elk opnieuw ingesloten object is een PDF-indirect object dat wordt geïdentificeerd door objectnummer en generatie.	ISO 32000-2	§7.3.10

ISO 19005-4 wordt op clausuleniveau geciteerd. Het staat niet in het verifieerbare citatiecorpus, dus er wordt geen reference_id vastgelegd. De bewering over het indirect object van ISO 32000-2 is verankerd in de woordenlijst. Beide beweringen zijn geparafraseerd. De engine reproduceert geen normatieve tekst.

Commerciële context

Core definieert en bevriest de extractiecontracten. De productiecode achter PdfAManagerInterface, EmbeddingServiceInterface en VectorIndexInterface wordt geleverd in de Pro- en Enterprise-editie, inclusief CPU- en GPU-embedding-modellen en het volledige PDF/A-handhavingspad. Core lost die implementaties tijdens runtime op met class_exists(). De open-source-engine draagt daarom geen commerciële afhankelijkheid, en de application programming interface (API) verandert niet bij een upgrade.

Zie ook

Contracts: 41 publieke interfaces — het overzicht van de Service Provider Interface (SPI) en de stabiliteitsniveaus.
Contracts / Document — de documentcontracten die de PDF/A-drager produceren.
Contracts / Signing — ondertekende archivering die samengaat met PDF/A-handhaving.
Inspect — de inspector-implementatie achter InspectorInterface.
Text — tekstextractie die geïnspecteerde objecten gebruikt.
Metadata — PDF/A-metadata die door de manager wordt geconfigureerd.