Pro sürüm

Interop — Derinlemesine başvuru

Bir bakışta

Bu sayfa, NextPDF\Pro\Interop\V1 için sözleşme düzeyinde başvurudur. Modül on dört genel simge içerir: bir dizileştirme sözleşmesi (InteropResultInterface), bir CI bütünlük koruması (SchemaLock), üç üst düzey sonuç DTO’su (ExtractedText, DocumentSegmentation, FormData) ve dokuz destekleyici değer nesnesi ile enum. Her DTO, tek bir analiz sonucunun değişmez, JSON olarak dizileştirilebilir bir görünümüdür. Tel biçimi sürümlenmiş ve kilitlenmiştir; bu yüzeydeki hiçbir şey analizi yeniden çalıştırmaz. Göreve yönelik görünüm yetenek sayfasında bulunur.

Kullanılabilirlik ve lisanslama

Bu yetenek NextPDF Pro (nextpdf/pro) ile birlikte gelir ve Pro katmanı lisans zarfıyla etkinleşir. Bu yetkiye sahip olmayan bir dağıtım, yeteneğin sınıflarını yüklemez. Sürümleri karşılaştırın ve lisans edinin.

Bu modülü çalışma zamanı yetenek bayrağı kapılamaz. Sınıflar, nextpdf/pro kurulu ve lisanslı olduğunda kullanılabilir.

Genel API yüzeyi

Simge	Parametreler	Varsayılan davranış	Döndürür	Fırlattığı veya başarısız olduğu durum	Notlar
`InteropResultInterface`	—	Üst düzey sonuç DTO’ları için sözleşme; `JsonSerializable` arabirimini genişletir	—	Fırlatmaz	`SCHEMA_VERSION`, `'1.0'` dizesidir.
`InteropResultInterface::toArray()`	yok	Her zaman `schema_version` taşıyan, JSON güvenli bir diziye dizileştirir	`array<string, mixed>`	Fırlatmaz	Uygulamalar ayrıca bir `type` ayırıcısı yayar.
`InteropResultInterface::toJson()`	`int $flags = 0`	`toArray()` çıktısını kodlar; `JSON_THROW_ON_ERROR` her zaman OR ile eklenir	`string`	Kodlanamayan veride `JsonException`	`JSON_PRETTY_PRINT` gibi bayraklar geçirin.
`SchemaLock::verify()`	yok	Diskteki V1 `schema.json` dosyasını hash’ler ve kilitlenmiş SHA-256 ile karşılaştırır	`bool`	Fırlatmaz	Şema dosyası eksik, okunamaz veya değiştirilmişse `false`.
`SchemaLock::expectedHash()`	yok	Kilitlenmiş hash’i döndürür	`string`	Fırlatmaz	CI hatası ayıklaması için tanılama çıktısı.
`SchemaLock::actualHash()`	yok	Geçerli şema dosyasının hash’ini döndürür	`string`	Fırlatmaz	G/Ç hatasında `FILE_NOT_FOUND` / `READ_FAILED` gözcü dizeleri hash’in yerini alır.
`BoundingBox`	`float $x`, `float $y`, `float $width`, `float $height`	PDF kullanıcı uzayı noktalarında, orijini sol altta olan değişmez kutu	—	Fırlatmaz	`area()`, `overlaps()`, `toArray()`, `fromArray()`.
`DocumentInfo`	`int $pageCount` artı altı isteğe bağlı meta veri alanı	Değişmez belge meta verisi	—	Fırlatmaz	`fromArray()` her alanı tür açısından korur; eksik alanlar varsayılanlara döner.
`PageInfo`	`int $pageNumber`, `float $width`, `float $height`, `int $rotation = 0`	Değişmez sayfa meta verisi	—	Fırlatmaz	`isLandscape()`; `fromArray()` sayısal dizeleri ve float değerleri dönüştürür.
`ExtractedText`	`list<ExtractedPage> $pages`, `DocumentInfo $documentInfo`, `float $processingTimeMs = 0.0`	Belge geneli metin çıkarma sonucu	—	Yalnızca `toJson()` kaynaklı `JsonException`	`page()`, `totalBlockCount()`, `plainText()`, `fromArray()`.
`ExtractedPage`	`PageInfo $pageInfo`, `list<TextBlock> $textBlocks`	Okuma sırasındaki metin bloklarının sayfa başına kapsayıcısı	—	Fırlatmaz	`plainText()` blok içeriğini tek boşluklarla birleştirir.
`TextBlock`	`string $content`, `BoundingBox $boundingBox`, `int $pageNumber`, `string $fontName = ''`, `float $fontSize = 0.0`	Konumlandırılmış, bitişik metin dizisi	—	Fırlatmaz	Yazı tipi adı ve boyutu en iyi çabayla belirlenir (bloktaki baskın yazı tipi).
`DocumentSegmentation`	`list<Segment> $segments`, `DocumentInfo $documentInfo`, `float $processingTimeMs = 0.0`	Yerleşim duyarlı segmentasyon sonucu	—	Yalnızca `toJson()` kaynaklı `JsonException`	`segmentCount()`, `ofType()`, `onPage()`, `contentSegments()`, `fromArray()`.
`Segment`	`SegmentType $type`, `string $content`, `BoundingBox $boundingBox`, `int $pageNumber`, `float $confidence = 1.0`, `list<Segment> $children = []`	Sınıflandırılmış sayfa bölgesi; alt öğeler özyinelemeli olarak iç içe geçer	—	Fırlatmaz	`isHighConfidence()` eşiği 0.8’dir; `descendantCount()` özyinelemelidir.
`SegmentType`	dize destekli enum	On iki durum, `heading`’den `unknown`’a kadar	—	Fırlatmaz	`isContent()` ve `isStructural()` durumları böler.
`FormData`	`list<FormField> $fields`, `DocumentInfo $documentInfo`, `float $processingTimeMs = 0.0`	Belge geneli form çıkarma sonucu	—	Yalnızca `toJson()` kaynaklı `JsonException`	`field()`, `dataFields()`, `filledCount()`, `toKeyValueMap()`, `fromArray()`.
`FormField`	`string $name`, `FormFieldType $type`, artı altı isteğe bağlı alan	Tek bir çıkarılmış form alanı	—	Fırlatmaz	`isFilled()`, `value !== ''` demektir.
`FormFieldType`	dize destekli enum	Sekiz durum, `text`’ten `button`’a kadar	—	Fırlatmaz	`isDataField()`, `button` ve `signature` için `false`’tur.

