Kontrakty / Ekstrakcja

W skrócie

Domena ekstrakcji definiuje kontrakty używane do odczytu i walidacji plików Portable Document Format (PDF) oraz przekształcania ich zawartości w dane strukturalne. Obejmuje inspektor, walidatory zgodności, menedżer PDF/A, kontrakty obiektów importowanych, kontrakty osadzeń i indeksu wektorowego oraz podprzestrzeń nazw walidatora e-faktur.

Instalacja

composer require nextpdf/core:^3

Przegląd koncepcyjny

InspectorInterface odczytuje surowe bajty PDF i zwraca ustrukturyzowany InspectResult. Wynik zawiera listę obiektów znajdujących się w pliku. Używaj tego kontraktu w każdym narzędziu, które odczytuje plik PDF, którego nie zapisał silnik.

ExternalComplianceValidatorInterface łączy silnik z zewnętrznym narzędziem sprawdzającym, takim jak veraPDF. Narzędzie sprawdzające weryfikuje zgodność z PDF/A oraz PDF/Universal Accessibility (PDF/UA). Gdy nie skonfigurowano żadnego narzędzia sprawdzającego, implementacja null zwraca wynik „niedostępne”. Instalacja bez veraPDF nadal działa. ProfileValidatorInterface sprawdza środowisko uruchomieniowe względem profilu wdrożenia, w tym wymagane i zalecane rozszerzenia. Zwraca typowany werdykt.

PdfAManagerInterface utrzymuje zgodność pliku PDF/A ze specyfikacją podczas budowania go przez komponent zapisujący. Blokuje JavaScript, akcje formularzy JavaScript oraz wbudowane szyfrowanie. PDF/A zabrania wszystkich tych trzech elementów. Sprawdza także, czy każda czcionka jest osadzona, ustawia metadane zgodne ze specyfikacją oraz zapisuje potrzebne obiekty przed katalogiem. Właściwa klasa jest dostarczana w edycji Pro. Core wykrywa ją za pomocą class_exists() i rzutuje ją na kontrakt. Silnik open source nie ma żadnej płatnej zależności.

Obiekty importowane obejmują dwa kontrakty: ImportedFormObjectInterface oraz EmbeddedPdfObjectInterface. Zapewniają typowany dostęp do obiektów odczytanych z istniejącego pliku PDF, aby silnik mógł je ponownie osadzić. Ścieżka bezstratna zachowuje surowe bajty słownika. Ścieżka zapasowa udostępnia sparsowaną tablicę słownika dla obiektów pobranych ze strumieni obiektów. Każdy ponownie osadzony obiekt jest pośrednim obiektem PDF. Identyfikują go numer obiektu i numer generacji, zgodnie z definicją w ISO 32000-2 §7.3.10.

Kontrakty osadzeń obsługują wyszukiwanie. EmbeddingServiceInterface przekształca tekst w gęsty wektor oraz raportuje rozmiar i nazwę modelu, dzięki czemu wywołujący mogą dostosować zachowanie w czasie wykonywania. Edycja Pro uruchamia model na procesorze centralnym (CPU). Edycja Enterprise uruchamia model na procesorze graficznym (GPU). VectorIndexInterface buduje i przeszukuje indeks najbliższych sąsiadów. Jest to mały indeks działający w procesie, przeznaczony do użytku w Core. Wyszukiwanie na większą skalę pozostaje w kontrakcie dostępnym wyłącznie w edycji Enterprise.

Grupa EInvoice zawiera walidator e-faktur obejmujący wszystkie poziomy. ValidatorInterface wykonuje wstępne kontrole ładunku Cross Industry Invoice (CII) lub Universal Business Language (UBL). SchematronRunnerInterface wykonuje przebieg reguł biznesowych. ValidationResult zbiera wyniki walidacji i naruszenia reguł. Walidator musi odrzucać błędne dane wejściowe przez zwrócenie wyniku, a nie wyjątku. Musi także chronić przed ładunkami z deklaracją typu dokumentu (DOCTYPE) oraz przed ładunkami o nadmiernym rozmiarze.

