Contracts / Extraction

Bir bakışta

Çıkarım alanı, Taşınabilir Belge Biçimi (PDF) dosyalarını okumak, doğrulamak ve ardından içeriklerini yapılandırılmış verilere dönüştürmek için kullandığınız sözleşmeleri tanımlar. İnceleyiciyi, uyumluluk doğrulayıcılarını, PDF/A yöneticisini, içe aktarılan nesne sözleşmelerini, gömme ve vektör dizini sözleşmelerini ve e-fatura doğrulayıcısının alt ad alanını kapsar.

Kurulum

composer require nextpdf/core:^3

Kavramsal genel bakış

InspectorInterface ham PDF baytlarını okur ve yapılandırılmış bir InspectResult döndürür. Sonuç, dosyadaki nesneleri listeler. Bu sözleşmeyi, motor tarafından yazılmamış bir PDF’i okuyan herhangi bir araç için kullanın.

ExternalComplianceValidatorInterface motoru veraPDF gibi harici bir denetleyiciye bağlar. Denetleyici, PDF/A ve PDF/Evrensel Erişilebilirlik (PDF/UA) sınamalarını çalıştırır. Hiçbir denetleyici yapılandırılmadığında boş uygulama bir “kullanılamıyor” sonucu döndürür. veraPDF bulunmayan bir site yine de çalışır. ProfileValidatorInterface çalışma zamanı ortamını, gerekli ve önerilen uzantılar dâhil olmak üzere bir dağıtım profiline göre denetler. Türü belirli olan bir karar döndürür.

PdfAManagerInterface, yazıcı bir PDF/A dosyası oluştururken onu spesifikasyona uygun tutar. JavaScript’i, JavaScript form eylemlerini ve yerleşik şifrelemeyi engeller. PDF/A üçünü de yasaklar. Ayrıca her yazı tipinin gömülü olduğunu denetler, spesifikasyona uygun meta veriyi ayarlar ve gerekli nesneleri katalogdan önce yazar. Somut sınıf, Pro sürümünde gönderilir. Çekirdek onu class_exists() ile bulur ve sözleşmeye uyarlar. Açık kaynaklı motorun hiçbir ücretli bağımlılığı yoktur.

İki sözleşme içe aktarılan nesneleri kapsar: ImportedFormObjectInterface ve EmbeddedPdfObjectInterface. Bunlar, motorun yeniden gömebilmesi için var olan bir PDF’den okunan nesnelere türü belirli erişim sağlar. Kayıpsız yol, ham sözlük baytlarını korur. Yedek yol, nesne akışlarından alınan nesneler için ayrıştırılmış bir sözlük dizisi sağlar. Yeniden gömülen her nesne bir PDF dolaylı nesnesidir. ISO 32000-2 §7.3.10 tarafından tanımlandığı şekilde, onu bir nesne numarası ve bir oluşturma numarası tanımlar.

Gömme sözleşmeleri aramayı destekler. EmbeddingServiceInterface metni yoğun bir vektöre dönüştürür ve model boyutunu ve adını bildirir; böylece çağıranlar çalışma zamanında uyum sağlayabilir. Pro sürümü merkezi işlem birimi (CPU) tabanlı bir model çalıştırır. Enterprise sürümü grafik işlem birimi (GPU) tabanlı bir model çalıştırır. VectorIndexInterface en yakın komşu dizini oluşturur ve bu dizinde arama yapar. Bu, çekirdek kullanımına yönelik küçük bir işlem içi dizindir. Daha büyük ölçekli arama, yalnızca Enterprise’a özgü bir sözleşmede kalır.

Söz konusu EInvoice grubu, katmanlar arası e-fatura denetleyicisini barındırır. ValidatorInterface bir Sektörler Arası Fatura (CII) veya Evrensel İş Dili (UBL) yükü üzerinde ön kontroller çalıştırır. SchematronRunnerInterface iş kuralı geçişini yürütür. ValidationResult bulguları ve kural ihlallerini toplar. Denetleyici, hatalı girdiyi bir istisna ile değil, bir sonuçla reddetmelidir. Ayrıca, Belge Türü Bildirimi (DOCTYPE) içeren yüklere ve aşırı büyük yüklere karşı koruma sağlamalıdır.

