Pro sürüm

Birleştirme

Bir bakışta

NextPDF\Pro\Merge\SmartMerger, birden çok PDF’i tek bir belgede birleştirir, ardından Pro geliştirmelerini uygular: girdi başına etiketlerden birleştirilmiş bir yer imi ağacı, içerik karması sayfa yinelenenlerini kaldırma ve girdi başına sayfa aralığı seçimi. Temel belge derlemesi, Pro nesne grafiği birleştirme motoru üzerinden çalışır. Her girdiyi tek bir nesne uzayına yeniden numaralar ve gerçek bir çapraz başvuru tablosu yazar.

Kullanılabilirlik ve lisanslama

Bu yetenek NextPDF Pro (nextpdf/pro) içinde gelir ve bir Pro katmanı lisans zarfıyla etkinleşir. Bu yetkiye sahip olmayan bir dağıtım, yeteneğin sınıflarını yüklemez. Sürümleri karşılaştırın ve bir lisans edinin.

Merge sınıfları, Pro paketi yüklü olduğunda her zaman kullanılabilir. Bu modülü hiçbir çalışma zamanı yetenek bayrağı kapamaz.

Yükleme

composer require nextpdf/pro:^3

Kavramsal genel bakış

SmartMerger, bir MergeInput değer nesneleri listesini kabul eder. Her girdi, kaynak PDF baytlarını, isteğe bağlı bir sayfa aralıkları listesini ve isteğe bağlı bir etiketi taşır. Sayfa aralıkları olan girdiler, birleştirmeden önce seçilen sayfalara indirgenir. Birleştirilmiş belge, her girdiyi tek bir bitişik nesne uzayına yeniden numaralayan ve gerçek bir çapraz başvuru tablosu yayan Pro nesne grafiği birleştirme motoru tarafından üretilir; ardından Pro katmanı, istenen geliştirmeleri ekler.

SmartMergeConfig, geliştirmeleri denetler:

Yer imi birleştirme, etiketlenmiş her girdi için, o girdinin bölümünün başlangıcına işaret eden bir taslak girişi ekler. Bu, ISO 32000-2:2020 §7.7.2’deki belge kataloğu /Outlines modelini izler.
Sayfa yinelenenlerini kaldırma, girdiler arasında içerik karmasıyla karşılaştırılan bayt-özdeş yinelenen sayfaları kaldırır.
Bağlantı yeniden yazma, birleştirilmiş çıktıda iç GoTo eylemlerini tarar.

SmartMergeResult, birleştirilmiş baytları artı istatistikleri raporlar: toplam sayfa, kaynak sayısı, çıktı boyutu, eklenen yer imleri, kaldırılan yinelenenler, algılanan bağlantılar ve sıralı girdi etiketleri.

Neden bu şekilde çalışır

PDF’leri birleştirmek bayt birleştirme değildir: her girdi kendi nesne numaralarını, çapraz başvuru tablosunu ve sayfa ağacını taşır, bu nedenle naif bir ekleme hiçbir uyumlu okuyucuda yüklenmez. Bu yüzden SmartMerger, temel derlemeyi her girdiyi tek bir bitişik nesne uzayına yeniden numaralayan, tek bir sayfa ağacını yeniden kuran ve gerçek bayt uzaklıklarıyla gerçek bir çapraz başvuru tablosu yayan Pro nesne grafiği motoruna (PdfSplitter::mergeDocuments()) devreder. Pro geliştirmeleri — yer imi birleştirme, yinelenenleri kaldırma ve bağlantı algılama — derlemeyi yeniden uygulamak yerine bu doğrulanmış çıktının üzerine katmanlanır. Tüm belge yinelenenlerini kaldırma ve yalnızca algılamalı bağlantı işleme, birleştirmeyi güvenilmez girdilerde belirlenimci ve güvenli tutan bilinçli kapsam sınırlarıdır.

Tasarım arka planı: Bir PDF dosyasının anatomisi.

Davranış sözleşmesi