Powierzchnia API

Typ	Rodzaj	Kluczowe składowe	Stabilność	Od wersji
InspectorInterface	interfejs	inspect(string, InspectConfig): InspectResult	eksperymentalny	2.2.0
ExternalComplianceValidatorInterface	interfejs	validate(string, ComplianceFlavour), isAvailable()	eksperymentalny	2.4.0
ProfileValidatorInterface	interfejs	validate(DeploymentProfile): DeploymentProfileResult	eksperymentalny	2.4.0
PdfAManagerInterface	interfejs	validateNoJavaScript(), validateFont(), validateNoEncryption(), applyOutputProfile(), writeRequiredObjects()	stabilny	1.10.0
ImportedFormObjectInterface	interfejs	getWidth(), getHeight(), getEmbeddedObjects(), getResourcesDict(), getMediaBox(), getContentStream()	stabilny	1.8.0
EmbeddedPdfObjectInterface	interfejs	getRawDictionaryBytes(), getRawStreamData(), getDictionary()	stabilny	1.8.0
EmbeddingServiceInterface	interfejs	embed(), batchEmbed(), getDimension(), getModelName()	eksperymentalny	2.1.0
VectorIndexInterface	interfejs	build(), search(), delete(), count()	eksperymentalny	2.1.0
EInvoice\ValidatorInterface	interfejs	validate(string, ValidatorContext): ValidationResult	eksperymentalny	5.1.0
EInvoice\ValidationResult	klasa final readonly	$isValid, getErrors(), getWarnings(), fail()	eksperymentalny	5.1.0

Przestrzeń nazw EInvoice publikuje również SchematronRunnerInterface, ProfileInterface, ValidationFinding, RuleViolation oraz wyliczenia ProfileType, RuleSeverity i ValidationFindingLevel.

Przykład kodu — szybki start

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

Funkcja zależy od kontraktu. Tę zależność może spełnić dowolna implementacja inspektora.

Przykład kodu — produkcja

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

Usługa jawnie obsługuje przypadek niedostępnego walidatora, zamiast zakładać, że walidator jest obecny.

Przypadki brzegowe i pułapki

• EInvoice\ValidatorInterface::validate() zwraca niepomyślny ValidationResult dla źle uformowanych danych wejściowych. Nie zgłasza wyjątku w przypadku naruszeń składni. Sprawdź $isValid; w tym przypadku nie obejmuj wywołania blokiem try/catch.
• ExternalComplianceValidatorInterface::isAvailable() trzeba sprawdzić, zanim oprzesz się na werdykcie. Implementacja null zwraca „niedostępne”. Potraktowanie tego jako „niezgodne” skutkuje fałszywie negatywnymi wynikami.
• EmbeddedPdfObjectInterface::getRawDictionaryBytes() zwraca null dla obiektów pobranych ze strumienia obiektów. W takiej sytuacji użyj getDictionary(). Nie zakładaj, że surowe bajty istnieją.
• EmbeddingServiceInterface::getDimension() różni się w zależności od poziomu. Kod, który alokuje wektor o stałej szerokości, musi odczytać wymiar w czasie wykonywania zamiast zapisywać go na sztywno.
• VectorIndexInterface::build() wymaga list wektorów i identyfikatorów o równej długości oraz spójnych wymiarach. Niezgodność powoduje zgłoszenie InvalidArgumentException. Zwaliduj listy przed zbudowaniem indeksu.

Wydajność