API yüzeyi

Tür	Çeşit	Temel üyeler	Kararlılık	Sürümden beri
`InspectorInterface`	arayüz	`inspect(string, InspectConfig): InspectResult`	deneysel	2.2.0
`ExternalComplianceValidatorInterface`	arayüz	`validate(string, ComplianceFlavour)`, `isAvailable()`	deneysel	2.4.0
`ProfileValidatorInterface`	arayüz	`validate(DeploymentProfile): DeploymentProfileResult`	deneysel	2.4.0
`PdfAManagerInterface`	arayüz	`validateNoJavaScript()`, `validateFont()`, `validateNoEncryption()`, `applyOutputProfile()`, `writeRequiredObjects()`	kararlı	1.10.0
`ImportedFormObjectInterface`	arayüz	`getWidth()`, `getHeight()`, `getEmbeddedObjects()`, `getResourcesDict()`, `getMediaBox()`, `getContentStream()`	kararlı	1.8.0
`EmbeddedPdfObjectInterface`	arayüz	`getRawDictionaryBytes()`, `getRawStreamData()`, `getDictionary()`	kararlı	1.8.0
`EmbeddingServiceInterface`	arayüz	`embed()`, `batchEmbed()`, `getDimension()`, `getModelName()`	deneysel	2.1.0
`VectorIndexInterface`	arayüz	`build()`, `search()`, `delete()`, `count()`	deneysel	2.1.0
`EInvoice\ValidatorInterface`	arayüz	`validate(string, ValidatorContext): ValidationResult`	deneysel	5.1.0
`EInvoice\ValidationResult`	final readonly sınıf	`$isValid`, `getErrors()`, `getWarnings()`, `fail()`	deneysel	5.1.0

Söz konusu EInvoice ad alanı ayrıca SchematronRunnerInterface, ProfileInterface, ValidationFinding, RuleViolation ile ProfileType, RuleSeverity ve ValidationFindingLevel enum’larını yayımlar.

Kod örneği — hızlı başlangıç

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

Bu işlev sözleşmeye bağlıdır. Herhangi bir inceleyici uygulaması bu bağımlılığı karşılayabilir.

Kod örneği — üretim

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

Hizmet, bir doğrulayıcının mevcut olduğunu varsaymak yerine, doğrulayıcının kullanılamadığı durumu açıkça ele alır.

Uç durumlar ve tuzaklar

EInvoice\ValidatorInterface::validate() hatalı biçimlendirilmiş girdi için başarısız bir ValidationResult döndürür. İyi biçimlilik ihlalleri için istisna fırlatmaz. $isValid değerini denetleyin; bu durum için çağrıyı bir try/catch içine sarmayın.
ExternalComplianceValidatorInterface::isAvailable(), bir karara güvenmeden önce denetlenmelidir. Boş uygulama “kullanılamıyor” döndürür. Bunu “uyumlu değil” olarak ele almak yanlış negatif sonuçlar üretir.
EmbeddedPdfObjectInterface::getRawDictionaryBytes() bir nesne akışından alınan nesneler için null döndürür. Yedek olarak getDictionary() yöntemini kullanın. Ham baytların var olduğunu varsaymayın.
EmbeddingServiceInterface::getDimension() katmana göre değişir. Sabit genişlikli bir vektör ayıran kod, boyutu sabit kodlamak yerine çalışma zamanında okumalıdır.
VectorIndexInterface::build() vektör ve kimlik listelerinin eşit uzunlukta ve tutarlı boyutlara sahip olmasını gerektirir. Herhangi bir uyumsuzluk InvalidArgumentException fırlatır. Dizini oluşturmadan önce listeleri doğrulayın.

Performans

