Merge — szczegółowa dokumentacja referencyjna

W skrócie

Ta strona jest dokumentacją na poziomie kontraktu modułu Merge w edycji NextPDF Pro, NextPDF\Pro\Merge. SmartMerger składa kilka dokumentów wejściowych w jeden i stosuje wzbogacenia Pro: skonsolidowane drzewo zakładek z etykiet poszczególnych wejść, deduplikację całych dokumentów, wybór zakresu stron dla każdego wejścia oraz wykrywanie odnośników wewnętrznych. SemanticSplitter to towarzyszący punkt wejścia podziału świadomego struktury. Ta strona podaje publiczne API, kontrakt obserwowalnego zachowania, ograniczenia zasobów oraz tryby awarii. Konfiguracja zorientowana na zadania i przykłady znajdują się na stronie możliwości Merge.

Dostępność i licencjonowanie

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

Żadna flaga możliwości w czasie działania nie obejmuje bramą tego modułu. Klasy Merge są używalne, gdy tylko nextpdf/pro jest zainstalowane i licencjonowane.

Powierzchnia publicznego API

Symbol	Parametry	Zachowanie domyślne	Zwraca	Zgłasza lub kończy się niepowodzeniem z	Uwagi
SmartMerger::__construct()	?PdfMerger $coreMerger = null, ?PdfSplitter $splitter = null	Przyjmuje i ignoruje starszy scalacz Core; wartość null dla splitera konstruuje domyślny spliter Pro	—	—	$coreMerger zachowany wyłącznie dla zgodnej wstecznie konstrukcji
SmartMerger::merge()	list<MergeInput> $inputs, SmartMergeConfig $config = new SmartMergeConfig()	Redukuje zakresy stron, deduplikuje całe wejścia, deleguje bazowe składanie, a następnie wstrzykuje zakładki i zlicza odnośniki zgodnie z konfiguracją	SmartMergeResult	InvalidArgumentException przy pustej liście wejściowej; OverflowException, gdy liczba wejść przekracza maxInputs lub wejście przekracza maxBytesPerInput	Jedyny punkt wejścia scalania
MergeInput::__construct()	string $pdfData, list<PageRange> $pageRanges = [], string $label = ''	Obiekt wartości; puste $pageRanges wybiera wszystkie strony	—	—	Tylko do odczytu
MergeInput::hasPageRanges()	—	Prawda, gdy wejście zawiera co najmniej jeden zakres stron	bool	—	—
SmartMergeConfig::__construct()	bool $consolidateBookmarks = true, bool $deduplicatePages = false, bool $rewriteLinks = true, int $maxInputs = 100, int $maxBytesPerInput = 100_000_000	Obiekt wartości przechowujący przełączniki wzbogacania oraz ograniczenia zasobów	—	—	Tylko do odczytu; deduplikacja jest opcjonalna (opt-in)
SmartMergeConfig::default()	—	Zakładki i skanowanie odnośników włączone, deduplikacja wyłączona	self	—	Fabryka statyczna
SmartMergeConfig::basic()	—	Wszystkie wzbogacenia wyłączone; tylko bazowa konkatenacja	self	—	Fabryka statyczna
SmartMergeResult::__construct()	string $pdfData, int $totalPages, int $sourceCount, int $mergedSize, int $bookmarksAdded = 0, int $duplicatesRemoved = 0, int $linksRewritten = 0, list<string> $inputLabels = []	Nośnik tylko do odczytu przechowujący scalone bajty i statystyki konsolidacji	—	—	Tylko do odczytu
SmartMergeResult::isValid()	—	Prawda, gdy wyjście zaczyna się nagłówkiem %PDF	bool	—	Tylko sprawdzenie nagłówka
SmartMergeResult::hasOptimizations()	—	Prawda, gdy usunięto jakikolwiek duplikat lub zliczono jakikolwiek odnośnik	bool	—	—
SemanticSplitter::__construct()	?PdfSplitter $splitter = null	Argument null konstruuje domyślny spliter Pro	—	—	Wstrzykiwanie przez konstruktor na potrzeby testów
SemanticSplitter::splitByStructure()	string $pdfData, float $headingFontThreshold = 14.0	Wykrywa operatory Tf o rozmiarze nagłówka jako początki sekcji i dzieli na tych granicach; brak wykrytej struktury zwraca jedną sekcję obejmującą cały dokument	SplitResult	InvalidArgumentException, gdy bufor jest pusty lub brakuje nagłówka %PDF; OverflowException, gdy wejście przekracza 100 MB	Cofa się do podziału zakresu stron Core

Sygnatury punktów wejścia

public function __construct(
    ?PdfMerger $coreMerger = null,
    ?PdfSplitter $splitter = null,
)

public function merge(
    array $inputs,
    SmartMergeConfig $config = new SmartMergeConfig(),
): SmartMergeResult

public function __construct(
    public string $pdfData,
    public array $pageRanges = [],
    public string $label = '',
)

