Pro edycja

Interop — szczegółowa dokumentacja referencyjna

W skrócie

Ta strona to referencja na poziomie kontraktu dla NextPDF\Pro\Interop\V1. Moduł zawiera czternaście symboli publicznych: jeden kontrakt serializacji (InteropResultInterface), jeden strażnik integralności CI (SchemaLock), trzy nadrzędne DTO wyników (ExtractedText, DocumentSegmentation, FormData) oraz dziewięć pomocniczych obiektów wartości i typów wyliczeniowych. Każde DTO to niemutowalny, serializowalny do JSON widok jednego wyniku analizy. Kształt formatu przesyłania jest wersjonowany i zablokowany; nic na tej powierzchni nie uruchamia ponownie analizy. Widok zorientowany na zadania znajduje się na stronie możliwości.

Dostępność i licencjonowanie

Ta funkcja jest dostarczana w NextPDF Pro (nextpdf/pro) i aktywuje się wraz z kopertą licencyjną w warstwie Pro. Wdrożenie bez tego uprawnienia nie ładuje klas tej funkcji. Porównaj edycje i uzyskaj licencję.

Żadna flaga funkcji w czasie wykonania nie stanowi bramy dla tego modułu. Klasy są dostępne zawsze, gdy nextpdf/pro jest zainstalowany i licencjonowany.

Powierzchnia publicznego API

Symbol	Parametry	Zachowanie domyślne	Zwraca	Zgłasza lub kończy niepowodzeniem	Uwagi
`InteropResultInterface`	—	Kontrakt dla nadrzędnych DTO wyników; rozszerza `JsonSerializable`	—	Nie zgłasza wyjątków	`SCHEMA_VERSION` to łańcuch `'1.0'`.
`InteropResultInterface::toArray()`	brak	Serializuje do bezpiecznej dla JSON tablicy, która zawsze niesie `schema_version`	`array<string, mixed>`	Nie zgłasza wyjątków	Implementacje emitują również dyskryminator `type`.
`InteropResultInterface::toJson()`	`int $flags = 0`	Koduje wynik `toArray()`; `JSON_THROW_ON_ERROR` jest zawsze dołączany operatorem OR	`string`	`JsonException` dla danych niemożliwych do zakodowania	Przekaż flagi takie jak `JSON_PRETTY_PRINT`.
`SchemaLock::verify()`	brak	Haszuje znajdujący się na dysku plik V1 `schema.json` i porównuje go z zablokowanym SHA-256	`bool`	Nie zgłasza wyjątków	`false`, gdy plik schematu jest brakujący, nieczytelny lub zmodyfikowany.
`SchemaLock::expectedHash()`	brak	Zwraca zablokowany hasz	`string`	Nie zgłasza wyjątków	Dane diagnostyczne do triażu niepowodzeń CI.
`SchemaLock::actualHash()`	brak	Zwraca hasz bieżącego pliku schematu	`string`	Nie zgłasza wyjątków	Wartowniki `FILE_NOT_FOUND` / `READ_FAILED` zastępują hasz przy błędzie We/Wy.
`BoundingBox`	`float $x`, `float $y`, `float $width`, `float $height`	Niemutowalny prostokąt w punktach przestrzeni użytkownika PDF, początek w lewym dolnym rogu	—	Nie zgłasza wyjątków	`area()`, `overlaps()`, `toArray()`, `fromArray()`.
`DocumentInfo`	`int $pageCount` oraz sześć opcjonalnych pól metadanych	Niemutowalne metadane dokumentu	—	Nie zgłasza wyjątków	`fromArray()` sprawdza typ każdego pola; brakujące pola przyjmują wartości domyślne.
`PageInfo`	`int $pageNumber`, `float $width`, `float $height`, `int $rotation = 0`	Niemutowalne metadane strony	—	Nie zgłasza wyjątków	`isLandscape()`; `fromArray()` konwertuje łańcuchy numeryczne i liczby zmiennoprzecinkowe.
`ExtractedText`	`list<ExtractedPage> $pages`, `DocumentInfo $documentInfo`, `float $processingTimeMs = 0.0`	Wynik ekstrakcji tekstu z całego dokumentu	—	`JsonException` tylko z `toJson()`	`page()`, `totalBlockCount()`, `plainText()`, `fromArray()`.
`ExtractedPage`	`PageInfo $pageInfo`, `list<TextBlock> $textBlocks`	Kontener bloków tekstu jednej strony w kolejności czytania	—	Nie zgłasza wyjątków	`plainText()` łączy zawartość bloków pojedynczymi spacjami.
`TextBlock`	`string $content`, `BoundingBox $boundingBox`, `int $pageNumber`, `string $fontName = ''`, `float $fontSize = 0.0`	Pozycjonowany ciągły fragment tekstu	—	Nie zgłasza wyjątków	Nazwa i rozmiar czcionki są przybliżeniem (dominująca czcionka w bloku).
`DocumentSegmentation`	`list<Segment> $segments`, `DocumentInfo $documentInfo`, `float $processingTimeMs = 0.0`	Wynik segmentacji uwzględniającej układ	—	`JsonException` tylko z `toJson()`	`segmentCount()`, `ofType()`, `onPage()`, `contentSegments()`, `fromArray()`.
`Segment`	`SegmentType $type`, `string $content`, `BoundingBox $boundingBox`, `int $pageNumber`, `float $confidence = 1.0`, `list<Segment> $children = []`	Sklasyfikowany obszar strony; dzieci zagnieżdżają się rekurencyjnie	—	Nie zgłasza wyjątków	Próg `isHighConfidence()` wynosi 0.8; `descendantCount()` jest rekurencyjny.
`SegmentType`	enum oparty na łańcuchach	Dwanaście przypadków, od `heading` do `unknown`	—	Nie zgłasza wyjątków	`isContent()` i `isStructural()` dzielą przypadki.
`FormData`	`list<FormField> $fields`, `DocumentInfo $documentInfo`, `float $processingTimeMs = 0.0`	Wynik ekstrakcji formularza z całego dokumentu	—	`JsonException` tylko z `toJson()`	`field()`, `dataFields()`, `filledCount()`, `toKeyValueMap()`, `fromArray()`.
`FormField`	`string $name`, `FormFieldType $type`, oraz sześć opcjonalnych pól	Pojedyncze wyodrębnione pole formularza	—	Nie zgłasza wyjątków	`isFilled()` to `value !== ''`.
`FormFieldType`	enum oparty na łańcuchach	Osiem przypadków, od `text` do `button`	—	Nie zgłasza wyjątków	`isDataField()` to `false` dla `button` i `signature`.

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

