Pro edycja

Scalanie

W skrócie

NextPDF\Pro\Merge\SmartMerger scala kilka plików PDF w jeden, a następnie stosuje rozszerzenia Pro: skonsolidowane drzewo zakładek na podstawie etykiet poszczególnych wejść, deduplikację stron według skrótu zawartości oraz wybór zakresu stron dla każdego wejścia. Składanie dokumentu bazowego przebiega przez silnik scalania grafu obiektów Pro. Przenumerowuje on każde wejście do jednej przestrzeni obiektów i zapisuje prawdziwą tablicę odsyłaczy.

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ę.

Klasy Merge są dostępne zawsze, gdy zainstalowany jest pakiet Pro. Żadna flaga możliwości czasu wykonania nie bramkuje tego modułu.

Instalacja

composer require nextpdf/pro:^3

Przegląd koncepcyjny

SmartMerger przyjmuje listę obiektów wartości MergeInput. Każde wejście niesie źródłowe bajty PDF, opcjonalną listę zakresów stron oraz opcjonalną etykietę. Wejścia z zakresami stron są redukowane do wybranych stron przed scaleniem. Połączony dokument jest tworzony przez silnik scalania grafu obiektów Pro, który przenumerowuje każde wejście do jednej ciągłej przestrzeni obiektów i emituje prawdziwą tablicę odsyłaczy; warstwa Pro dodaje następnie żądane rozszerzenia.

SmartMergeConfig steruje rozszerzeniami:

Konsolidacja zakładek wstawia jeden wpis konspektu na każde etykietowane wejście, wskazujący na początek sekcji tego wejścia. Jest to zgodne z modelem /Outlines katalogu dokumentu w ISO 32000-2:2020 §7.7.2.
Deduplikacja stron usuwa identyczne bajtowo zduplikowane strony między wejściami, porównywane według skrótu zawartości.
Przepisywanie odnośników skanuje scalony wynik pod kątem wewnętrznych akcji GoTo.

SmartMergeResult raportuje scalone bajty oraz statystyki: łączną liczbę stron, liczbę źródeł, rozmiar wyniku, dodane zakładki, usunięte duplikaty, wykryte odnośniki oraz uporządkowane etykiety wejść.

Dlaczego działa to w ten sposób

Scalanie plików PDF to nie konkatenacja bajtów: każde wejście niesie własne numery obiektów, tablicę odsyłaczy i drzewo stron, więc naiwne sklejenie nie wczyta się w żadnym zgodnym czytniku. Dlatego SmartMerger deleguje składanie bazowe do silnika grafu obiektów Pro (PdfSplitter::mergeDocuments()), który przenumerowuje każde wejście do jednej ciągłej przestrzeni obiektów, odbudowuje pojedyncze drzewo stron i emituje prawdziwą tablicę odsyłaczy z rzeczywistymi przesunięciami bajtowymi. Rozszerzenia Pro — konsolidacja zakładek, deduplikacja i wykrywanie odnośników — nakładają się następnie na ten zweryfikowany wynik, zamiast ponownie implementować składanie. Deduplikacja całych dokumentów i obsługa odnośników ograniczona do wykrywania to celowe granice zakresu, które utrzymują scalanie deterministycznym i bezpiecznym na niezaufanych danych.

Tło projektowe: Anatomia pliku PDF.

Kontrakt zachowania

Wejście. Niepusta lista MergeInput. Pusta lista zgłasza InvalidArgumentException. Liczba wejść i rozmiar bajtowy każdego wejścia są ograniczone przez SmartMergeConfig (maxInputs, maxBytesPerInput).
Wyjście. SmartMergeResult. isValid() jest prawdą, gdy wynik zaczyna się nagłówkiem %PDF.
Konsolidacja zakładek dodaje jeden wpis na każde wejście z niepustą etykietą, gdy consolidateBookmarks jest włączone.
Deduplikacja jest opcjonalna (deduplicatePages, domyślnie wyłączona) i dopasowuje całe strony według skrótu zawartości, a nie strony wizualnie podobne.
Przepisywanie odnośników w bieżącym wydaniu wykrywa i zlicza wewnętrzne akcje GoTo; nie wykonuje pełnego ponownego rozwiązania celów między dokumentami. Traktuj linksRewritten jako liczbę wykryć.
Determinizm. Dla identycznych wejść i konfiguracji scalony strumień bajtów jest stabilny, z zastrzeżeniem udokumentowanego profilu determinizmu silnika scalania Pro.

Publiczna powierzchnia API