İnceleme ve doğrulama maliyeti belge boyutu ve nesne sayısıyla ölçeklenir. 1500 ms duvar saati süresi ve 64 MB tepe değerindeki performance_budget değeri, orta büyüklükte bir belgeyi kapsar. Harici bir veraPDF çağrısı, kendi işlem süresini ekler. Bu süre, motor bütçesinin dışındadır ve istek yolundan ayrı çalışmalıdır. Gömme maliyeti metin uzunluğuyla ölçeklenir; özellikle bir GPU modelinde toplu işlem, döngüye göre çok daha ucuzdur. batchEmbed() yöntemini tercih edin. Vektör araması, işlem içi dizin için dizin boyutuna göre alt doğrusaldır. Yeniden üretilebilirlik profili structural değeridir. Bir doğrulama raporu, bir zaman damgası ve bir ortam parmak izi kaydeder. İki çalıştırma bu alanlarda farklılık gösterse de uyumluluk kararı aynı kalır.

Güvenlik notları

Çıkarım, motorun oluşturmadığı belgeleri okur; bu nedenle her girdi güvenilmezdir. Hem inceleyici hem de e-fatura doğrulayıcısı harici olarak sağlanan baytları ayrıştırır. E-fatura doğrulayıcısı, Genişletilebilir İşaretleme Dili (XML) harici varlık ve billion-laughs saldırılarını önlemek için Belge Türü Bildirimi (DOCTYPE) içeren, aşırı büyük olan veya yasaklanmış denetim karakterleri içeren yükleri ayrıştırmadan önce engellemelidir. İçe aktarılan nesnenin yeniden gömülmesi, harici bir PDF’den baytları kopyalar. Kötü amaçlı bir kaynak nesne düşmanca içerik taşıyabilir; bu nedenle yeniden gömme işlemi baytları yürütmeden korur. PDF/A uygulaması, JavaScript’i ve eylemleri kaldırır. PDF/A yöneticisi, JavaScript ve şifrelemeyi reddeder; çünkü ikisi de profilde yasaktır ve ikisi de uzun ömürlü bir arşiv belgesinde kötüye kullanım vektörüdür. İncelenen içeriği, içe aktarılan nesneleri ve fatura XML’ini baştan sona düşmanca girdi olarak ele alın.

Uygunluk

İddia	Standart	Madde	Kanıt
PDF/A-4, JavaScript’i ve JavaScript form eylemlerini yasaklar; PDF/A yöneticisi her ikisini de reddeder.	ISO 19005-4	§6.7.1	maddeye göre alıntılanmış (corpus’ta değil)
Yeniden gömülen her nesne, nesne numarası ve oluşturma numarasıyla tanımlanan bir PDF dolaylı nesnesidir.	ISO 32000-2	§7.3.10

ISO 19005-4 madde düzeyinde kaynak gösterilmiştir. Doğrulanabilir alıntı corpus’ta yer almaz; bu nedenle hiçbir reference_id kaydedilmez. ISO 32000-2 dolaylı nesne iddiası sözlük kaydına sabitlenmiştir. Her iki iddia da başka sözcüklerle ifade edilmiştir. Motor hiçbir normatif metni yeniden üretmez.

Ticari bağlam

Çekirdek, çıkarım sözleşmelerini tanımlar ve dondurur. PdfAManagerInterface, EmbeddingServiceInterface ve VectorIndexInterface arkasındaki üretim kodu, CPU ve GPU gömme modelleri ile tam PDF/A uygulama yolu dâhil olmak üzere Pro ve Enterprise sürümlerinde gönderilir. Çekirdek, bunları çalışma zamanında class_exists() ile çözer. Açık kaynaklı motor bu nedenle hiçbir ticari bağımlılık taşımaz ve uygulama programlama arayüzü (API), yükseltme sırasında değişmez.

Ayrıca bakınız

Sözleşmeler: 41 genel arayüz — Hizmet Sağlayıcı Arayüzü (SPI) genel bakışı ve kararlılık katmanları.
Contracts / Document — PDF/A taşıyıcısını üreten belge sözleşmeleri.
Contracts / Signing — PDF/A uygulamasıyla eşleşen imzalı arşivleme.
Inspect — InspectorInterface arkasındaki inceleyici uygulaması.
Text — incelenen nesneleri kullanan metin çıkarımı.
Metadata — yönetici tarafından yapılandırılan PDF/A meta verisi.