public function hasPageRanges(): bool

public function __construct(
    public bool $consolidateBookmarks = true,
    public bool $deduplicatePages = false,
    public bool $rewriteLinks = true,
    public int $maxInputs = 100,
    public int $maxBytesPerInput = 100_000_000,
)

public static function default(): self

public static function basic(): self

public function isValid(): bool

public function hasOptimizations(): bool

public function __construct(?PdfSplitter $splitter = null)

public function splitByStructure(
    string $pdfData,
    float $headingFontThreshold = 14.0,
): SplitResult

Kontrakt zachowania

Potok scalania

SmartMerger::merge() wykonuje stały potok, obserwowany z zewnątrz następująco.

1. Pusta lista wejściowa zgłasza InvalidArgumentException. Liczba wejść jest następnie ograniczona przez maxInputs; przekroczenie zgłasza OverflowException.
2. Rozmiar każdego wejścia jest sprawdzany względem maxBytesPerInput przed użyciem. Gdy wejście deklaruje zakresy stron, jest najpierw redukowane do wybranych stron przez spliter Pro, a następnie wnosi tylko te strony.
3. Gdy deduplicatePages jest włączone, pełny ciąg bajtów każdego dokumentu wejściowego jest odciskany niekryptograficzną funkcją xxh128. Wejście, którego bajty dokładnie odpowiadają wcześniejszemu wejściu, jest odrzucane. Deduplikacja obejmuje cały dokument i jest dokładna co do bajtu.
4. Bazowe składanie deleguje do silnika Pro PdfSplitter::mergeDocuments(), który przenumerowuje każde wejście do jednej ciągłej przestrzeni obiektów i emituje rzeczywistą tablicę odsyłaczy (cross-reference).
5. Konsolidacja zakładek jest stosowana, gdy consolidateBookmarks jest włączone i co najmniej jedno wejście zawiera niepustą etykietę. Wstawiany jest minimalny słownik /Outlines, odniesiony z katalogu dokumentu, z jednym wpisem konspektu na wejście w kolejności scalania.
6. Gdy rewriteLinks jest włączone, scalone wyjście jest skanowane w poszukiwaniu akcji /S /GoTo, a ich liczba jest raportowana.

Statystyki wyniku

SmartMergeResult raportuje scalone bajty oraz statystyki. totalPages pochodzi z bazowego scalania. sourceCount to pierwotna liczba wejść, pobrana przed deduplikacją. mergedSize to długość wyjścia w bajtach. bookmarksAdded zlicza tylko wejścia, które dostarczyły niepustą etykietę. duplicatesRemoved zlicza odrzucone całe wejścia. linksRewritten to wykryta liczba GoTo. inputLabels wymienia rozwiązane etykiety w kolejności scalania. isValid() sprawdza nagłówek %PDF; hasOptimizations() jest prawdą, gdy usunięto duplikat lub zliczono odnośnik.

Tytuły zakładek

Każdy wpis konspektu niesie etykietę wejścia jako /Title, poddaną sekwencji ucieczki jako łańcuch literalny PDF zgodnie z ISO 32000-2:2020 §7.3.4.2. Odwrotny ukośnik (reverse solidus) jest najpierw podwajany, nawiasy są poddawane sekwencji ucieczki, nazwane bajty sterujące używają swoich zdefiniowanych sekwencji, a każdy pozostały bajt niedrukowalny staje się trzycyfrową sekwencją ucieczki ósemkowej. Wroga etykieta nie może zatem zdesynchronizować separatora łańcucha literalnego ani wstrzyknąć struktury obiektu. Wejścia z pustą etykietą otrzymują zastępczy tytuł Document N, indeksowany od jedynki.

Bazowe składanie

Starsza metoda Core PdfMerger::merge() jest w tym wydaniu celowym zaślepieniem typu fail-closed; nigdy nie jest wywoływana przez SmartMerger. Bazowe scalanie przebiega zamiast tego przez Pro PdfSplitter::mergeDocuments(), więc scalony plik niesie dokładną co do bajtu tablicę odsyłaczy z jednym wpisem na każdy obiekt pośredni zgodnie z ISO 32000-2:2020 §7.5.4. Determinizm wynika z udokumentowanego profilu splitera Pro: identyczne wejścia i konfiguracja dają stabilny strumień bajtów.

Podział świadomy struktury

SemanticSplitter::splitByStructure() skanuje strumienie treści stron w poszukiwaniu operatorów ustawiania czcionki Tf o wartości równej lub większej niż headingFontThreshold (domyślnie 14.0) i traktuje każdą taką stronę jako początek sekcji. Granice są przekształcane w zakresy stron i delegowane do Pro PdfSplitter::split(). Gdy nie wykryto żadnej granicy, cały dokument zwracany jest jako pojedyncza sekcja. Wejście musi zaczynać się od %PDF i mieścić się w limicie 100 MB.

