Merge — Derinlemesine başvuru

Bir bakışta

Bu sayfa, NextPDF Pro Merge modülü olan NextPDF\Pro\Merge için sözleşme düzeyinde başvurudur. SmartMerger, birkaç giriş belgesini tek bir belgede birleştirir ve Pro zenginleştirmelerini uygular: giriş başına etiketlerden oluşturulan birleştirilmiş bir yer imi ağacı, belge genelinde yinelenenleri kaldırma, giriş başına sayfa aralığı seçimi ve dahili bağlantı algılama. SemanticSplitter, yapı farkında bölme için tamamlayıcı giriş noktasıdır. Bu sayfa, genel API’yi, gözlemlenebilir davranış sözleşmesini, kaynak sınırlarını ve hata modlarını belirtir. Göreve yönelik kurulum ve örnekler Merge yetenek sayfasında yer alır.

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.

Hiçbir çalışma zamanı yetenek bayrağı bu modülü kapılamaz. Merge sınıfları, nextpdf/pro yüklü ve lisanslı olduğunda kullanılabilir.

Genel API yüzeyi

Simge	Parametreler	Varsayılan davranış	Döndürür	Şununla fırlatır veya başarısız olur	Notlar
SmartMerger::__construct()	?PdfMerger $coreMerger = null, ?PdfSplitter $splitter = null	Eski core birleştiriciyi kabul eder ve yok sayar; null bir splitter varsayılan Pro splitter’ı oluşturur	—	—	$coreMerger yalnızca geriye dönük uyumlu yapı için tutulur
SmartMerger::merge()	list<MergeInput> $inputs, SmartMergeConfig $config = new SmartMergeConfig()	Sayfa aralıklarını indirger, girişlerin tamamındaki yinelenenleri kaldırır, temel birleştirmeyi devreder, ardından yapılandırmaya göre yer imlerini enjekte eder ve bağlantıları sayar	SmartMergeResult	Boş bir giriş listesinde InvalidArgumentException; giriş sayısı maxInputs’i aştığında veya bir giriş maxBytesPerInput’i aştığında OverflowException	Tek birleştirme giriş noktası
MergeInput::__construct()	string $pdfData, list<PageRange> $pageRanges = [], string $label = ''	Değer nesnesi; boş bir $pageRanges tüm sayfaları seçer	—	—	Readonly
MergeInput::hasPageRanges()	—	Giriş en az bir sayfa aralığı taşıdığında true	bool	—	—
SmartMergeConfig::__construct()	bool $consolidateBookmarks = true, bool $deduplicatePages = false, bool $rewriteLinks = true, int $maxInputs = 100, int $maxBytesPerInput = 100_000_000	Zenginleştirme anahtarlarını ve kaynak sınırlarını tutan değer nesnesi	—	—	Readonly; yinelenenleri kaldırma isteğe bağlıdır
SmartMergeConfig::default()	—	Yer imleri ve bağlantı taraması açık, yinelenenleri kaldırma kapalı	self	—	Statik fabrika
SmartMergeConfig::basic()	—	Tüm zenginleştirmeler kapalı; yalnızca temel birleştirme	self	—	Statik fabrika
SmartMergeResult::__construct()	string $pdfData, int $totalPages, int $sourceCount, int $mergedSize, int $bookmarksAdded = 0, int $duplicatesRemoved = 0, int $linksRewritten = 0, list<string> $inputLabels = []	Birleştirilmiş baytlar ve birleştirme istatistikleri için readonly taşıyıcı	—	—	Readonly
SmartMergeResult::isValid()	—	Çıktı %PDF başlığıyla başladığında true	bool	—	Yalnızca başlık denetimi
SmartMergeResult::hasOptimizations()	—	Herhangi bir yineleme kaldırıldığında veya herhangi bir bağlantı sayıldığında true	bool	—	—
SemanticSplitter::__construct()	?PdfSplitter $splitter = null	null bir argüman varsayılan Pro splitter’ı oluşturur	—	—	Test için yapıcı enjeksiyonu
SemanticSplitter::splitByStructure()	string $pdfData, float $headingFontThreshold = 14.0	Başlık boyutundaki Tf operatörlerini bölüm başlangıçları olarak algılar ve o sınırlarda böler; algılanan yapı yoksa belge genelinde tek bir bölüm döndürür	SplitResult	Arabellek boş olduğunda veya %PDF başlığı olmadığında InvalidArgumentException; giriş 100 MB’ı aştığında OverflowException	Core sayfa aralığı bölmesine geri döner

Giriş noktası imzaları

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

Davranış sözleşmesi

Birleştirme işlem hattı

SmartMerger::merge() sabit bir işlem hattı çalıştırır; dışarıdan gözlemlendiği şekliyle aşağıdaki gibidir.

