Birlikte çalışabilirlik

Bir bakışta

NextPDF Pro, PDF analiz çıktısını — belge bilgisi, sayfalar, metin blokları, bölümleme ve form verisi — harici sistemler ve araçlar tarafından tüketilmek üzere kararlı, şema kilitli bir JSON biçimine serileştiren sürümlü bir sonuç veri aktarım nesnesi (DTO) kümesi sağlar.

Kullanılabilirlik ve lisanslama

Bu yetenek NextPDF Pro (nextpdf/pro) içinde sunulur ve Pro katmanı lisans zarfıyla etkinleşir. Bu yetkiye sahip olmayan bir dağıtım, yeteneğin sınıflarını yüklemez. Interop, Pro sürümünün bir parçasıdır; ayrı bir özellik başına lisans bayrağı yoktur. Sürümleri karşılaştırın ve lisans edinin.

Kurulum

composer require nextpdf/pro:^3

Kavramsal genel bakış

PDF işleme çıktısı bir süreç veya hizmet sınırını geçtiğinde, alıcının kararlı bir sözleşmeye ihtiyacı vardır. Interop V1 yüzeyi bunu sağlar:

• InteropResultInterface — her sonuç DTO’su bunu uygular. Her biri, her zaman bir schema_version anahtarı taşıyan JSON güvenli bir diziye ve bir JSON dizesine serileştirilir.
• Sonuç DTO’ları — DocumentInfo, PageInfo, BoundingBox, ExtractedText / ExtractedPage / TextBlock, DocumentSegmentation / Segment ve FormData / FormField. Her biri, bir analiz sonucunun değişmez bir görünümüdür.
• SchemaLock — bir CI koruması. Dondurulmuş şemanın SHA-256 değerini tutar ve şema dosyası, karşılık gelen bir sürüm artışı olmadan değişirse derlemeyi başarısız kılar; böylece iletişim sözleşmesi sessizce kayamaz.

Interop yüzeyi açıkça sürümlüdür (SCHEMA_VERSION). Onu bir genel API sözleşmesi olarak değerlendirin: eklemeli değişiklikler şemayı artırır; bozucu değişiklikler yeni bir ana sürüm gerektirir.

Neden bu şekilde çalışır

Serileştirme biçimi, bir uygulama ayrıntısı değil, genel bir API sözleşmesi olarak değerlendirilir. Her DTO bir schema_version anahtarı taşır; böylece tüketiciler tahmin etmek yerine aldıkları biçime göre dallanır. SchemaLock, dondurulmuş şemanın SHA-256 değerini CI’da sabitler; böylece biçim bir sürüm artışı olmadan kayamaz. Harici sistemlerin JSON’a karşı güvenle derleme yapmasını sağlayan şey budur: sözleşme yalnızca sürüm değiştiğinde değişir. Çıktı taşınabilir kalır — sahip olduğunuz belgelenmiş, sürümlü veriler; altınızda kayan bir biçim değil.

Tasarım arka planı: Açık çekirdek, bağımlılık yok.

API yüzeyi

Sınıf	Sorumluluk
InteropResultInterface	Ortak serileştirme sözleşmesi.
DocumentInfo, PageInfo, BoundingBox	Ortak belge/sayfa DTO’ları.
ExtractedText, ExtractedPage, TextBlock	Metin çıkarımı DTO’ları.
DocumentSegmentation, Segment	Belge bölümleme DTO’ları.
FormData, FormField	Form verisi DTO’ları.
SchemaLock	CI şema kayması koruması.

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

$json = $result->toJson(JSON_PRETTY_PRINT);
$array = $result->toArray(); // includes 'schema_version'

Kod örneği — Üretim

use NextPDF\Pro\Interop\V1\SchemaLock;

if (! SchemaLock::verify()) {
    throw new RuntimeException('Interop schema drift detected — version bump required.');
}
$payload = $result->toArray();
$httpClient->postJson($endpoint, $payload);

Uç durumlar ve dikkat edilmesi gerekenler

• toArray() her zaman schema_version içerir; aşağı akış tüketicileri onun üzerinde dallanmalıdır.
• SchemaLock::verify(), şema dosyası eksik veya değiştirilmişse false döndürür.
• DTO’lar salt okunur görünümlerdir; analizi yeniden çalıştırmazlar.

Performans

Serileştirme, sonuç grafiğinin boyutunda doğrusaldır.

Güvenlik notları

DTO’lar yalnızca doldurduğunuz analiz çıktısını taşır. Serileştirme sırasında hiçbir dosya sistemi veya ağ giriş/çıkışı gerçekleşmez.

Uygunluk

Interop, NextPDF’e ait sürümlü bir şema tanımlar; harici bir standart uygulamaz.

Davranış sözleşmesi

• Her sonuç DTO’su InteropResultInterface arabirimini uygular ve her zaman bir schema_version anahtarı taşıyan JSON güvenli bir diziye ve bir JSON dizesine serileştirilir.
• Sonuç DTO’ları (DocumentInfo, PageInfo, BoundingBox, ExtractedText/ExtractedPage/TextBlock, DocumentSegmentation/Segment, FormData/FormField) değişmez salt okunur görünümlerdir; analizi yeniden çalıştırmazlar.
• SchemaLock::verify(), dondurulmuş şemanın SHA-256 değerini tutar ve şema dosyası eksik veya değiştirilmişse false döndürür; böylece iletişim sözleşmesi sessizce kayamaz.
• Yüzey açıkça sürümlüdür (SCHEMA_VERSION): eklemeli değişiklikler şemayı artırır; bozucu değişiklikler yeni bir ana sürüm gerektirir.
• Serileştirme sırasında hiçbir dosya sistemi veya ağ giriş/çıkışı gerçekleşmez.

Enterprise sınır notu

Enterprise, Interop davranışını değiştirmez. Enterprise, ayrı olarak belgelenen üst katman özellikleri ekler; bunlar sürümlü sonuç DTO’larını kullanmak için gerekli değildir.

Core geri dönüşü / alternatifi

Şema kilitli, sürümlü sonuç DTO’ları için hiçbir Core eşdeğeri yoktur. Bu bir Pro eklentisidir.

Yayın sınırı

Bu sayfa yalnızca dışarıdan gözlemlenebilen davranışı ve desteklenen genel API yüzeyini belgeler. İç ad alanı yolları, yardımcı sınıflar, mekanizma tabloları, runbook dosya adları ve bilet önekleri kapsam dışıdır.

Ayrıca bkz.

• Extraction — metin ve bölüm sonuçları üretir.
• Form — form verisi sonuçları üretir.
• Interop — Derinlemesine başvuru — tam DTO alan başvurusu.