Document

W skrócie

Moduł Document dzieli plik PDF na segmenty według zakresu stron oraz składa portfolia PDF (Collections) z sortowalnymi kolumnami schematu. Obie operacje są ograniczone wobec wrogiego wejścia.

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. Document jest częścią edycji Pro, bez osobnej flagi licencyjnej dla poszczególnych funkcji. Porównaj edycje i uzyskaj licencję.

Instalacja

composer require nextpdf/pro:^3

Kod znajduje się w przestrzeni nazw NextPDF\Pro\Document.

Przegląd koncepcyjny

Dostarczone są dwie możliwości:

• PdfSplitter wyodrębnia zakresy stron do samodzielnych segmentów PDF. Wykrywa strony, skanując obiekty stron w surowym wejściu, i zawija wybrane strony w minimalny katalog oraz drzewo stron. Obsługuje dzielenie według zakresów, dzielenie o stałym rozmiarze (splitEvery) oraz wyodrębnianie pojedynczego zakresu (extractPages).
• PdfPortfolio buduje słownik PDF Collection, który agreguje załączniki plikowe z określonym schematem. Obsługuje tryby widoku tile, detail i hidden oraz emituje słownik nadający się do włączenia do katalogu dokumentu.

Dlaczego działa to w ten sposób

Dzielenie pliku PDF to nie wycinek bajtów. Obiekt strony odwołuje się do współdzielonych zasobów, czcionek i strumieni treści poprzez odwołanie pośrednie. Dziedziczy również /MediaBox i /Resources po swoich przodkach w drzewie stron. Dlatego splitter rekonstruuje każdy segment jako samowystarczalny graf obiektów: przechodzi przechodnie domknięcie odwołań wybranych stron, materializuje dziedziczone atrybuty, przenumerowuje je w świeżą przestrzeń identyfikatorów i zapisuje tablicę odsyłaczy krzyżowych z przesunięciami dokładnymi co do bajta. Przejście domknięcia jest ograniczone, ponieważ wrogi graf o rozgałęzieniu mógłby w przeciwnym razie wciągnąć nieograniczoną pracę do jednego segmentu. Wynik otwiera się jako prawidłowy samodzielny PDF, a nie fragment z wiszącymi odwołaniami.

Tło projektowe: Anatomia pliku PDF.

Kontrakt zachowania

• PdfSplitter::split($pdfData, $ranges, $maxBytes = 100_000_000, $maxRanges = 1000) wymusza limit rozmiaru wejścia oraz limit liczby zakresów i odrzuca wejście, które nie zaczyna się od nagłówka PDF.
• splitEvery($pdfData, $pagesPerSegment) odrzuca rozmiar segmentu poniżej 1; ostatni segment może zawierać mniej stron.
• PdfPortfolio odrzuca każdy tryb widoku inny niż tile, detail lub hidden w czasie konstrukcji.
• addSchema() i addEntry() zwracają portfolio do płynnego łańcuchowania; generateCollectionDictionary() zwraca ciąg słownika Collection.
• Nazwy pól schematu są oczyszczane na potrzeby użycia jako obiekty nazw PDF; wartości łańcuchowe są poddawane ucieczce dla literalnych ciągów PDF.

Przykład kodu — Szybki start

Poniższe odzwierciedla udokumentowane publiczne API. Repozytorium nie dostarcza dla tego modułu uruchamialnego przykładu.

use NextPDF\Pro\Document\PdfSplitter;
use NextPDF\Document\PageRange;

$result = (new PdfSplitter())->split($pdfBytes, [new PageRange(1, 5)]);

Przykład kodu — Produkcja

use NextPDF\Pro\Document\PdfSplitter;
use NextPDF\Document\PageRange;

$splitter = new PdfSplitter();

try {
    $result = $splitter->split(
        $pdfBytes,
        [new PageRange(1, 10), new PageRange(11, 20)],
        maxBytes: 50_000_000,
        maxRanges: 100,
    );
} catch (\InvalidArgumentException $e) {
    // Input rejected (not a PDF, or limits exceeded).
}

Przypadki brzegowe i pułapki

• Splitter rekonstruuje każdy segment jako świeży graf obiektów z prawdziwą, dokładną co do bajta tablicą odsyłaczy krzyżowych; segmenty są prawidłowymi samodzielnymi plikami PDF. Przenumerowuje je w nową przestrzeń identyfikatorów zamiast zachowywać źródłowy układ bajtów, więc bajty segmentu przekaż do modułu Writer dla przepływów aktualizacji przyrostowej lub podpisywania.
• Zakres niepasujący do żadnej strony daje minimalny jednostronicowy segment zamiast błędu.
• Sortowanie portfolio domyślnie korzysta z pierwszego pola schematu, rosnąco.

Wydajność

Dzielenie i składanie portfolio są liniowe względem rozmiaru wejścia i liczby wpisów. Domyślny pułap wejścia to 100 MB, a domyślny pułap zakresów to 1000; oba można dostrajać przez wywołującego w dół. Mierz na reprezentatywnych dokumentach.

Uwagi dotyczące bezpieczeństwa

Traktuj wejście jako niezaufane. Strażnicy rozmiaru i liczby ograniczają zużycie zasobów. Moduł oczyszcza nazwy pól i poddaje ucieczce wartości łańcuchowe, zanim trafią do słownika wyjściowego. Nie loguje żadnej zawartości dokumentu.

Konformancja

Słownik Portfolio podąża za modelem PDF Collections, a splitter podąża za modelem obiektów stron zdefiniowanym przez ISO 32000-2; źródło opisuje właściwe klauzule. Korpus RAG był niedostępny w czasie tworzenia, dlatego ta strona nie twierdzi żadnych zewnętrznych identyfikatorów klauzul i ogranicza stwierdzenia o konformancji do zachowania zweryfikowanego testami modułu.

Nota o granicy Enterprise

Enterprise nie zmienia zachowania Document. Enterprise dodaje funkcje archiwalne i zgodności wyższego poziomu, udokumentowane osobno; nie są one wymagane do dzielenia ani składania Portfolio.

Rozwiązanie awaryjne / alternatywa w Core

Bez Pro użyj bazowych prymitywów dokumentu NextPDF Core; dzielenie według zakresu stron i składanie Portfolio to dodatki Pro. Zobacz /modules/document/.

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 i prefiksy zgłoszeń są poza zakresem.

Zobacz też

• Document — Głęboka referencja
• Writer
• Merge
• Output Pipeline