1. Boş bir giriş listesi InvalidArgumentException fırlatır. Giriş sayısı ardından maxInputs ile sınırlandırılır; bir taşma OverflowException fırlatır.
2. Her giriş, kullanılmadan önce maxBytesPerInput’e karşı boyut açısından denetlenir. Giriş sayfa aralıkları bildirdiğinde, önce Pro splitter aracılığıyla seçilen sayfalara indirgenir, ardından yalnızca o sayfaları katar.
3. deduplicatePages etkinleştirildiğinde, her giriş belgesinin tam bayt dizisi, kriptografik olmayan xxh128 işleviyle parmak izi olarak alınır. Baytları daha önceki bir girişle tam olarak eşleşen bir giriş atılır. Yinelenenleri kaldırma, belge geneli ve bayt olarak tamdır.
4. Temel birleştirme, her girişi tek bir bitişik nesne alanına yeniden numaralandıran ve gerçek bir çapraz başvuru tablosu yayan Pro PdfSplitter::mergeDocuments() motoruna devredilir.
5. Yer imi birleştirme, consolidateBookmarks etkinleştirildiğinde ve en az bir giriş boş olmayan bir etiket taşıdığında uygulanır. Belge kataloğundan bağlantılanmış, birleştirme sırasına göre giriş başına bir anahat girişi içeren minimal bir /Outlines sözlüğü eklenir.
6. rewriteLinks etkinleştirildiğinde, birleştirilmiş çıktı /S /GoTo eylemleri için taranır ve sayıları bildirilir.

Sonuç istatistikleri

SmartMergeResult, birleştirilmiş baytları ve istatistikleri bildirir. totalPages, temel birleştirmeden gelir. sourceCount, yinelenenleri kaldırmadan önce alınan özgün giriş sayısıdır. mergedSize, çıktı bayt uzunluğudur. bookmarksAdded, yalnızca boş olmayan bir etiket sağlayan girişleri sayar. duplicatesRemoved, atılan tam girişleri sayar. linksRewritten, algılanan GoTo sayısıdır. inputLabels, çözümlenen etiketleri birleştirme sırasına göre listeler. isValid(), %PDF başlığını denetler; hasOptimizations(), bir yineleme kaldırıldığında veya bir bağlantı sayıldığında true olur.

Yer imi başlıkları

Her anahat girişi, giriş etiketini bir /Title olarak taşır; bu, ISO 32000-2:2020 §7.3.4.2 uyarınca bir PDF sabit dizesi olarak kaçışlanır. Ters bölü işareti önce iki katına çıkarılır, parantezler kaçışlanır, adlandırılmış denetim baytları tanımlı dizilerini kullanır ve kalan yazdırılamayan her bayt üç basamaklı sekizli kaçışa dönüşür. Bu nedenle düşmanca bir etiket, sabit dize sınırlayıcısının eşzamanlamasını bozamaz veya nesne yapısı enjekte edemez. Boş etiketli girişler, bir tabanlı olarak indekslenen bir Document N yer tutucu başlığı alır.

Temel birleştirme

Eski Core PdfMerger::merge(), bu sürümde kasıtlı bir fail-closed saplamasıdır; SmartMerger tarafından hiçbir zaman çağrılmaz. Bunun yerine temel birleştirme, Pro PdfSplitter::mergeDocuments() üzerinden çalışır; böylece birleştirilmiş dosya, ISO 32000-2:2020 §7.5.4 uyarınca dolaylı nesne başına bir giriş içeren bayt açısından doğru bir çapraz başvuru tablosu taşır. Belirlenimcilik, Pro splitter’ın belgelenmiş profilini izler: aynı girişler ve yapılandırma kararlı bir bayt akışı üretir.

Yapı farkında bölme

SemanticSplitter::splitByStructure(), sayfa içerik akışlarını headingFontThreshold (varsayılan 14.0) değerinde veya üzerindeki Tf yazı tipi ayarlama operatörleri için tarar ve bu tür her sayfayı bir bölüm başlangıcı olarak değerlendirir. Sınırlar sayfa aralıklarına dönüştürülür ve Pro PdfSplitter::split()’e devredilir. Hiçbir sınır algılanmadığında, belgenin tamamı tek bir bölüm olarak döndürülür. Giriş %PDF ile başlamalı ve 100 MB sınırı içinde kalmalıdır.

Uç durumlar ve hata modları

