Kontrak / Ekstraksi

Sekilas

Domain ekstraksi mendefinisikan kontrak yang Anda gunakan untuk membaca dan memvalidasi berkas Portable Document Format (PDF), lalu mengubah isinya menjadi data terstruktur. Domain ini mencakup inspector, validator kepatuhan, pengelola PDF/A, kontrak objek yang diimpor, kontrak embedding dan indeks vektor, serta sub-namespace validator faktur elektronik.

Pemasangan

composer require nextpdf/core:^3

Tinjauan konseptual

InspectorInterface membaca byte PDF mentah dan mengembalikan InspectResult terstruktur. Hasil tersebut mencantumkan objek-objek di dalam berkas. Gunakan kontrak ini untuk alat apa pun yang membaca PDF yang tidak ditulis oleh engine.

ExternalComplianceValidatorInterface menghubungkan engine ke pemeriksa eksternal seperti veraPDF. Pemeriksa tersebut menguji PDF/A dan PDF/Universal Accessibility (PDF/UA). Ketika tidak ada pemeriksa yang dikonfigurasi, implementasi null mengembalikan hasil “tidak tersedia”. Situs tanpa veraPDF tetap berjalan. ProfileValidatorInterface memeriksa runtime terhadap profil deployment, termasuk ekstensi yang diwajibkan dan dianjurkan. Kontrak ini mengembalikan verdict bertipe.

PdfAManagerInterface menjaga berkas PDF/A tetap sesuai spesifikasi saat writer membangunnya. Kontrak ini memblokir JavaScript, aksi formulir JavaScript, dan enkripsi bawaan. PDF/A melarang ketiganya. Kontrak ini juga memastikan setiap fon sudah disematkan, menetapkan metadata yang sesuai spesifikasi, dan menulis objek yang diperlukan sebelum katalog. Kelas konkretnya disertakan dalam edisi Pro. Core menemukannya dengan class_exists() dan melakukan cast ke kontrak. Engine open-source tidak memiliki dependensi berbayar.

Dua kontrak menangani objek yang diimpor: ImportedFormObjectInterface dan EmbeddedPdfObjectInterface. Keduanya menyediakan akses bertipe ke objek yang dibaca dari PDF yang sudah ada agar engine dapat menyematkannya kembali. Jalur lossless mempertahankan byte kamus mentah. Jalur fallback menyediakan array kamus yang telah diurai untuk objek yang diambil dari aliran objek. Setiap objek yang disematkan kembali merupakan objek tidak langsung (indirect object) PDF. Nomor objek dan nomor generasi mengidentifikasinya, sebagaimana didefinisikan oleh ISO 32000-2 §7.3.10.

Kontrak embedding mendukung pencarian. EmbeddingServiceInterface mengubah teks menjadi vektor padat (dense vector) dan melaporkan dimensi serta nama model, sehingga pemanggil dapat menyesuaikan diri saat runtime. Edisi Pro menjalankan model central processing unit (CPU). Edisi Enterprise menjalankan model graphics processing unit (GPU). VectorIndexInterface membangun dan mencari indeks nearest-neighbor. Ini adalah indeks kecil dalam proses (in-process) untuk penggunaan core. Pencarian berskala lebih besar tetap berada dalam kontrak khusus Enterprise.

Grup EInvoice menampung pemeriksa faktur elektronik lintas tier. ValidatorInterface menjalankan pemeriksaan preflight pada payload Cross Industry Invoice (CII) atau Universal Business Language (UBL). SchematronRunnerInterface menjalankan lintasan aturan bisnis. ValidationResult mengumpulkan temuan dan pelanggaran aturan. Pemeriksa harus menolak input yang buruk melalui sebuah hasil, bukan dengan exception. Pemeriksa juga harus berjaga terhadap payload yang memiliki Document Type Declaration (DOCTYPE) dan payload yang berukuran berlebihan.

Permukaan API

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

Namespace EInvoice juga memublikasikan SchematronRunnerInterface, ProfileInterface, ValidationFinding, RuleViolation, serta enum ProfileType, RuleSeverity, dan ValidationFindingLevel.

Contoh kode — Mulai cepat

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

Fungsi tersebut bergantung pada kontrak. Implementasi inspector apa pun dapat memenuhinya.

Contoh kode — Produksi

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

Layanan ini menangani kasus validator yang tidak tersedia secara eksplisit, alih-alih mengasumsikan bahwa validator selalu ada.

Kasus tepi & jebakan