Kontrakt zachowania

Wersjonowana koperta. Każde nadrzędne DTO (ExtractedText, DocumentSegmentation, FormData) implementuje InteropResultInterface. Wynik jego toArray() zawsze niesie schema_version ('1.0') oraz dyskryminator type: extracted_text, document_segmentation lub form_data.
Kodowanie JSON. toJson() deleguje do json_encode z JSON_THROW_ON_ERROR dołączonym operatorem OR do flag wywołującego. jsonSerialize() deleguje do toArray(), więc json_encode($dto) daje ten sam kształt.
Deterministyczna serializacja. Kolejność i kształt kluczy są ustalone przez DTO. Segment::toArray() pomija klucz children, gdy jest pusty; FormField::toArray() pomija bounding_box, gdy ma wartość null. Konsumenci muszą traktować oba klucze jako opcjonalne.
Podróż w obie strony. Każde DTO udostępnia statyczną fromArray(), która przyjmuje zdekodowany obiekt JSON. Pola są sprawdzane pod względem typu na tej granicy międzyprocesowej: brakujące lub błędnie otypowane wartości przyjmują udokumentowane wartości domyślne zamiast zgłaszać wyjątek.
Wartości zastępcze enum. Nierozpoznany łańcuch type mapuje się na SegmentType::Unknown w Segment::fromArray() oraz na FormFieldType::Text w FormField::fromArray().
Współrzędne. Współrzędne BoundingBox to jednostki przestrzeni użytkownika PDF (punkty, 1/72 cala) z początkiem w lewym dolnym rogu strony. Numery stron są liczone od jedynki w całym module.
Łączenie zwykłego tekstu. ExtractedPage::plainText() łączy zawartość bloków pojedynczymi spacjami. ExtractedText::plainText() łączy strony pustymi wierszami ("\n\n").
Zapytania o segmentację. ofType(), onPage() i contentSegments() filtrują wyłącznie segmenty nadrzędne i zwracają listy z przeindeksowaniem. contentSegments() wybiera typy, dla których SegmentType::isContent() to true: heading, sub_heading, paragraph, table, list, code.
Zapytania o formularze. FormData::dataFields() i toKeyValueMap() wykluczają typy pól niebędące danymi (button, signature). filledCount() liczy pola, których wartość jest niepustym łańcuchem.
Blokada schematu. SchemaLock::verify() odczytuje plik V1 schema.json dostarczany z pakietem, normalizuje CRLF do LF, haszuje algorytmem SHA-256 i porównuje z zablokowaną stałą w czasie stałym. CI używa tego do blokowania cichego dryfu schematu; wartość blokady zmienia się wyłącznie przy celowej, wersjonowanej zmianie schematu.
Zasady wersjonowania. Powierzchnia V1 to jawny kontrakt publiczny. Zmiany addytywne podnoszą wersję schematu; zmiany łamiące zgodność wymagają nowej wersji głównej.