Przypadki brzegowe i tryby awarii

• Pusta lista wejściowa kończy się niepowodzeniem z InvalidArgumentException przed jakimkolwiek składaniem.
• Liczba wejść powyżej maxInputs (domyślnie 100) lub jakiekolwiek wejście powyżej maxBytesPerInput (domyślnie 100 MB) kończy się niepowodzeniem z OverflowException. Oba ograniczenia są celowymi odrzuceniami typu fail-closed, a nie błędami przejściowymi.
• Deduplikacja obejmuje cały dokument i jest dokładna co do bajtu. Dwa wejścia, które renderują się identycznie, ale różnią się jakimkolwiek bajtem, są oba zachowywane, a duplicatesRemoved zlicza odrzucone całe wejścia pomimo zorientowanej na strony nazwy deduplicatePages.
• sourceCount odzwierciedla pierwotną liczbę wejść, a nie liczbę dokumentów po deduplikacji.
• Konsolidacja zakładek uruchamia się tylko wtedy, gdy co najmniej jedno wejście ma niepustą etykietę. Przy consolidateBookmarks równym prawda, lecz każdej etykiecie pustej, nie jest zapisywany żaden obiekt /Outlines.
• Wstrzyknięte wpisy konspektu niosą tytuły oraz odnośniki drzewa /Parent, /Prev, /Next; w tym wydaniu nie osadzają jawnych celów /Dest.
• Przepisywanie odnośników zlicza wyłącznie akcje /S /GoTo; nie przeadresowuje celów w przemianowanych obiektach. Traktuj linksRewritten jako liczbę wykryć.
• Wykrywanie w SemanticSplitter jest leksykalne. Opiera się na operatorach rozmiaru czcionki Tf, więc strony zawierające tylko obrazy lub nietypowo zakodowane nie wytwarzają granic i zwracają pojedynczą sekcję obejmującą cały dokument.

Zachowanie w trybie FIPS

W tym module nie zachodzi żadna operacja kryptograficzna, więc nie istnieje żadne zachowanie specyficzne dla trybu FIPS. Odcisk treści xxh128 używany do deduplikacji jest niekryptograficznym skrótem wykrywania zmian i nie niesie żadnej wagi integralnościowej ani dowodowej.

Zgodność ze standardami

Twierdzenie	Standard	Klauzula
Skonsolidowane zakładki zapisane jako słownik /Outlines odniesiony z katalogu dokumentu	ISO 32000-2:2020	§7.7.2
Bazowe scalanie emituje dokładną co do bajtu tablicę odsyłaczy dla każdego obiektu pośredniego	ISO 32000-2:2020	§7.5.4
Tytuły wpisów konspektu poddane sekwencji ucieczki jako łańcuchy literalne PDF, z obsługą ukośnika odwrotnego i nawiasów	ISO 32000-2:2020	§7.3.4.2
Pełne ponowne rozwiązywanie odnośników międzydokumentowych	—	Nieobsługiwane (tylko wykrywanie GoTo)
Jawne cele konspektu dla poszczególnych sekcji	—	Nieemitowane w tym wydaniu

Wszystkie klauzule są parafrazowane; NextPDF nie odtwarza tekstu normatywnego. Są to stwierdzenia o możliwościach, a nie certyfikaty; NextPDF nie posiada żadnego certyfikatu i żadnego nie przyznaje.

Uwagi deweloperskie

• Dostępność w pakiecie Pro: SmartMerger, MergeInput, SmartMergeConfig, SmartMergeResult oraz SemanticSplitter od 2.2.0. Wszystkie są aktualne w nextpdf/pro 3.1.0.
• Bazowe scalanie deleguje do Pro PdfSplitter::mergeDocuments(). Starsza metoda Core PdfMerger::merge() jest w tym wydaniu zaślepieniem typu fail-closed i nigdy nie jest wywoływana.
• Włączaj deduplicatePages tylko wtedy, gdy wejścia mogą być identycznymi co do bajtu całymi dokumentami; nie łączy kopii zbliżonych ani przekodowanych.
• Użyj SmartMergeConfig::basic() do czystej konkatenacji oraz ::default() dla zakładek wraz ze skanowaniem odnośników.
• Przechwytuj OverflowException podczas scalania niezaufanych wejść; ograniczenia liczby i rozmiaru są celowymi odrzuceniami.
• Do prostego podziału zakresu stron preferuj bezpośrednio Pro PdfSplitter; po SemanticSplitter sięgaj tylko wtedy, gdy wymagane jest dzielenie na sekcje sterowane nagłówkami.

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

Zobacz także

• Merge (możliwości) — instalacja, szybki start i produkcyjne przykłady.
• Toc — szczegółowa dokumentacja referencyjna
• Diff — szczegółowa dokumentacja referencyjna
• Document — szczegółowa dokumentacja referencyjna — spliter Pro i bazowy silnik scalania.