Girdi. Boş olmayan bir MergeInput listesi. Boş bir liste, InvalidArgumentException oluşturur. Girdi sayısı ve girdi başına bayt boyutu, SmartMergeConfig (maxInputs, maxBytesPerInput) ile sınırlandırılır.
Çıktı. Bir SmartMergeResult. Çıktı %PDF başlığıyla başladığında isValid() doğrudur.
Yer imi birleştirme, consolidateBookmarks etkinleştirildiğinde, boş olmayan bir etikete sahip her girdi için bir giriş ekler.
Yinelenenleri kaldırma isteğe bağlıdır (deduplicatePages, varsayılan kapalı) ve görsel olarak benzer sayfaları değil, tüm sayfaları içerik karmasıyla eşler.
Bağlantı yeniden yazma, mevcut sürümde iç GoTo eylemlerini algılar ve sayar; tam belgeler arası hedef yeniden çözümlemesi yapmaz. linksRewritten değerini bir algılama sayısı olarak değerlendirin.
Belirlenimcilik. Özdeş girdiler ve yapılandırma için, birleştirilmiş bayt akışı, Pro birleştirme motorunun belgelenmiş belirlenimcilik profiline tabi olarak kararlıdır.

Genel API yüzeyi

Tür	Çeşit	Anahtar üyeler
`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`

Kod örneği — Hızlı başlangıç

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

Kod örneği — Üretim

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

Uç durumlar ve dikkat edilecekler

Tek bir girdi geçerlidir ve o belgenin normalize edilmiş bir kopyasına birleşir.
Yinelenenleri kaldırma, tüm sayfanın bayt içeriğini karşılaştırır; yalnızca üst veriler veya nesne numaralandırması bakımından farklı olan sayfalar, yinelenen olarak değerlendirilmez.
Bir girdideki sayfa aralığı seçimi, birleştirme sıralamasından önce uygulanır.
linksRewritten, algılanan bir eylem sayısıdır; her belgeler arası bağlantı hedefinin yeniden yönlendirildiğinin garantisi değildir.

Performans

Maliyete, Pro birleştirme motoru egemendir ve toplam girdi baytları ile sayfa sayısıyla ölçeklenir. Yinelenenleri kaldırma, sayfa başına bir içerik karması ekler. performance_budget ön bilgisi, birleştirme başına referanstır.

Güvenlik notları

Girdi sayısı ve girdi başına boyut, düşmanca girdilerden kaynaklanan kaynak tükenmesini sınırlamak için SmartMergeConfig ile sınırlandırılır. Birleştirme, gömülü belge betiklerini çalıştırmaz. Bayt akışı ayrıştırma sağlamlaştırması için Core güvenlik modeline bakın.

Uygunluk

İddia	Belirtim kuralı	Durum
`/Outlines` aracılığıyla birleştirilmiş yer imleri	ISO 32000-2:2020 §7.7.2	Doğrulandı (birim paketi)
İçerik karması sayfa yinelenenlerini kaldırma	—	Doğrulandı (birim paketi)
Tam belgeler arası bağlantı yeniden çözümlemesi	—	Desteklenmez (yalnızca algılama)

Core geri dönüşü / alternatifi

Pro birleştirme olmadan temel birleştirme için, açık kaynaklı Core NextPDF\Document\PdfMerger, desteklenen bağımsız yoldur. SmartMerger ona devretmez; Pro birleştirme kendi nesne grafiği motorunda çalışır. Bkz. /modules/core/document/.

Enterprise sınır notu

Bu modül yapısal birleştirme yapar. Hukuki saklama derlemesi, karartma veya delil gözetim zinciri paketlemesi yapmaz; bunlar burada sağlanmaz.

Yayın sınırı

Bu sayfa yalnızca dışarıdan gözlemlenebilen davranışı ve desteklenen genel API yüzeyini açıklar. İç ad alanı yolları, yardımcı sınıflar, mekanizma tabloları, çalıştırma kılavuzu dosya adları ve talep ön ekleri kapsam dışıdır.