interface InteropResultInterface extends JsonSerializable

public const SCHEMA_VERSION = '1.0';

public function toArray(): array;

public function toJson(int $flags = 0): string;

final class SchemaLock

public static function verify(): bool

public static function expectedHash(): string

public static function actualHash(): string

final readonly class ExtractedText implements InteropResultInterface

public function __construct(
    public array $pages,
    public DocumentInfo $documentInfo,
    public float $processingTimeMs = 0.0,
)

public function page(int $pageNumber): ?ExtractedPage

public function totalBlockCount(): int

public function plainText(): string

public static function fromArray(array $data): self

final readonly class DocumentSegmentation implements InteropResultInterface

public function __construct(
    public array $segments,
    public DocumentInfo $documentInfo,
    public float $processingTimeMs = 0.0,
)

public function ofType(SegmentType $type): array

public function onPage(int $pageNumber): array

public function contentSegments(): array

public static function fromArray(array $data): self

final readonly class FormData implements InteropResultInterface

public function __construct(
    public array $fields,
    public DocumentInfo $documentInfo,
    public float $processingTimeMs = 0.0,
)

public function field(string $name): ?FormField

public function dataFields(): array

public function toKeyValueMap(): array

public static function fromArray(array $data): self

Davranış sözleşmesi

Sürümlenmiş zarf. Her üst düzey DTO (ExtractedText, DocumentSegmentation, FormData) InteropResultInterface arabirimini uygular. Onun toArray() çıktısı her zaman schema_version ('1.0') ile bir type ayırıcısı taşır: extracted_text, document_segmentation veya form_data.
JSON kodlama. toJson(), çağıranın bayraklarına OR ile eklenmiş JSON_THROW_ON_ERROR ile json_encode’a devreder. jsonSerialize(), toArray()’e devreder, bu nedenle json_encode($dto) aynı biçimi üretir.
Belirlenimci dizileştirme. Anahtar sırası ve biçim DTO tarafından sabitlenir. Segment::toArray(), boş olduğunda children anahtarını atlar; FormField::toArray(), null olduğunda bounding_box’ı atlar. Tüketiciler her iki anahtarı da isteğe bağlı olarak ele almalıdır.
Gidiş dönüş. Her DTO, kodu çözülmüş bir JSON nesnesini kabul eden statik bir fromArray() sunar. Alanlar bu süreçler arası sınırda tür açısından korunur: eksik veya yanlış türdeki değerler, fırlatmak yerine belgelenen varsayılanlara döner.
Enum yedekleri. Tanınmayan bir type dizesi, Segment::fromArray() içinde SegmentType::Unknown’a ve FormField::fromArray() içinde FormFieldType::Text’e eşlenir.
Koordinatlar. BoundingBox koordinatları, orijini sayfanın sol alt köşesinde olan PDF kullanıcı uzayı birimleridir (nokta, 1/72 inç). Sayfa numaraları baştan sona birden başlar.
Düz metin birleştirmeleri. ExtractedPage::plainText() blok içeriğini tek boşluklarla birleştirir. ExtractedText::plainText() sayfaları boş satırlarla ("\n\n") birleştirir.
Segmentasyon sorguları. ofType(), onPage() ve contentSegments() yalnızca üst düzey segmentleri filtreler ve yeniden dizinlenmiş listeler döndürür. contentSegments(), SegmentType::isContent() değeri true olan türleri seçer: heading, sub_heading, paragraph, table, list, code.
Form sorguları. FormData::dataFields() ve toKeyValueMap(), veri olmayan alan türlerini (button, signature) hariç tutar. filledCount(), değeri boş olmayan bir dize olan alanları sayar.
Şema kilidi. SchemaLock::verify(), paketle birlikte gelen V1 schema.json dosyasını okur, CRLF’yi LF’ye normalleştirir, SHA-256 ile hash’ler ve sabit zamanda kilitlenmiş sabitle karşılaştırır. CI, sessiz şema kaymasını engellemek için bunu kullanır; kilit değeri yalnızca kasıtlı, sürümlenmiş bir şema değişikliğiyle değişir.
Sürümleme politikası. V1 yüzeyi açık bir genel sözleşmedir. Eklemeli değişiklikler şema sürümünü yükseltir; uyumluluğu bozan değişiklikler yeni bir ana sürüm gerektirir.

