Pro edycja

Document — szczegółowa dokumentacja referencyjna

W skrócie

Moduł Document udostępnia trzy prymitywy montażu Pro: podział według zakresów stron, scalanie wielu dokumentów oraz budowę słownika PDF Portfolio (Collection). PdfSplitter wyodrębnia zakresy stron do samodzielnych, strukturalnie zgodnych plików PDF oraz scala całe dokumenty w jeden plik z przenumerowaniem. PdfPortfolio buduje słownik Collection, który prezentuje osadzone pliki wraz z sortowalnymi kolumnami schematu. Każdy punkt wejścia ogranicza rozmiar wejścia i liczbę obiektów względem wrogiego wejścia.

Dostępność i licencjonowanie

Ta funkcjonalność 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 funkcjonalności. Porównaj edycje i uzyskaj licencję.

Powierzchnia publicznego API

Wszystkie typy modułu znajdują się w przestrzeni nazw NextPDF\Pro\Document. PageRange i MergeResult to obiekty wartości z Core, z NextPDF\Document.

Symbol	Parametry	Zachowanie domyślne	Zwraca	Zgłasza lub kończy się błędem	Uwagi
`PdfSplitter::split()`	`string $pdfData`, `list<PageRange> $ranges`, `int $maxBytes = 100_000_000`, `int $maxRanges = 1000`	Buduje jeden samodzielny segment PDF na zakres	`SplitResult`	`InvalidArgumentException` przy braku nagłówka `%PDF`; `OverflowException` przy przekroczeniu limitu rozmiaru, liczby zakresów lub domknięcia	Zabezpieczenia działają przed jakimkolwiek parsowaniem
`PdfSplitter::splitEvery()`	`string $pdfData`, `int $pagesPerSegment`	Wyprowadza spójne zakresy N-stronicowe; ostatni segment może być krótszy	`SplitResult`	`InvalidArgumentException`, gdy `$pagesPerSegment < 1` lub brakuje nagłówka	Deleguje do `split()` z domyślnymi limitami
`PdfSplitter::extractPages()`	`string $pdfData`, `PageRange $range`	Zwraca jeden zakres jako samodzielne bajty PDF	`string`	`InvalidArgumentException` przy braku nagłówka; `OverflowException` przy przekroczeniu limitu domknięcia	Ta ścieżka nie ma parametrów limitów
`PdfSplitter::mergeDocuments()`	`list<string> $pdfs`, `int $maxInputs = 100`, `int $maxBytesEach = 100_000_000`	Scala wejścia w kolejności w jeden przenumerowany PDF	`MergeResult`	`InvalidArgumentException` przy pustej liście lub wejściu niebędącym PDF; `OverflowException` przy przekroczeniu limitu liczby, rozmiaru pojedynczego wejścia lub domknięcia	Od 3.1.0; najwyższa wersja wejścia ustala nagłówek wyjścia
`SplitResult`	readonly `$segments`, `$ranges`, `$totalPages`	Niesie surowe bajty segmentów oraz metadane źródła	—	—	Obiekt wartości `final readonly`
`SplitResult::count()`	—	Zlicza wytworzone segmenty	`int`	—	—
`SplitResult::segment()`	`int $index`	Zwraca bajty jednego segmentu	`string`	`OutOfRangeException` przy indeksie poza zakresem	Indeks liczony od zera
`PdfPortfolio::__construct()`	`string $viewMode = 'tile'`	Sprawdza tryb widoku przy konstrukcji	—	`InvalidArgumentException` dla trybu innego niż `tile`, `detail`, `hidden`	—
`PdfPortfolio::addSchema()`	`PortfolioField $field`	Dołącza kolumnę schematu	`self`	—	Płynne (fluent)
`PdfPortfolio::addEntry()`	`PortfolioEntry $entry`	Dołącza wpis pliku	`self`	—	Płynne (fluent)
`PdfPortfolio::getSchema()`	—	Zwraca zgromadzone pola schematu	`list<PortfolioField>`	—	—
`PdfPortfolio::getEntries()`	—	Zwraca zgromadzone wpisy plików	`list<PortfolioEntry>`	—	—
`PdfPortfolio::count()`	—	Zlicza wpisy plików	`int`	—	—
`PdfPortfolio::generateCollectionDictionary()`	—	Emituje łańcuch słownika Collection	`string`	—	Bloki schematu i sortowania pojawiają się tylko wtedy, gdy istnieją pola
`PortfolioEntry`	`$filename`, `$data`, `$description = ''`, `$mimeType = 'application/octet-stream'`, `$customFields = []`	Niezmienny obiekt wartości wpisu pliku	—	—	`size()` zwraca długość danych w bajtach
`PortfolioField`	`$name`, `PortfolioFieldType $type`, `$displayName = ''`, `$order = 0`, `$visible = true`	Niezmienny obiekt wartości kolumny schematu	—	—	`effectiveDisplayName()` przechodzi w rezerwie do `$name`
`PortfolioFieldType`	Enum łańcuchowy: `Text`, `Date`, `Number`, `FileName`, `Description`, `Size`, `ModDate`, `CreationDate`	Mapuje każdy przypadek na PDF-owy `/Subtype` przez `pdfSubtype()`	`string` (`S`, `D`, `N`, `F`, `Desc`)	—	Przypadki datowe współdzielą podtyp `D`; przypadki liczbowe współdzielą `N`