Koszt inspekcji i walidacji rośnie wraz z rozmiarem dokumentu i liczbą obiektów. Budżet performance_budget wynoszący 1500 ms czasu rzeczywistego i 64 MB szczytowego zużycia obejmuje jeden umiarkowany dokument. Zewnętrzne wywołanie veraPDF dodaje własny czas procesu. Czas ten znajduje się poza budżetem silnika, a wywołanie należy wykonywać poza ścieżką żądania. Koszt osadzania rośnie wraz z długością tekstu i jest znacznie niższy w trybie wsadowym niż w pętli, zwłaszcza w modelu GPU. Preferuj batchEmbed(). Wyszukiwanie wektorowe jest podliniowe względem rozmiaru indeksu dla indeksu działającego w procesie. Profil odtwarzalności to structural. Raport walidacji zapisuje znacznik czasu i odcisk środowiska. Dwa przebiegi różnią się tymi polami, natomiast werdykt zgodności pozostaje identyczny.

Uwagi dotyczące bezpieczeństwa

Ekstrakcja odczytuje dokumenty, których silnik nie utworzył, więc wszystkie dane wejściowe są niezaufane. Zarówno inspektor, jak i walidator e-faktur parsują bajty dostarczone z zewnątrz. Walidator e-faktur musi przed parsowaniem blokować ładunki z deklaracją typu dokumentu (DOCTYPE), o nadmiernym rozmiarze oraz zawierające zabronione znaki sterujące, aby zapobiec atakom z użyciem encji zewnętrznych Extensible Markup Language (XML) oraz atakom typu billion-laughs. Ponowne osadzanie obiektów importowanych kopiuje bajty z obcego pliku PDF. Złośliwy obiekt źródłowy może zawierać wrogą zawartość, dlatego ponowne osadzanie zachowuje bajty bez ich wykonywania. Egzekwowanie PDF/A usuwa JavaScript i akcje. Menedżer PDF/A odrzuca JavaScript i szyfrowanie, ponieważ oba są zabronione w profilu i oba są wektorami nadużyć w długoterminowym dokumencie archiwalnym. Traktuj zawartość poddaną inspekcji, obiekty importowane oraz XML faktury jako wrogie dane wejściowe na każdym etapie.

Zgodność

Twierdzenie	Standard	Klauzula	Dowód
PDF/A-4 zabrania JavaScriptu i akcji formularzy JavaScript; menedżer PDF/A odrzuca oba.	ISO 19005-4	§6.7.1	cytowane według klauzuli (poza korpusem)
Każdy ponownie osadzony obiekt jest pośrednim obiektem PDF identyfikowanym przez numer obiektu i generację.	ISO 32000-2	§7.3.10

ISO 19005-4 jest cytowane według klauzuli. Nie znajduje się w weryfikowalnym korpusie cytowań, więc nie zapisuje się żadnego reference_id. Twierdzenie o obiekcie pośrednim z ISO 32000-2 jest powiązane z glosariuszem. Oba twierdzenia są sparafrazowane. Silnik nie odtwarza żadnego tekstu normatywnego.

Kontekst komercyjny

Core definiuje i zamraża kontrakty ekstrakcji. Produkcyjny kod implementujący PdfAManagerInterface, EmbeddingServiceInterface oraz VectorIndexInterface jest dostarczany w edycjach Pro i Enterprise, w tym modele osadzania CPU i GPU oraz pełna ścieżka egzekwowania PDF/A. Core rozwiązuje te implementacje w czasie wykonywania za pomocą class_exists(). Silnik open source nie ma więc żadnej zależności komercyjnej, a interfejs programowania aplikacji (API) nie zmienia się podczas aktualizacji.

Zobacz także

• Kontrakty: 41 publicznych interfejsów — przegląd interfejsu dostawcy usług (SPI) i poziomów stabilności.
• Kontrakty / Dokument — kontrakty dokumentu, które wytwarzają nośnik PDF/A.
• Kontrakty / Podpisywanie — archiwizacja z podpisem, która współgra z egzekwowaniem PDF/A.
• Inspekcja — implementacja inspektora stojąca za InspectorInterface.
• Tekst — ekstrakcja tekstu, która wykorzystuje obiekty poddane inspekcji.
• Metadane — metadane PDF/A konfigurowane przez menedżera.