Uç durumlar ve başarısızlık modları

Bu yüzeyde fırlatan tek üye toJson()’dur: dizi kodlanamadığında, örneğin çıkarılan içerikte geçersiz UTF-8 olduğunda JsonException.
SchemaLock::verify(), şema dosyası eksik, okunamaz veya değiştirilmiş olduğunda false döndürür — asla fırlatmaz. Kaymayı G/Ç hatasından ayırt etmek için expectedHash() ile actualHash()’i karşılaştırın.
fromArray() yedekleri tasarım gereği sessizdir. Yanlış türdeki bir page_number, 1 olur; yanlış türdeki bir confidence, varsayılana döner. Üretilen varsayılanlar kabul edilemez olduğunda yukarı akışta doğrulayın.
Sayısal dize dönüştürmesi asimetriktir. PageInfo::fromArray(), int ve float alanları için sayısal dizeleri kabul eder; Segment ve TextBlock, confidence ve font_size için yalnızca int veya float kabul eder.
BoundingBox::fromArray(), belgelenen dizi biçimine göre dört anahtarın tümünü gerektirir. Onu gömen DTO’lar, sarmalayıcı anahtar yoksa sıfır kutusu (veya FormField için null) koyar.
ExtractedPage::fromArray(), anahtar eksik veya yanlış türde olduğunda 595 × 842 nokta boyutundaki 1. sayfaya ait yedek bir page_info koyar.
FormField::fromArray(), required ve read_only için yalnızca katı boole değerlerini kabul eder; doğru sayılan dizeler ve tam sayılar false’a eşlenir.
Segment alt öğeleri, derinlik sınırı olmadan özyineler. Aşırı derin iç içe geçme yalnızca PHP’nin bellek ve yığın sınırlarıyla sınırlanır.
Bu modülde hiçbir kriptografik anahtar veya imza işlemi gerçekleşmez. SchemaLock, SHA-256’yı yalnızca bir dosya bütünlüğü sağlama toplamı olarak kullanır, bu nedenle FIPS moduna özgü bir davranış yoktur.

Uygunluk

Interop V1, NextPDF’e ait, sürümlenmiş bir tel sözleşmesidir. Harici bir standardı uygulamaz, bu nedenle normatif bir atıf tablosu yoktur. BoundingBox semantiği, üretici Core alt sistemlerinin kullandığı PDF kullanıcı uzayı koordinat modeliyle hizalanır; bu, bir uygunluk testi sonucu değil, yapısal bir hizalama ifadesidir. NextPDF hiçbir sertifikaya sahip değildir ve hiçbir sertifika vermez.

Geliştirme notları

Tüketicilerde schema_version’a göre dallanın. Eklemeli anahtarları uyumlu olarak ele alın; bilinmeyen ana sürümleri açıkça reddedin.
CI’da SchemaLock::verify() çalıştırın. Başarısızlıkta expectedHash() ve actualHash()’i günlüğe kaydedin ve yerinde bir düzenleme değil, kasıtlı, sürümlenmiş bir şema değişikliği zorunlu kılın.
Süreçler arası gidiş dönüşler için ilişkisel dizilerle kod çözün (json_decode($json, true)) ve sonucu eşleşen fromArray()’e verin.
Tüm DTO’lar final ve readonly’dir. Bileşim yoluyla genişletin; yeni görünümleri genel alanlardan türetin.
toKeyValueMap(), yalnızca veri taşıyan alanları düzleştirir. Varlıkları önemli olduğunda signature alanlarını doğrudan FormData::$fields’ten okuyun.
Yeniden kullanım güvenlidir: DTO’lar hiçbir değiştirilebilir durum veya kaynak tutmaz, bu nedenle önbelleğe alınabilir, istekler arasında paylaşılabilir ve tekrar tekrar dizileştirilebilir.

Yayın sınırı

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