• Boş bir giriş listesi, herhangi bir birleştirmeden önce InvalidArgumentException ile başarısız olur.
• maxInputs (varsayılan 100) üzerindeki bir giriş sayısı veya maxBytesPerInput (varsayılan 100 MB) üzerindeki herhangi bir giriş, OverflowException ile başarısız olur. Her iki sınır da geçici hatalar değil, kasıtlı fail-closed reddetmelerdir.
• Yinelenenleri kaldırma, belge geneli ve bayt olarak tamdır. Aynı şekilde işlenen ancak herhangi bir baytta farklılık gösteren iki giriş de korunur ve duplicatesRemoved, sayfa odaklı deduplicatePages adına rağmen atılan tam girişleri sayar.
• sourceCount, yinelenenleri kaldırma sonrası belge sayısını değil, özgün giriş sayısını yansıtır.
• Yer imi birleştirme, yalnızca en az bir giriş boş olmayan bir etikete sahip olduğunda tetiklenir. consolidateBookmarks true ancak her etiket boş olduğunda, hiçbir /Outlines nesnesi yazılmaz.
• Enjekte edilen anahat girişleri başlıkları ve /Parent, /Prev, /Next ağaç bağlantılarını taşır; bu sürümde açık /Dest hedefleri gömmezler.
• Bağlantı yeniden yazma yalnızca /S /GoTo eylemlerini sayar; yeniden numaralandırılan nesneler arasında hedefleri yeniden işaret etmez. linksRewritten’ı bir algılama sayısı olarak değerlendirin.
• SemanticSplitter algılaması sözcükseldir. Tf yazı tipi boyutu operatörlerine dayanır; bu nedenle yalnızca görüntü içeren veya olağandışı kodlanmış sayfalar hiçbir sınır üretmez ve belge genelinde tek bir bölüm döndürür.

FIPS modu davranışı

Bu modülde hiçbir kriptografik işlem gerçekleşmez, bu nedenle FIPS moduna özgü bir davranış yoktur. Yinelenenleri kaldırmak için kullanılan xxh128 içerik parmak izi, kriptografik olmayan bir değişiklik algılama karmasıdır ve hiçbir bütünlük veya kanıt ağırlığı taşımaz.

Uygunluk

İddia	Standart	Madde
Belge kataloğundan bağlantılanan bir /Outlines sözlüğü olarak yazılan birleştirilmiş yer imleri	ISO 32000-2:2020	§7.7.2
Temel birleştirme, her dolaylı nesne için bayt açısından doğru bir çapraz başvuru tablosu yayar	ISO 32000-2:2020	§7.5.4
Ters bölü ve parantez işlemesiyle PDF sabit dizeleri olarak kaçışlanan anahat girişi başlıkları	ISO 32000-2:2020	§7.3.4.2
Belgeler arası tam bağlantı yeniden çözümlemesi	—	Desteklenmiyor (yalnızca GoTo algılama)
Bölüm başına açık anahat hedefleri	—	Bu sürümde yayılmıyor

Tüm maddeler başka sözcüklerle ifade edilmiştir; NextPDF normatif metni yeniden üretmez. Bunlar sertifikalar değil, yetenek beyanlarıdır; NextPDF hiçbir sertifikaya sahip değildir ve hiçbir sertifika vermez.

Geliştirme notları

• Pro paketi içindeki kullanılabilirlik: SmartMerger, MergeInput, SmartMergeConfig, SmartMergeResult ve SemanticSplitter 2.2.0’dan beri. Tümü nextpdf/pro 3.1.0’da günceldir.
• Temel birleştirme, Pro PdfSplitter::mergeDocuments()’a devreder. Eski Core PdfMerger::merge(), bu sürümde bir fail-closed saplamasıdır ve hiçbir zaman çağrılmaz.
• deduplicatePages’i yalnızca girişler bayt olarak aynı tam belgeler olabileceğinde etkinleştirin; yakın yinelenen veya yeniden kodlanmış kopyaları daraltmaz.
• Saf birleştirme için SmartMergeConfig::basic(), yer imleri ve bağlantı taraması için ::default() kullanın.
• Güvenilmeyen girişleri birleştirirken OverflowException’ı yakalayın; sayı ve boyut sınırları kasıtlı reddetmelerdir.
• Basit sayfa aralığı bölmesi için doğrudan Pro PdfSplitter’ı tercih edin; SemanticSplitter’a yalnızca başlık odaklı bölümleme gerektiğinde başvurun.

Yayın sınırı

Bu sayfa yalnızca dışarıdan gözlemlenebilir davranışı ve desteklenen genel API yüzeyini belgeler. Dahili ad alanı yolları, yardımcı sınıflar, mekanizma tabloları, runbook dosya adları ve bilet önekleri kapsam dışıdır.

Ayrıca bkz.

• Merge (yetenek) — kurulum, hızlı başlangıç ve üretim örnekleri.
• Toc — Derinlemesine başvuru
• Diff — Derinlemesine başvuru
• Document — Derinlemesine başvuru — Pro splitter ve temel birleştirme motoru.