Sygnatury punktów wejścia:

public function split(string $pdfData, array $ranges, int $maxBytes = 100_000_000, int $maxRanges = 1000): SplitResult

public function mergeDocuments(
    array $pdfs,
    int $maxInputs = 100,
    int $maxBytesEach = 100_000_000,
): MergeResult

public function __construct(
    private readonly string $viewMode = 'tile',
)

public function generateCollectionDictionary(): string

Kontrakt zachowania

Podział i scalanie współdzielą jeden potok grafu obiektów:

Wejście musi zaczynać się nagłówkiem %PDF. Zabezpieczenia rozmiaru i liczby działają przed parsowaniem i przy naruszeniu zgłaszają OverflowException.
Strony liściowe są wykrywane przez skanowanie w poszukiwaniu markerów obiektów stron; węzły drzewa stron są wykluczane z zliczania.
Parser indeksuje każdy nieskompresowany obiekt pośredni za pomocą skanu terminatorów świadomego strumieni. Wygrywa pierwsze wystąpienie identyfikatora obiektu, więc nadpisania z aktualizacji przyrostowej nie są stosowane.
Dziedziczone atrybuty drzewa stron (/Resources, /MediaBox, /CropBox, /Rotate) są materializowane na każdej wyodrębnionej stronie przez przejście łańcucha /Parent, dzięki czemu segmenty są samodzielne.
Przechodnie domknięcie odniesień pośrednich każdej strony jest zbierane, z wyłączeniem krawędzi powrotnej /Parent, i przenumerowywane do świeżej, spójnej przestrzeni identyfikatorów.
Serializator emituje nagłówek, Catalog, drzewo Pages, obiekty stron i obiekty domknięcia, a następnie tablicę odsyłaczy z dokładnymi przesunięciami bajtowymi oraz startxref wskazującym na słowo kluczowe xref.
mergeDocuments powtarza potok dla każdego wejścia w jednej wspólnej przestrzeni identyfikatorów. Najwyższa wersja PDF wejścia ustala nagłówek wyjścia. Jest to zgodne zastępstwo dla wyłączonego mechanizmu scalania z Core, który pozostaje bezpieczny w razie awarii (fail-closed).
Wyjście jest deterministyczne. Nie są emitowane żadne znaczniki czasu ani losowe identyfikatory, więc identyczne wejście daje identyczne bajty.

Montaż Portfolio:

Konstruktor sprawdza tryb widoku. Emitowany token /View to odpowiednio /T, /D lub /H dla tile, detail i hidden.
generateCollectionDictionary() emituje /Type /Collection, token /View, blok /Schema, gdy istnieją pola, oraz dyrektywę /Sort według pierwszego pola schematu, rosnąco.
Każde pole schematu emituje /Subtype (z pdfSubtype()), /N (nazwa wyświetlana ze znakami ucieczki), /O (kolejność) i /V (widoczność).
Nazwy pól są oczyszczane do prawidłowych tokenów nazw PDF; znaki niebędące znakami słowa stają się podkreśleniami. Wartości łańcuchowe są poprzedzane znakami ucieczki jako literały łańcuchowe PDF.
Wpisy plików są udostępniane przez getEntries() do osadzenia przez warstwę zapisu. Sam słownik Collection niesie wyłącznie widok, schemat i sortowanie.

Przypadki brzegowe i tryby awarii

Zakres niepasujący do żadnej strony daje minimalny jednostronicowy segment (MediaBox 612 x 792), a nie błąd.
Dokument bez wykrywalnych markerów stron jest liczony jako jedna strona.
Strony przechowywane wewnątrz strumieni obiektów nie są wykrywane; w wyodrębnianiu uczestniczą tylko nieskompresowane obiekty pośrednie.
Gdy istnieją zduplikowane identyfikatory obiektów, używana jest rewizja o najniższym przesunięciu; późniejsze rewizje z aktualizacji przyrostowej są ignorowane.
Domknięcie odniesień na segment jest ograniczone do 50 000 obiektów; złośliwie samoodwołujący się lub rozgałęziony graf zgłasza OverflowException.
Domyślne górne limity: 100 MB wejścia, 1000 zakresów, 100 wejść scalania. Wszystkie można dostrajać po stronie wywołującego dla każdego wywołania.
splitEvery() odrzuca rozmiar segmentu poniżej 1 z InvalidArgumentException.
SplitResult::segment() odrzuca indeks poza zakresem z OutOfRangeException.
Dwie nazwy pól schematu różniące się jedynie interpunkcją oczyszczają się do tego samego klucza słownika; późniejsze pole po cichu przesłania wcześniejsze w emitowanym schemacie.
Ten moduł nie wykonuje żadnych operacji kryptograficznych; tryb FIPS nie zmienia jego zachowania.

Zgodność

Wyjście segmentów i scalania jest zgodne z modelem obiektu strony ISO 32000-2; źródło opatruje adnotacjami właściwe klauzule. Zewnętrznie sprawdzalne stwierdzenia:

Układ zwiastuna (trailer), przesunięcie bajtowe startxref oraz terminator %%EOF są zgodne z ISO 32000-2:2020, §7.5.5 — reference ef0f2a4b563b84f81b3e6428612bc47c510d94fc8096849d339abf0f3247d845.
Wartości /View słownika Collection (/T, /D, /H) są zgodne z ISO 32000-2:2020, §12.3.5 — reference 5cefaaeb40f3ff98e3aba135ac57c9424a05c43144c1b9b5156bfd4295e08ddd.
Wpisy /Subtype, /N, /O i /V pola Collection są zgodne z ISO 32000-2:2020, §12.3.5 (słownik pola collection) — reference 6300fbfdc8a913a8dc6f6ae34eff99f2bd03c4313a77777cdd5a8dd856d9537a.

Te stwierdzenia opisują zaimplementowaną funkcjonalność zweryfikowaną testami modułu. Wsparcie dla danej konstrukcji nie jest deklaracją zgodności, a zgodność nie jest certyfikacją; NextPDF nie posiada dla tego modułu żadnej certyfikacji zewnętrznej.

Uwagi deweloperskie

Wszystkie klasy modułu są final; typy wyniku i obiektów wartości są readonly. Typy splittera i Portfolio pochodzą z 1.9.0; mergeDocuments() dodano w 3.1.0.
PageRange i MergeResult to typy z Core, więc miejsca wywołań pozostają przenośne między edycjami.
Zwiastuny segmentów niosą wyłącznie /Size i /Root; nie jest emitowany identyfikator pliku /ID ani słownik /Info.
W przypadku przepływów z aktualizacją przyrostową lub podpisywaniem przekazuj bajty segmentu do modułu Writer, zamiast edytować je w miejscu.
Moduł nie loguje żadnej treści dokumentu.

Granica publikacji

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