EInvoice\ValidatorInterface::validate() mengembalikan ValidationResult yang gagal untuk input yang cacat. Metode ini tidak melempar exception untuk pelanggaran well-formedness. Periksa $isValid; jangan membungkus pemanggilan dalam try/catch untuk kasus tersebut.
ExternalComplianceValidatorInterface::isAvailable() harus diperiksa sebelum Anda mengandalkan suatu verdict. Implementasi null mengembalikan “tidak tersedia”. Memperlakukan itu sebagai “tidak patuh” menghasilkan negatif palsu.
EmbeddedPdfObjectInterface::getRawDictionaryBytes() mengembalikan null untuk objek yang diambil dari aliran objek. Gunakan getDictionary() sebagai cadangan. Jangan berasumsi byte mentah pasti ada.
EmbeddingServiceInterface::getDimension() berbeda menurut tier. Kode yang mengalokasikan vektor dengan lebar tetap harus membaca dimensinya saat runtime, bukan menuliskannya secara hard-code.
VectorIndexInterface::build() memerlukan daftar vektor dan id dengan panjang yang sama serta dimensi yang konsisten. Ketidakcocokan memunculkan InvalidArgumentException. Validasi daftar tersebut sebelum Anda membangun indeks.

Kinerja

Biaya inspeksi dan validasi meningkat seiring ukuran dokumen dan jumlah objek. performance_budget sebesar 1500 ms wall dan puncak 64 MB mencakup satu dokumen berukuran sedang. Panggilan veraPDF eksternal menambahkan waktu prosesnya sendiri. Waktu tersebut berada di luar anggaran engine dan sebaiknya dijalankan di luar jalur permintaan. Biaya embedding meningkat seiring panjang teks dan jauh lebih murah jika dilakukan dalam satu batch daripada dalam sebuah loop, terutama pada model GPU. Utamakan batchEmbed(). Pencarian vektor bersifat sublinear terhadap ukuran indeks untuk indeks dalam proses. Profil reproduktibilitasnya adalah structural. Laporan validasi mencatat stempel waktu dan sidik jari lingkungan. Dua eksekusi berbeda pada bidang-bidang tersebut, sementara verdict kepatuhannya tetap identik.

Catatan keamanan

Ekstraksi membaca dokumen yang tidak dibuat oleh engine, sehingga setiap input tidak tepercaya. Inspector dan validator faktur elektronik sama-sama mengurai byte yang dipasok secara eksternal. Validator faktur elektronik harus memblokir payload yang memiliki Document Type Declaration (DOCTYPE), berukuran berlebihan, dan mengandung karakter kendali terlarang sebelum penguraian untuk mencegah serangan external-entity Extensible Markup Language (XML) dan billion-laughs. Penyematan kembali objek yang diimpor menyalin byte dari PDF asing. Objek sumber yang berbahaya dapat membawa konten berbahaya, sehingga penyematan kembali mempertahankan byte tanpa mengeksekusinya. Penegakan PDF/A menghapus JavaScript dan aksi. Pengelola PDF/A menolak JavaScript dan enkripsi karena keduanya dilarang dalam profil dan merupakan vektor penyalahgunaan dalam dokumen arsip berumur panjang. Perlakukan konten yang diinspeksi, objek yang diimpor, dan XML faktur sebagai input bermusuhan secara menyeluruh.

Kesesuaian

Klaim	Standar	Klausul	Bukti
PDF/A-4 melarang JavaScript dan aksi formulir JavaScript; pengelola PDF/A menolak keduanya.	ISO 19005-4	§6.7.1	dikutip berdasarkan klausul (tidak ada dalam korpus)
Setiap objek yang disematkan kembali merupakan objek tidak langsung (indirect object) PDF yang diidentifikasi oleh nomor objek dan generasi.	ISO 32000-2	§7.3.10

ISO 19005-4 dikutip berdasarkan klausul. Standar ini tidak ada dalam korpus sitasi yang dapat diverifikasi, sehingga tidak ada reference_id yang dicatat. Klaim objek tidak langsung dari ISO 32000-2 dipautkan pada glosarium. Kedua klaim diparafrasekan. Engine tidak mereproduksi teks normatif apa pun.

Konteks komersial

Core mendefinisikan dan membekukan kontrak ekstraksi. Kode produksi di balik PdfAManagerInterface, EmbeddingServiceInterface, dan VectorIndexInterface disertakan dalam edisi Pro dan Enterprise, termasuk model embedding CPU dan GPU serta jalur penegakan PDF/A lengkap. Core menyelesaikannya saat runtime dengan class_exists(). Oleh karena itu, engine open-source tidak membawa dependensi komersial, dan application programming interface (API) tidak berubah saat upgrade.

Lihat juga

Kontrak: 41 antarmuka publik — tinjauan Service Provider Interface (SPI) dan tingkat stabilitas.
Kontrak / Dokumen — kontrak dokumen yang menghasilkan carrier PDF/A.
Kontrak / Penandatanganan — pengarsipan bertanda tangan yang berpasangan dengan penegakan PDF/A.
Inspect — implementasi inspector di balik InspectorInterface.
Text — ekstraksi teks yang mengonsumsi objek yang diinspeksi.
Metadata — metadata PDF/A yang dikonfigurasi oleh pengelola.