Przypadki brzegowe i tryby awarii

Jedynym elementem tej powierzchni, który zgłasza wyjątek, jest toJson(): JsonException, gdy tablica nie jest możliwa do zakodowania, na przykład przy nieprawidłowym UTF-8 w wyodrębnionej zawartości.
SchemaLock::verify() zwraca false — nigdy nie zgłasza wyjątku — gdy plik schematu jest brakujący, nieczytelny lub zmodyfikowany. Porównaj expectedHash() z actualHash(), aby odróżnić dryf od błędu We/Wy.
Wartości zastępcze fromArray() są celowo ciche. Błędnie otypowany page_number staje się 1; błędnie otypowany confidence przyjmuje wartość domyślną. Waliduj wcześniej w potoku, gdy sfabrykowane wartości domyślne są nie do przyjęcia.
Konwersja łańcuchów numerycznych jest asymetryczna. PageInfo::fromArray() akceptuje łańcuchy numeryczne dla swoich pól int i float; Segment i TextBlock akceptują wyłącznie int lub float dla confidence i font_size.
BoundingBox::fromArray() wymaga wszystkich czterech kluczy zgodnie z udokumentowanym kształtem tablicy. Osadzające go DTO podstawiają zerowy prostokąt (lub null dla FormField), gdy klucz opakowujący jest nieobecny.
ExtractedPage::fromArray() podstawia zastępcze page_info dla strony 1 o wymiarach 595 × 842 punktów, gdy klucz jest brakujący lub błędnie otypowany.
FormField::fromArray() akceptuje wyłącznie ścisłe wartości logiczne dla required i read_only; prawdziwościowe łańcuchy i liczby całkowite mapują się na false.
Dzieci Segment rekurują bez limitu głębokości. Skrajnie głębokie zagnieżdżenie jest ograniczone wyłącznie limitami pamięci i stosu PHP.
W tym module nie zachodzi żadna operacja na kluczu kryptograficznym ani podpisie. SchemaLock używa SHA-256 wyłącznie jako sumy kontrolnej integralności pliku, więc nie występuje zachowanie specyficzne dla trybu FIPS.

Zgodność

Interop V1 to wersjonowany kontrakt formatu przesyłania należący do NextPDF. Nie implementuje zewnętrznego standardu, więc nie ma tabeli odniesień normatywnych. Semantyka BoundingBox jest zgodna z modelem współrzędnych przestrzeni użytkownika PDF używanym przez wytwarzające ją podsystemy Core; jest to stwierdzenie o zgodności strukturalnej, a nie wynik testu zgodności. NextPDF nie posiada żadnej certyfikacji ani żadnej nie udziela.

Uwagi dla programistów

Rozgałęziaj logikę w konsumentach na podstawie schema_version. Traktuj klucze addytywne jako zgodne; jawnie odrzucaj nieznane wersje główne.
Uruchamiaj SchemaLock::verify() w CI. Przy niepowodzeniu rejestruj expectedHash() i actualHash() oraz wymagaj celowej, wersjonowanej zmiany schematu, nigdy edycji w miejscu.
Dla podróży w obie strony między procesami dekoduj z tablicami asocjacyjnymi (json_decode($json, true)) i przekazuj wynik do odpowiedniej fromArray().
Wszystkie DTO są final i readonly. Rozszerzaj przez kompozycję; wyprowadzaj nowe widoki z pól publicznych.
toKeyValueMap() spłaszcza wyłącznie pola przenoszące dane. Odczytuj pola signature bezpośrednio z FormData::$fields, gdy ich obecność ma znaczenie.
Ponowne użycie jest bezpieczne: DTO nie przechowują stanu mutowalnego ani zasobów, więc mogą być buforowane, współdzielone między żądaniami i wielokrotnie serializowane.

Granica publikacji

Ta strona dokumentuje wyłącznie zachowanie obserwowalne z zewnątrz oraz wspieraną powierzchnię publicznego API. Wewnętrzne ścieżki przestrzeni nazw, klasy pomocnicze, tabele mechanizmów, nazwy plików runbook oraz prefiksy zgłoszeń są poza zakresem.