Pro редакция

Merge

Краткий обзор

NextPDF\Pro\Merge\SmartMerger объединяет несколько PDF в один, затем применяет улучшения Pro: консолидированное дерево закладок из меток отдельных входов, дедупликацию страниц по хешу содержимого и выбор диапазона страниц для каждого входа. Базовая сборка документа выполняется движком объединения графа объектов Pro. Он перенумеровывает каждый вход в единое пространство объектов и записывает настоящую таблицу перекрёстных ссылок.

Доступность и лицензирование

Эта возможность поставляется в NextPDF Pro (nextpdf/pro) и активируется лицензионным пакетом уровня Pro. Развёртывание без этого права доступа не загружает классы возможности. Сравнить редакции и получить лицензию.

Классы Merge доступны всякий раз, когда установлен пакет Pro. Никакой флаг возможности времени выполнения этот модуль не активирует.

Установка

composer require nextpdf/pro:^3

Концептуальный обзор

SmartMerger принимает список объектов-значений MergeInput. Каждый вход несёт байты исходного PDF, необязательный список диапазонов страниц и необязательную метку. Входы с диапазонами страниц сводятся к выбранным страницам перед объединением. Объединённый документ создаётся движком объединения графа объектов Pro, который перенумеровывает каждый вход в единое непрерывное пространство объектов и выдаёт настоящую таблицу перекрёстных ссылок; затем слой Pro добавляет запрошенные улучшения.

SmartMergeConfig управляет улучшениями:

Консолидация закладок вставляет одну запись плана на каждый помеченный вход, указывающую на начало раздела этого входа. Это следует модели /Outlines каталога документа в ISO 32000-2:2020 §7.7.2.
Дедупликация страниц удаляет байт-идентичные дублирующиеся страницы между входами, сравниваемые по хешу содержимого.
Перезапись ссылок ищет внутренние действия GoTo в объединённом выводе.

SmartMergeResult сообщает объединённые байты плюс статистику: всего страниц, число источников, размер вывода, добавлено закладок, удалено дубликатов, обнаружено ссылок и упорядоченные метки входов.

Почему это работает именно так

Объединение PDF — это не байтовая конкатенация: каждый вход несёт собственные номера объектов, таблицу перекрёстных ссылок и дерево страниц, поэтому наивная склейка не загрузится ни в одном соответствующем стандарту ридере. Поэтому SmartMerger делегирует базовую сборку движку графа объектов Pro (PdfSplitter::mergeDocuments()), который перенумеровывает каждый вход в единое непрерывное пространство объектов, перестраивает единое дерево страниц и выдаёт настоящую таблицу перекрёстных ссылок с истинными байтовыми смещениями. Затем улучшения Pro — консолидация закладок, дедупликация и обнаружение ссылок — наслаиваются на этот проверенный вывод, а не переизобретают сборку. Дедупликация на уровне всего документа и обработка ссылок только через обнаружение — это намеренные границы области, которые сохраняют объединение детерминированным и безопасным на недоверенном входе.

Проектный контекст: Анатомия файла PDF.

Контракт поведения

Вход. Непустой список MergeInput. Пустой список выбрасывает InvalidArgumentException. Число входов и размер байтов на вход ограничены SmartMergeConfig (maxInputs, maxBytesPerInput).
Вывод. SmartMergeResult. isValid() истинно, когда вывод начинается с заголовка %PDF.
Консолидация закладок добавляет одну запись на каждый вход с непустой меткой, когда включено consolidateBookmarks.
Дедупликация включается по выбору (deduplicatePages, по умолчанию выключено) и сопоставляет целые страницы по хешу содержимого, а не визуально похожие страницы.
Перезапись ссылок в текущем выпуске обнаруживает и подсчитывает внутренние действия GoTo; она не выполняет полное междокументное переразрешение пунктов назначения. Считайте linksRewritten счётчиком обнаружения.
Детерминизм. Для идентичных входов и конфигурации объединённый поток байтов стабилен, при условии задокументированного профиля детерминизма движка объединения Pro.

Публичная поверхность API

Тип	Вид	Ключевые члены
`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`

Пример кода — быстрый старт

<?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";

Пример кода — продакшен

<?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;
}

Граничные случаи и подводные камни

Один вход допустим и объединяется в нормализованную копию этого документа.
Дедупликация сравнивает байтовое содержимое целых страниц; страницы, различающиеся только метаданными или нумерацией объектов, не считаются дубликатами.
Выбор диапазона страниц на входе применяется до упорядочивания при объединении.
linksRewritten — это счётчик обнаруженных действий, а не гарантия того, что каждая цель междокументной ссылки была переуказана.

Производительность

Стоимость определяется в основном движком объединения Pro и масштабируется с общим объёмом байтов входов и количеством страниц. Дедупликация добавляет один хеш содержимого на страницу. Вступительный блок performance_budget — это ориентир на одно объединение.

Замечания по безопасности

Число входов и размер на вход ограничены SmartMergeConfig, чтобы ограничить исчерпание ресурсов от враждебных входов. Объединение не исполняет встроенные скрипты документа. О защите разбора потоков байтов см. модель безопасности Core.

Соответствие

Утверждение	Пункт спецификации	Статус
Консолидированные закладки через `/Outlines`	ISO 32000-2:2020 §7.7.2	Проверено (модульный набор)
Дедупликация страниц по хешу содержимого	—	Проверено (модульный набор)
Полное междокументное переразрешение ссылок	—	Не поддерживается (только обнаружение)

Резервный вариант / альтернатива в Core

Для базовой конкатенации без консолидации Pro поддерживаемый автономный путь — открытый Core NextPDF\Document\PdfMerger. SmartMerger не делегирует ему; объединение Pro работает на собственном движке графа объектов. См. /modules/core/document/.

Граница с Enterprise

Этот модуль выполняет структурное объединение. Он не выполняет сборку для правового удержания, редактирование или упаковку доказательственной цепочки сохранности; это здесь не предоставляется.

Граница публикации

Эта страница документирует только внешне наблюдаемое поведение и поддерживаемую публичную поверхность API. Внутренние пути пространств имён, вспомогательные классы, таблицы механизмов, имена файлов runbook и префиксы тикетов выходят за рамки области.