Typ	Rodzaj	Kluczowe składowe
`NextPDF\Pro\Merge\SmartMerger`	`final class`	`__construct(?PdfMerger $coreMerger = null, ?PdfSplitter $splitter = null)`, `merge(array $inputs, SmartMergeConfig $config = new SmartMergeConfig()): SmartMergeResult`
`NextPDF\Pro\Merge\MergeInput`	`final readonly class`	`__construct(string $pdfData, array $pageRanges = [], string $label = '')`, `hasPageRanges(): bool`
`NextPDF\Pro\Merge\SmartMergeConfig`	`final readonly class`	`__construct(bool $consolidateBookmarks = true, bool $deduplicatePages = false, bool $rewriteLinks = true, int $maxInputs = 100, int $maxBytesPerInput = 100_000_000)`, `default()`, `basic()`
`NextPDF\Pro\Merge\SmartMergeResult`	`final readonly class`	`string $pdfData`, `int $totalPages`, `int $sourceCount`, `int $bookmarksAdded`, `int $duplicatesRemoved`, `int $linksRewritten`, `array $inputLabels`, `isValid(): bool`, `hasOptimizations(): bool`

Przykład kodu — Szybki start

<?php

declare(strict_types=1);

use NextPDF\Pro\Merge\MergeInput;
use NextPDF\Pro\Merge\SmartMerger;

$result = (new SmartMerger())->merge([
    new MergeInput(file_get_contents('cover.pdf'), label: 'Cover'),
    new MergeInput(file_get_contents('body.pdf'),  label: 'Body'),
]);

echo $result->totalPages, " pages, ",
     $result->bookmarksAdded, " bookmarks\n";

Przykład kodu — Produkcja

<?php

declare(strict_types=1);

use NextPDF\Pro\Merge\MergeInput;
use NextPDF\Pro\Merge\SmartMergeConfig;
use NextPDF\Pro\Merge\SmartMerger;

function assemblePacket(array $sections): string
{
    $inputs = [];
    foreach ($sections as $label => $bytes) {
        $inputs[] = new MergeInput($bytes, label: (string) $label);
    }

    $config = new SmartMergeConfig(
        consolidateBookmarks: true,
        deduplicatePages: true,
        rewriteLinks: false,
        maxInputs: 50,
    );

    $result = (new SmartMerger())->merge($inputs, $config);

    if (! $result->isValid()) {
        throw new RuntimeException('merge produced invalid output');
    }

    return $result->pdfData;
}

Przypadki brzegowe i pułapki

Pojedyncze wejście jest poprawne i scala się do znormalizowanej kopii tego dokumentu.
Deduplikacja porównuje bajtową zawartość całych stron; strony różniące się tylko metadanymi lub numeracją obiektów nie są traktowane jako duplikaty.
Wybór zakresu stron na wejściu jest stosowany przed ustaleniem kolejności scalania.
linksRewritten to liczba wykrytych akcji, a nie gwarancja, że każdy cel odnośnika między dokumentami został ponownie wskazany.

Wydajność

Koszt jest zdominowany przez silnik scalania Pro i skaluje się wraz z łączną liczbą bajtów wejściowych i liczbą stron. Deduplikacja dodaje jeden skrót zawartości na stronę. Frontmatter performance_budget jest punktem odniesienia dla pojedynczego scalenia.

Uwagi dotyczące bezpieczeństwa

Liczba wejść i rozmiar każdego wejścia są ograniczone przez SmartMergeConfig, aby ograniczyć wyczerpanie zasobów przez wrogie dane. Scalanie nie wykonuje osadzonych skryptów dokumentu. Zobacz model bezpieczeństwa Core w zakresie utwardzenia parsowania strumieni bajtów.

Konformancja

Twierdzenie	Klauzula specyfikacji	Status
Skonsolidowane zakładki przez `/Outlines`	ISO 32000-2:2020 §7.7.2	Zweryfikowane (zestaw testów jednostkowych)
Deduplikacja stron według skrótu zawartości	—	Zweryfikowane (zestaw testów jednostkowych)
Pełne ponowne rozwiązanie odnośników między dokumentami	—	Nieobsługiwane (tylko wykrywanie)

Rozwiązanie awaryjne / alternatywa Core

W przypadku podstawowej konkatenacji bez konsolidacji Pro wspieraną, samodzielną ścieżką jest otwartoźródłowy Core NextPDF\Document\PdfMerger. SmartMerger nie deleguje do niego; scalanie Pro działa na własnym silniku grafu obiektów. Zobacz /modules/core/document/.

Uwaga o granicy Enterprise

Ten moduł wykonuje scalanie strukturalne. Nie wykonuje składania na potrzeby legal hold, redakcji ani pakowania łańcucha dowodowego (chain-of-custody); te funkcje nie są tu dostarczane.

Granica publikacji

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