Interoperacyjność

W skrócie

NextPDF Pro dostarcza wersjonowany zestaw obiektów transferu danych (DTO) wyników, które serializują wyjście analizy PDF — informacje o dokumencie, strony, bloki tekstu, segmentację oraz dane formularza — do stabilnego, zablokowanego schematem kształtu JSON na potrzeby konsumpcji przez systemy i narzędzia zewnętrzne.

Dostępność i licencjonowanie

Ta funkcja jest dostarczana w NextPDF Pro (nextpdf/pro) i aktywuje się wraz z kopertą licencyjną poziomu Pro. Wdrożenie bez tego uprawnienia nie ładuje klas tej funkcji. Interop jest częścią edycji Pro; nie ma osobnej flagi licencyjnej dla poszczególnych funkcji. Porównaj edycje i uzyskaj licencję.

Instalacja

composer require nextpdf/pro:^3

Przegląd koncepcyjny

Gdy wyjście przetwarzania PDF przekracza granicę procesu lub usługi, odbiorca potrzebuje stabilnego kontraktu. Powierzchnia Interop V1 to zapewnia:

• InteropResultInterface — implementuje go każde DTO wyniku. Każde serializuje się do tablicy bezpiecznej dla JSON, która zawsze niesie klucz schema_version, oraz do ciągu JSON.
• DTO wyników — DocumentInfo, PageInfo, BoundingBox, ExtractedText / ExtractedPage / TextBlock, DocumentSegmentation / Segment oraz FormData / FormField. Każde jest niezmienialnym widokiem jednego wyniku analizy.
• SchemaLock — strażnik CI. Przechowuje SHA-256 zamrożonego schematu i zawodzi kompilację, jeśli plik schematu zmieni się bez odpowiadającego podbicia wersji, dzięki czemu kontrakt sieciowy nie może po cichu dryfować.

Powierzchnia Interop jest jawnie wersjonowana (SCHEMA_VERSION). Traktuj ją jak publiczny kontrakt API: zmiany addytywne podbijają schemat; zmiany łamiące wymagają nowej wersji głównej.

Dlaczego działa to w ten sposób

Kształt serializacji jest traktowany jak publiczny kontrakt API, a nie szczegół implementacji. Każde DTO niesie klucz schema_version, więc konsumenci rozgałęziają się na otrzymanym kształcie, zamiast zgadywać. SchemaLock przypina SHA-256 zamrożonego schematu w CI, dzięki czemu format nie może dryfować bez podbicia wersji. To właśnie pozwala systemom zewnętrznym bezpiecznie budować w oparciu o JSON: kontrakt przesuwa się tylko wtedy, gdy przesuwa się wersja. Wyjście pozostaje przenośne — udokumentowane, wersjonowane dane, które są Twoje, a nie kształt zmieniający się pod Tobą.

Tło projektowe: Open core, bez uwięzienia u dostawcy.

Powierzchnia API

Klasa	Odpowiedzialność
InteropResultInterface	Wspólny kontrakt serializacji.
DocumentInfo, PageInfo, BoundingBox	Wspólne DTO dokumentu/strony.
ExtractedText, ExtractedPage, TextBlock	DTO ekstrakcji tekstu.
DocumentSegmentation, Segment	DTO segmentacji dokumentu.
FormData, FormField	DTO danych formularza.
SchemaLock	Strażnik dryfu schematu w CI.

Przykład kodu — Szybki start

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

Przykład kodu — Produkcja

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);

Przypadki brzegowe i pułapki

• toArray() zawsze zawiera schema_version; konsumenci w dół powinni się na nim rozgałęziać.
• SchemaLock::verify() zwraca false, jeśli plik schematu jest brakujący lub zmodyfikowany.
• DTO to widoki tylko do odczytu; nie uruchamiają ponownie analizy.

Wydajność

Serializacja jest liniowa względem rozmiaru grafu wyniku.

Uwagi dotyczące bezpieczeństwa

DTO niosą wyłącznie wyjście analizy, którym je wypełnisz. Podczas serializacji nie zachodzi żadne wejście/wyjście systemu plików ani sieci.

Konformancja

Interop definiuje wersjonowany schemat należący do NextPDF; nie implementuje zewnętrznego standardu.

Kontrakt zachowania

• Każde DTO wyniku implementuje InteropResultInterface i serializuje się do tablicy bezpiecznej dla JSON, która zawsze niesie klucz schema_version, oraz do ciągu JSON.
• DTO wyników (DocumentInfo, PageInfo, BoundingBox, ExtractedText/ExtractedPage/TextBlock, DocumentSegmentation/Segment, FormData/FormField) to niezmienialne widoki tylko do odczytu; nie uruchamiają ponownie analizy.
• SchemaLock::verify() przechowuje SHA-256 zamrożonego schematu i zwraca false, jeśli plik schematu jest brakujący lub zmodyfikowany, dzięki czemu kontrakt sieciowy nie może po cichu dryfować.
• Powierzchnia jest jawnie wersjonowana (SCHEMA_VERSION): zmiany addytywne podbijają schemat; zmiany łamiące wymagają nowej wersji głównej.
• Podczas serializacji nie zachodzi żadne wejście/wyjście systemu plików ani sieci.

Nota o granicy Enterprise

Enterprise nie zmienia zachowania Interop. Enterprise dodaje funkcje wyższego poziomu udokumentowane osobno; nie są one wymagane do korzystania z wersjonowanych DTO wyników.

Rozwiązanie awaryjne / alternatywa w Core

Nie istnieje odpowiednik w Core dla zablokowanych schematem, wersjonowanych DTO wyników. To dodatek Pro.

Granica publikacji

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

Zobacz też

• Extraction — wytwarza wyniki tekstu i segmentów.
• Form — wytwarza wyniki danych formularza.
• Interop — Szczegółowa dokumentacja — pełna referencja pól DTO.